HPC Plans Summary API - UN-OCHA/hpc-api GitHub Wiki
The HPC Plans Summary API is an analytical tool designed to leverage HPC data and can be customized to suit various contexts. It includes for each plan the following datasets:
-
Overview Information: High level summary information about the plan, such as:
- Plan Id
- Plan Name
- Plan Type
- Plan Costing Type
- Plan Year
- Last Published Date
- Plan Start Date
- Plan End Date
- Plan Countries
-
organizations: Includes the organizations involved with the plan. Organizations can be the partners submitting projects, partners receiving funds and donors sending funds.
-
planClusters: Includes all field clusters activated which have caseloads and financial requirements.
-
planGlobalClusters: Global clusters associated with plan clusters which have caseloads and financial requirements.
-
planEntities: Includes both strategic and clusters framework entities including objectives and activities such as Strategic Objectives, Cluster Objectives and Cluster Activities.
-
monitoringPeriods: Monitoring periods defined for the plan. This field only includes information about the monitoring period but not the monitoring data themselves
-
caseloads are metrics relating to populations, such as:
- Total population
- People affected
- People in need
- People targeted by plan
In addition to their measurements such as reached population, cumulative reached populations...etc. or corresponding terms in French such as Atteint, cumulAttaint...etc.
-
indicators are more general, and can be used to track progress. Data captured for indicators are the indicators descriptions, metrics such as Indicator target, and their measurements such as Indicator measure.
-
financialData: Includes all financial requirements and funding details related to plan, such as:
- Requirements: broken down by plan cluster, global cluster (with many-to-many relationship with the plan cluster), and by organization. The breakdown by organization can be empty if the plan has no projects.
- Funding: broken down by plan cluster, global cluster (with many-to-many relationship with the plan cluster), and by receiving organization and by donor.
Getting Started using the Response Monitoring Tool API
Using the API Directly
Request
API requests should be GET requests to the following URL:
https://api.hpc.tools/v2/public/planSummary?year=[year]
With the following query parameters:
| Parameter | Required / Default Value | Details |
|---|---|---|
year |
Required | The year you wish to get plans data for. |
includeIndicators |
Optional (default: false) |
Set to true if indicator data should be included |
includeCaseloads |
Optional (default: false) |
Set to true if caseload data should be included |
includeFinancials |
Optional (default: false) |
Set to true if financial data should be included |
For example, requests could look like the following:
-
GET https://api.hpc.tools/v2/public/planSummary?year=2023 -
GET https://api.hpc.tools/v2/public/planSummary?year=2023&includeIndicators=true&includeCaseloads=true&includeFinancials=true
Response
Responses will look something like this, the exact shape of the data will depend
on which parameters you have set to true above.
{
"data": {
"totalGHOPlans": 45,
"totalGHOCountries": 74,
"usageInfo": "The plan summary API is an interface that provides the humanitarian community and others with direct access to Humanitarian Appeals data. This valuable information, managed by country teams through HPC Tools, is also accessible on public platforms like https://humanitarianaction.info/ and https://fts.unocha.org/. For more information about HPC Tools, please visit https://kmp.hpc.tools/hpc-tools/. Detailed instructions on utilizing the API can be found in its documentation, available at https://github.com/UN-OCHA/hpc-api/wiki",
"planData": [
{
"planId": 1109,
"name": "Occupied Palestinian Territory Humanitarian Response Plan 2023",
"planType": "Humanitarian response plan",
"planCostingType": "Unit-Based costed requirements - with projects",
"includedGHO": true,
"planYear": "2023",
"lastPublishedVersion": "4.0",
"lastPublishedDate": "22/11/2023",
"lastPublishedComment": "HRP Req decreased by %25, end date modified to 30/09 - costing type",
"planStartDate": "01/01/2023",
"planEndDate": "30/09/2023",
"planCountries": [
{
"id": 171,
"iso3": "PSE",
"country": "occupied Palestinian territory",
"latitude": 31.990841420042,
"longitude": 35.307440467367
}
],
"planClusters": [
{
"clusterId": 6760,
"clusterName": "Coordination and Support Services",
"clusterCustomRef": "CLCSS"
},
{
"clusterId": 6767,
"clusterName": "Multi-cluster/Multi-Purpose Cash",
"clusterCustomRef": "CLMS"
}
],
"planGlobalClusters": [
{
"planClusters": [
6762
],
"globalClusterId": 3,
"globalClusterCode": "EDU",
"globalClusterName": "Education",
"globalClusterType": "global"
},
{
"planClusters": [
6765
],
"globalClusterId": 4,
"globalClusterCode": "SHL",
"globalClusterName": "Emergency Shelter and NFI",
"globalClusterType": "global"
}
],
"planEntities": [
{
"id": 21127,
"type": "CA",
"entityRef": "CLHEA/CA2",
"entityDescription": "Enhancing community engagement and adherence to vaccination in affected areas",
"supports": [
21121
],
"planCluster": 6821
},
{
"id": 20977,
"type": "CO",
"entityRef": "CLEDU/CO2",
"entityDescription": "Provision of alternative education platforms",
"supports": [
20304
],
"planCluster": 6819
},
{
"id": 20299,
"type": "SO",
"entityRef": "SO1",
"entityDescription": "Reduce the mortality and morbidity of 1.3 million people affected by crisis",
"supports": [],
"planCluster": null
},
{
"id": 20302,
"type": "SP",
"entityRef": "SP1.1",
"entityDescription": "1.3 million vulnerable people affected by crisis benefit from inclusive, lifesaving and timely food, nutrition, WASH, shelter, NFI, and health services by the end of 2023",
"supports": [
20299
],
"planCluster": null
}
],
"monitoringPeriods": [
{
"id": 2368,
"periodNumber": 1,
"periodName": "MP1",
"startDate": "01/01/2023",
"endDate": "30/06/2023"
},
{
"id": 2369,
"periodNumber": 2,
"periodName": "MP2",
"startDate": "01/07/2023",
"endDate": "31/12/2023"
}
]
},
{
"planId": 1110,
"name": "Nigeria Humanitarian Response Plan 2023",
"planType": "Humanitarian response plan",
"planCostingType": "Unit-Based costed requirements - with projects",
"includedGHO": true,
"planYear": "2023",
"lastPublishedVersion": "1.23",
"lastPublishedDate": "22/01/2024",
"lastPublishedComment": "Publish MP11 and open MP12",
"planStartDate": "01/01/2023",
"planEndDate": "31/12/2023",
"planCountries": [
{
"id": 163,
"iso3": "NGA",
"country": "Nigeria",
"latitude": 9.58605,
"longitude": 8.09237
}
],
"planClusters": [
{
"clusterId": 6768,
"clusterName": "Camp Coordination and Camp Management",
"clusterCustomRef": "CLCCM"
},
{
"clusterId": 6780,
"clusterName": "Multi-Purpose Cash",
"clusterCustomRef": "CLMS"
}
],
"planGlobalClusters": [
{
"planClusters": [
6768
],
"globalClusterId": 1,
"globalClusterCode": "CCM",
"globalClusterName": "Camp Coordination / Management",
"globalClusterType": "global"
}
],
"monitoringPeriods": [
{
"id": 2596,
"periodNumber": 1,
"periodName": "Jan",
"startDate": "01/01/2023",
"endDate": "31/01/2023"
},
{
"id": 2597,
"periodNumber": 2,
"periodName": "Feb",
"startDate": "01/02/2023",
"endDate": "28/02/2023"
}
]
}],
"meta": {
"language": "en"
}
},
"status": "ok"
}
More Detailed Data
When the includeIndicators, includeCaseloads and/or includeFinancials flag is set to true, the data will include the additional information when that data is available.
The value of such property looks something like this:
{
"data": {
"totalGHOPlans": 45,
"totalGHOCountries": 74,
"usageInfo": "The plan summary API is an interface that provides the humanitarian community and others with direct access to Humanitarian Appeals data. This valuable information, managed by country teams through HPC Tools, is also accessible on public platforms like https://humanitarianaction.info/ and https://fts.unocha.org/. For more information about HPC Tools, please visit https://kmp.hpc.tools/hpc-tools/. Detailed instructions on utilizing the API can be found in its documentation, available at https://github.com/UN-OCHA/hpc-api/wiki",
"planData": [
{
"planId": 1109,
"name": "Occupied Palestinian Territory Humanitarian Response Plan 2023",
"planType": "Humanitarian response plan",
"planCostingType": "Unit-Based costed requirements - with projects",
"includedGHO": true,
"planYear": "2023",
"lastPublishedVersion": "4.0",
"lastPublishedDate": "22/11/2023",
"lastPublishedComment": "HRP Req decreased by %25, end date modified to 30/09 - costing type",
"planStartDate": "01/01/2023",
"planEndDate": "30/09/2023",
"planCountries": [
{
"id": 171,
"iso3": "PSE",
"country": "occupied Palestinian territory",
"latitude": 31.990841420042,
"longitude": 35.307440467367
}
],
"organizations": [
{
"id": 8957,
"name": "ACT Alliance / Dan Church Aid - Norwegian Church Aid Joint office in Palestine",
"abbreviation": "ACT/DCA-NCA Palestine",
"url": "https://www.kirkensnodhjelp.no/en/where-we-work/palestine-and-israel/",
"orgType": "NGOs",
"orgSubtype": "Internationally Affiliated Organizations"
},
{
"id": 928,
"name": "Yesh Din - Volunteers for Human Rights",
"abbreviation": "Yesh Din",
"url": "http://www.yesh-din.org/",
"orgType": "NGOs",
"orgSubtype": "National NGOs/CSOs"
}
],
"planClusters": [
{
"clusterId": 6760,
"clusterName": "Coordination and Support Services",
"clusterCustomRef": "CLCSS"
},
{
"clusterId": 6767,
"clusterName": "Multi-cluster/Multi-Purpose Cash",
"clusterCustomRef": "CLMS"
}
],
"planGlobalClusters": [
{
"planClusters": [
6762
],
"globalClusterId": 3,
"globalClusterCode": "EDU",
"globalClusterName": "Education",
"globalClusterType": "global"
},
{
"planClusters": [
6760
],
"globalClusterId": 26480,
"globalClusterCode": "CSS",
"globalClusterName": "Coordination and support services",
"globalClusterType": "custom"
}
],
"planEntities": [
{
"id": 21127,
"type": "CA",
"entityRef": "CLHEA/CA2",
"entityDescription": "Enhancing community engagement and adherence to vaccination in affected areas",
"supports": [
21121
],
"planCluster": 6821
},
{
"id": 20977,
"type": "CO",
"entityRef": "CLEDU/CO2",
"entityDescription": "Provision of alternative education platforms",
"supports": [
20304
],
"planCluster": 6819
},
{
"id": 20299,
"type": "SO",
"entityRef": "SO1",
"entityDescription": "Reduce the mortality and morbidity of 1.3 million people affected by crisis",
"supports": [],
"planCluster": null
},
{
"id": 20302,
"type": "SP",
"entityRef": "SP1.1",
"entityDescription": "1.3 million vulnerable people affected by crisis benefit from inclusive, lifesaving and timely food, nutrition, WASH, shelter, NFI, and health services by the end of 2023",
"supports": [
20299
],
"planCluster": null
}
],
"monitoringPeriods": [
{
"id": 2704,
"periodNumber": 1,
"periodName": "Q1",
"startDate": "01/01/2023",
"endDate": "31/03/2023"
},
{
"id": 2705,
"periodNumber": 2,
"periodName": "Q2",
"startDate": "01/04/2023",
"endDate": "30/06/2023"
},
{
"id": 2706,
"periodNumber": 3,
"periodName": "Q3",
"startDate": "01/07/2023",
"endDate": "30/09/2023"
},
{
"id": 2707,
"periodNumber": 4,
"periodName": "Q4",
"startDate": "01/10/2023",
"endDate": "31/12/2023"
}
],
"caseloads": [
{
"caseloadId": 36340,
"caseloadCustomRef": "BP1",
"caseloadType": "plan",
"caseloadDescription": "Final HRP caseload",
"entityId": null,
"totalPopulation": 109568891,
"affected": null,
"inNeed": 26429388,
"target": 10026830,
"expectedReach": 7150000,
"measurements": [
{
"monitoringPeriodId": 2706,
"atteints": null,
"cumulAtteints": 5457744,
"couverts": null
},
{
"monitoringPeriodId": 2707,
"atteints": null,
"cumulAtteints": 6913268,
"couverts": null
},
{
"monitoringPeriodId": 2705,
"atteints": "",
"cumulAtteints": 4270413,
"couverts": null
},
{
"monitoringPeriodId": 2704,
"atteints": null,
"cumulAtteints": 2518769,
"couverts": null
}
]
}
],
"indicators": [
{
"indicatorId": 42106,
"indicatorCustomRef": "CLCCM/CO1/IN1",
"indicatorDescription": "# de personnes vivant dans des sites gérés ayant bénéficié d'une assistance multisectorielle",
"clusterId": 6815,
"planEntityId": 23029,
"unit": "People",
"calculationMethod": "Latest value",
"target": 364931,
"measurements": [
{
"monitoringPeriodId": 2706,
"mesure": 745866
},
{
"monitoringPeriodId": 2707,
"mesure": 749878
},
{
"monitoringPeriodId": 2704,
"mesure": 630825
},
{
"monitoringPeriodId": 2705,
"mesure": 704027
}
]
},
{
"indicatorId": 42107,
"indicatorCustomRef": "CLCCM/CO2/IN1",
"indicatorDescription": "# de sites profilés et avec la population enregistrée",
"clusterId": 6815,
"planEntityId": 23030,
"unit": "Sites",
"calculationMethod": "Latest value",
"target": 46,
"measurements": [
{
"monitoringPeriodId": 2706,
"mesure": 247
},
{
"monitoringPeriodId": 2707,
"mesure": 248
},
{
"monitoringPeriodId": 2705,
"mesure": 184
},
{
"monitoringPeriodId": 2704,
"mesure": 159
}
]
}
],
"financialData": {
"requirements": {
"totalRequirements": 376729201,
"breakdown": {
"byCluster": [
{
"clusterId": 6760,
"requirements": 9533315
},
{
"clusterId": 6761,
"requirements": 209809128
}
],
"byGlobalCluster": [
{
"globalClusterId": 26480,
"requirements": 9533315
},
{
"globalClusterId": 26479,
"requirements": 14247547
}
],
"byOrganization": {
"3": [
{
"clusterId": 6760,
"globalClusterId": 26480,
"requirements": 700000
}
],
"12686": [
{
"clusterId": 6766,
"globalClusterId": 11,
"requirements": 350000
}
]
}
}
},
"funding": {
"totalFundingInsidePlan": 377669403,
"totalFundingOutsidePlan": 974008472,
"totalPledges": 0,
"breakdown": {
"byCluster": [
{
"clusterId": 6760,
"funding": 5046348
},
{
"clusterId": "Not specified",
"funding": 15090744
}
],
"byGlobalCluster": [
{
"globalClusterId": 10,
"funding": 18258223
},
{
"globalClusterId": "Multiple global clusters (shared)",
"funding": 1795228
}
],
"byDonor": [
{
"organizationId": 100,
"funding": 16486486
},
{
"organizationId": 92,
"funding": 50000
}
],
"byOrganization": [
{
"organizationId": 2178,
"funding": 26167773
},
{
"organizationId": 6461,
"funding": 394527
}
]
}
}
}
}
],
"meta": {
"language": "en"
}
},
"status": "ok"
}
Configuration:
The first time you load data, you will be asked how you want to authenticate with the API. Given that this API includes unpublished data, you will need to log-in as yourself using HID. To do so, generate a HID Token using the instructions here.