Getting Plan Requirements - UN-OCHA/hpc-api GitHub Wiki

The API endpoints presented here are currently the v2 endpoints, which are optimized for data-entry applications like RPM, rather than for consumption by external API users. As a result, they do not currently provide this data in an efficient manner.

This is something that we're in the process of addressing in the design and development of the next version of the HPC API, which you can read more about under the section Upcoming Changes to the API.

This document will be updated once it's possible to retrieve this data using the new API.

If you would like to be notified once this is possible, please see the section Keeping Up-To-Date below.

Not all plans provide cost requirements to the same level of detail. Exactly how much detail that is available depends on many factors, including which stage of the planning process a particular plan is in.

The types of costing methods that may be found for plans in HPC.tools are:

• Overall Plan Requirements:

  Only a single "overall" figure is available for the whole plan

• Cluster requirements only without projects:

  Requirements are available on a per cluster/sector basis. The overall financial requirements are calculated by adding up all of the cluster/sector requirements. (This will usually also include a breakdown of cost per AoR)

• Cluster requirements with project planning:

  Requirements are available on a per cluster/sector basis. The overall financial requirements are calculated by adding up all of the cluster/sector requirements.

  In addition, some more granular requirements data may be available on a per-project basis (with organization and cluster / sector breakdowns), but these projects are unlikely to cover the entire scope of a plan's budget.

• Project requirements:

  Requirements are available on a per-project basis, and also include organization and cluster / sector breakdowns.

  Project budgets are then summed-up to to calculate the overall cluster/sector and plan requirements.

Regardless of costing method used, it's always possible to get the overall requirements for a particular plan. This figure is usually provided whenever you make an API call that includes plan details.

For example, it is provided when getting all plans for a given year.

This is not available for plans that use Overall Plan Requirements.

TODO

This is not available for plans that use Overall Plan Requirements or Cluster requirements only without projects.

There are two ways to retrieve the budget breakdown for projects.

• You can get the breakdown for an individual project:

  https://api.hpc.tools/v2/public/projectDetails?includeBudgetByOrg=true&mode=project&projectId=<project id>
  

• Or you can get the breakdown for all projects of a particular plan:

  https://api.hpc.tools/v2/public/projectDetails?includeBudgetByOrg=true&mode=plan&planId=<plan id>
  

The API will respond with something that looks like this:

{
  "data": {
    "projects": [
      {
        "id": 179984,
        "budgetByOrg": [
          {
            "amountUSD": 7500,
            "globalCluster": 6,
            "governingEntity": 5958,
            "organization": 10992
          },
          // ...
        ]
      },
      {
        "id": 179985,
        "budgetByOrg": [
          {
            "amountUSD": 500,
            "globalCluster": 6,
            "governingEntity": 5958,
            "organization": 11834
          },
          // ...
        ]
      },
      // ...
    ],
    "meta": {
      "language": "en"
    }
  },
  "status": "ok"
}

Each entry in "projects" represents a different project in project module, and "budgetByOrg" includes a breakdown of the budget, with the following fields:

• "organization": The numeric ID of the organization on our system. (The endpoint /v1/public/organization can be used to get the full list of organizations on the HPC.tools system)

• "governingEntity": The ID of the cluster / sector of a plan that this budget segment is for.

  Each plan has it's own specific clusters / sectors defined, the list of these (along with their IDs) can be found in a number of different endpoints, including when Getting Cluster / Sector Caseload Data

• "globalCluster": The global cluster or AoR associated with this budget segment. (The endpoint /v1/public/global-cluster can be used to get the full list of global clusters / AoRs on the HPC.tools system)

  In most cases, clusters / sectors (i.e. the value for governingEntity) are associated with a single global cluster, meaning that there is usually only one possible value for "globalCluster", which is not useful. However in some cases (such as Protection Clusters), they are associated with multiple AoRs, and in these cases we can provide budget breakdowns on a per-AoR basis.

The project 174913 has the following budget:

And calling this endpoint:

https://api.hpc.tools/v2/public/projectDetails?includeBudgetByOrg=true&mode=project&projectId=174913

Will return the following:

{
    "data": {
        "projects": [
            {
                "id": 174913,
                "budgetByOrg": [
                    {
                        "amountUSD": 2500000,
                        "globalCluster": 11,
                        "governingEntity": 5998,
                        "organization": 4279
                    },
                    {
                        "amountUSD": 1250000,
                        "globalCluster": 13,
                        "governingEntity": 5997,
                        "organization": 4279
                    },
                    {
                        "amountUSD": 1250000,
                        "globalCluster": 12,
                        "governingEntity": 5997,
                        "organization": 4279
                    },
                    {
                        "amountUSD": 2500000,
                        "globalCluster": 9,
                        "governingEntity": 5996,
                        "organization": 4279
                    },
                    {
                        "amountUSD": 2500000,
                        "globalCluster": 7,
                        "governingEntity": 5995,
                        "organization": 4279
                    }
                ]
            }
        ],
        "meta": {
            "language": "en"
        }
    },
    "status": "ok"
}

• Organization 4279 refers to "Family Health International"
• The following Governing Entities & Global Clusters are used:
  • Governing Entity 5995 - Health
    • Global Cluster 7 - Health
  • Governing Entity 5996 - Nutrition
    • Global Cluster 9 - Nutrition
  • Governing Entity 5997 - Protection
    • Global Cluster 12 - Protection - Child Protection
    • Global Cluster 13 - Protection - Gender-Based Violence
  • Governing Entity 5998 - Water and Sanitation
    • Global Cluster 11 - Water Sanitation Hygiene