HPC Response Monitoring Analysis API - UN-OCHA/hpc-api GitHub Wiki
The HPC Response Monitoring API is analytical tool designed to leverage HPC data and can be customized to suit various contexts. It includes for each plan the following datasets:
-
Plan Clusters: Includes all clusters activated which have caseloads and financial requirements.
-
Organizations: Includes the organizations involved with the plan. Organizations can be the partners submitting projects, partners receiving funds and donors sending funds.
-
Locations: Includes all updates CODs at all Admin levels of the plan
-
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.
-
financial Data: 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/plan/[planId]/responseMonitoring
With the following query parameters:
| Parameter | Required / Default Value | Details |
|---|---|---|
planId |
Required | The numeric ID of the plan you wish to get data for. |
includeCaseloadDisaggregation |
Optional (default: false) |
Set to true if caseload disaggregated data should be included |
includeIndicatorDisaggregation |
Optional (default: false) |
Set to true if indicators disaggregated should be included |
disaggregationOnlyTotal |
Optional (default: true) |
If set to true (and includeCaseloadDisaggregation/includeIndicatorDisaggregation also set to true), this fetches data disaggregated by locations and by categories such as SAAD, population type. Otherwise, if set to false, it fetches only the Total values, disaggregated by location. |
For example, requests could look like the following:
-
GET https://demo.api-hpc-tools.ahconu.org/v2/plan/1174/responseMonitoring -
GET https://demo.api-hpc-tools.ahconu.org/v2/plan/1174/responseMonitoring?includeCaseloadDisaggregation=true&includeIndicatorDisaggregation=true&disaggregationOnlyTotal=false
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": {
// These are plan description fields
"planId": 1114,
"name": "Syrian Arab Republic Humanitarian Response Plan 2023",
"planType": "Humanitarian response plan",
"planCostingType": "Cluster requirements with project planning",
"planYear": "2023",
"lastPublishedVersion": "4.2",
"lastPublishedDate": "11/05/2023",
"lastPublishedComment": "Custom publish for revised HRP.",
"planCountries": [
{
"id": 218,
"iso": "SYR",
"country": "Syrian Arab Republic"
}
],
// The list of all organizations relevant to the plan data
"organizations": [
{
"id": 8094,
"name": "Basmeh and Zeitooneh for Relief and Development - Gülümseme ve Zeytin",
"abbreviation": "B&Z",
"url": "http://www.basmeh-zeitooneh.org/",
"orgType": "NGOs",
"orgSubtype": "National NGOs/CSOs"
},
{
"id": 8068,
"name": "Al-Bir Wa Al-Ehsan Association in Ras AlAin",
"abbreviation": "Al-Bir Wa Al-Ehsan",
"url": "https://www.facebook.com/salbrrasalain",
"orgType": "NGOs",
"orgSubtype": "National NGOs/CSOs"
}
],
// This includes all clusters activated which has caseloads and financial requirements
"planClusters": [
{
"clusterId": 6959,
"clusterName": "Protection",
"clusterCustomRef": "CLPRO"
},
{
"clusterId": 6966,
"clusterName": "Logistics",
"clusterCustomRef": "CLLOG"
},
{
"clusterId": 6962,
"clusterName": "Food Security and Agriculture",
"clusterCustomRef": "CLFSC"
}
],
// This list includes all Global Clusters linked to Plan Clusters
"planGlobalClusters": [
{
"planClusters": [6959],
"globalClusterId": 15,
"globalClusterCode": "PRO-MIN",
"globalClusterName": "Protection - Mine Action",
"globalClusterType": "aor"
},
{
"planClusters": [6959],
"globalClusterId": 13,
"globalClusterCode": "PRO-GBV",
"globalClusterName": "Protection - Gender-Based Violence",
"globalClusterType": "aor"
}
],
// List of Plan Entities including links between them maintained through the field "Supports" and the relevant clusters they belong to. planCluster with null value means the PlanEntities are not linked to clusters but to strategic framework:
"planEntities": [
{
"id": 20370,
"type": "CA",
"entityRef": "CLEDU/CA13",
"entityDescription": "Activity 10: Provide solar power system in schools",
"supports": [20341],
"planCluster": 6961
},
{
"id": 20783,
"type": "CO",
"entityRef": "CLMS/CO2",
"entityDescription": "MPC Objective 3.1: Most vulnerable HHs near markets reducing reliance on negative coping strategies over time",
"supports": [20230],
"planCluster": 6968
},
{
"id": 20784,
"type": "CA",
"entityRef": "CLMS/CA1",
"entityDescription": "MPC Activity 1.1: Deliver emergency MPC* to the most vulnerable",
"supports": [20782],
"planCluster": 6968
}
],
// This list has all updates CODs for all Admin levels of the plan:
"locations": [
{
"id": 218,
"name": "Syrian Arab Republic",
"adminLevel": 0,
"pcode": "SY",
"latitude": 35.011051885705,
"longitude": 38.511238049703
},
{
"id": 25801539,
"name": "Tartous",
"adminLevel": 1,
"pcode": "SY10",
"latitude": 34.959426,
"longitude": 36.077933
},
{
"id": 25801540,
"name": "Ar-Raqqa",
"adminLevel": 1,
"pcode": "SY11",
"latitude": 36.01153,
"longitude": 38.994679
},
{
"id": 25864980,
"name": "Kayariyeh",
"adminLevel": 4,
"pcode": "C1310",
"latitude": 36.193502,
"longitude": 37.707559
},
{
"id": 25865000,
"name": "Rasm Elkibir - Ilkana",
"adminLevel": 4,
"pcode": "C1312",
"latitude": 36.220867,
"longitude": 37.64228
}
],
// List of monitoring periods that include measurements reporting
"monitoringPeriods": [
{
"id": 2396,
"periodNumber": 3,
"periodName": "Q3",
"startDate": "01/07/2023",
"endDate": "30/09/2023"
},
{
"id": 2394,
"periodNumber": 1,
"periodName": "Q1",
"startDate": "01/01/2023",
"endDate": "31/03/2023"
}
],
// This list includes caseloads metrics such as People in Need, People target, and measurement such as Reach, cumulative reach, and the disaggregation by locations and other categories:
"caseloads": [
{
"caseloadId": 41531,
"caseloadCustomRef": "CLERY/BF1",
"caseloadType": "cluster",
"caseloadDescription": "Early Recovery and Livelihoos",
"entityId": 6960,
"inNeed": 15303316,
"target": 5900000,
"measurements": []
},
{
"caseloadId": 41532,
"caseloadCustomRef": "CLEDU/BF1",
"caseloadType": "cluster",
"caseloadDescription": "Education",
"entityId": 6961,
"inNeed": 6879939,
"target": 4889027,
"measurements": []
},
{
"caseloadId": 41535,
"caseloadCustomRef": "CLFSC/BF1",
"caseloadType": "cluster",
"caseloadDescription": "Food Security",
"entityId": 6962,
"inNeed": 15044409,
"target": 14200000,
"measurements": []
}
],
// This list includes indicators such as indicators description, target, and measurement such as indicator measure, and the disaggregation by locations and other categories:
"indicators": [
{
"indicatorId": 37220,
"indicatorCustomRef": "CLPRO/CA3.1/IN3.1.3",
"indicatorDescription": "Number of male and female GBV actors trained on GBV",
"clusterId": 6959,
"planEntityId": 20331,
"unit": "People",
"calculationMethod": "Latest value",
"target": 4940,
"measurements": []
},
{
"indicatorId": 37228,
"indicatorCustomRef": "CLPRO/CA4.2/IN4.2.3",
"indicatorDescription": "square meters of land cleared or rendered safe",
"clusterId": 6959,
"planEntityId": 20335,
"unit": "Numbers",
"calculationMethod": "Latest value",
"target": 11704000,
"measurements": []
},
{
"indicatorId": 37219,
"indicatorCustomRef": "CLPRO/CA3.1/IN3.1.2",
"indicatorDescription": "Number of GBV response services provided to GBV survivors and women and girls at risk",
"clusterId": 6959,
"planEntityId": 20331,
"unit": "Services",
"calculationMethod": "Latest value",
"target": 468000,
"measurements": []
},
{
"indicatorId": 37221,
"indicatorCustomRef": "CLPRO/CA3.2/IN3.2.1",
"indicatorDescription": "Number of women, men, girls and boys reached by GBV prevention and empowerment activities",
"clusterId": 6959,
"planEntityId": 20332,
"unit": "People",
"calculationMethod": "Latest value",
"target": 1695000,
"measurements": []
}
],
// Includes all financial requirements and funding details related to plan, broken down by Plan cluster, global cluster (with many-to-many relationship with the Plan cluster), and by organization in addition to the funding by donor.
"financialData": {
"requirements": {
"totalRequirements": 5413802598,
"breakdown": {
"byCluster": [
{
"clusterId": 6967,
"requirements": 500000
},
{
"clusterId": 6966,
"requirements": 11482648
}
],
"byGlobalCluster": [
{
"globalClusterId": 26480,
"requirements": 41549258
},
{
"globalClusterId": 1,
"requirements": 23027392
},
{
"globalClusterId": 15,
"requirements": 64724355
}
],
"byOrganization": {
"8": [
{
"clusterId": 6963,
"globalClusterId": 7,
"requirements": 7098929
},
{
"clusterId": 6961,
"globalClusterId": 3,
"requirements": 1963209
}
],
"47": [
{
"clusterId": 6965,
"globalClusterId": 11,
"requirements": 4047076
},
{
"clusterId": 6963,
"globalClusterId": 7,
"requirements": 2851486
}
]
},
"funding": {
"totalFundingInsidePlan": 1591170227,
"totalCountryFunding": 2687492333,
"totalPledges": 445526,
"breakdown": {
"byCluster": [
{
"clusterId": 6816,
"funding": 17324049
},
{
"clusterId": 6959,
"funding": 137898318
}
],
"byGlobalCluster": [
{
"globalClusterId": 10,
"funding": 102172122
},
{
"globalClusterId": 11,
"funding": 140244121
},
{
"globalClusterId": 12,
"funding": 16913918
}
],
"byDonor": [
{
"organizationId": 100,
"funding": 15314300
},
{
"organizationId": 11164,
"funding": 30266
},
{
"organizationId": 1196,
"funding": 92840
}
]
}
}
},
"meta": {
"language": "en"
}
},
"status": "ok"
}
}
}
Disaggregated Data
When the includeCaseloadDisaggregation and/or includeIndicatorDisaggregation flag is set to true, caseload and/or indicator items will include a disaggregated property when that data is available.
The value of such property looks something like this:
{
/**
* For Attachmentsdisaggregation: location IDs used in addition to categories used for this disaggregation and array of dataMatrix of people in Need and targets,
* For disaggregatedMeasurementsArray: location IDs used in addition to categories used for this disaggregation and array of dataMatrix of measurements such as reach, comulative reach, or Attient, cumulAttent in French ...etc.
*/
"disaggregatedAttachments": [
{
"locationId": 25818257,
"categoryLabel": "total",
"categoryName": "Total",
"dataMatrix": [
{
"metricType": "target",
"value": 59828
}
]
}
],
"measurements": [
{
"monitoringPeriodId": 2337,
"reached": null,
"cumulativeReach": null,
"covered": null,
"disaggregatedMeasurements": []
},
{
"monitoringPeriodId": 2338,
"reached": null,
"cumulativeReach": null,
"covered": null,
"disaggregatedMeasurements": []
}
]
}
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.