Data API

This API is used to retrieve various analytical data, including IU, site level, and forecast data. It powers all of the data downloads available on the ESPEN Portal.

There are two required params, disease and level. It is advisable to filter the data by country as well, by passing in the iso2 or country param.

Learn more about accessing IU Forecast data below.

GET /api/data?{params}

Return a list of data filtered on the params that are passed in. There are two required params: disease and level. Accepts limit and offset params to enable paging.

Params


    country: country name, e.g. Ghana
    iso2: country ISO2 code, e.g. GH
    disease: { lf | oncho | loa | sch | sth | trachoma | coendemicity }
    level: { iu | sitelevel }
    type: { forecast }
    subtype: { mda | impact_assessment }

    # to specify a year range, both params are required
    start_year: year to start, inclusive
    end_year: year to end, inclusive

    # page through the data
    limit: how many records to return
    offset: how many records to skip

    # return only these attributes
    attributes: e.g. IU_ID,Endemicity,MDA,EffMDA

Response

IU-level


    e.g. /api/data?iso2=GH&disease=lf&level=iu

    [
      {
        "WHO_region": "AFRO",
        "Country": "Ghana",
        "ISO2": "GH",
        "Country_ID": 20,
        "ADMIN1_NAME": "Ashanti",
        "ADMIN1_ID": 313,
        "IU_Name": "Mampong Muncipal",
        "District_ID": 3412,
        "IU_ID": 21378,
        "Endemicity": "Non-endemic",
        "MDA_start_APOC": null,
        "LF_MDA_duration": null,
        "start_year": 2000,
        "end_year": 2000,
        "Period": "Annual",
        "PopReq": 0.0,
        "PopTreat": 0.0,
        "Cov": 0.0,
        "MDA": 999,
        "EffMDA": 999,
        "MDA_n": 999,
        "EffMDA_n": 999,
        "MDA_left": 999,
        "Mapping_gap": 0,
        "Composite_IU_ID": "AGHA0216121378"
      }, ...
    ]

Site Level


    e.g. /api/data?iso2=GH&disease=lf&level=sitelevel

    [
      {
        "ID": 4046,
        "Source": "AFRO",
        "Status": "Old",
        "Region": "Western Africa",
        "Country": "Ghana",
        "Country_ID": 20,
        "ISO2": "GH",
        "ISO3": "GHA",
        "ADMIN1_NAME": "ASHANTI",
        "ADMIN1_CODE": 2161,
        "ADMIN2_NAME": "ADANSI SOUTH",
        "ADMIN2_CODE": 21380,
        "EU_NAME": null,
        "IU_NAME": "Adansi South",
        "IU_ID": 21380,
        "LocationName": "KOJO MANKRONG",
        "NamePositioning": null,
        "Longitude": -1.479,
        "Latitude": 5.980556,
        "Georeliability": 1,
        "Location": "Community",
        "PoT": "Preintervention",
        "Period": "after 2000",
        "Year_start": 2001,
        "Year_end": 2001,
        "SurveyYear": 2001,
        "MonthSurvey": null,
        "Year_MDA": null,
        "N_MDA": 0,
        "Method_0": "Mapping survey",
        "Method_1": "Serological",
        "Method_2": "ICT",
        "Blood_volume": 100,
        "Timing": "Day",
        "Sex": "Both",
        "Age_start": 15,
        "Age_end": 99,
        "Examined": 100,
        "Positive": 0,
        "Prevalence": 0.0,
        "Reference": null,
        "Composite_IU_ID": "AGHA0216121380"
      }, ...
    ]

How the attributes param works


    e.g. /api/data?iso2=GH&disease=lf&level=iu&attributes=Country,IU_ID,Endemicity,MDA,EffMDA

    [
      {
        "Country": "Ghana",
        "IU_ID": 21378,
        "Endemicity": "Non-endemic",
        "MDA": 999,
        "EffMDA": 999,
      }, ...
    ]

IU Forecast

If you pass in the param type=forecast then the API will return all of the MDA and impact assessment projections for the next 10 years.

Caution

The IU forecast dataset is very wide, which can cause slow response times and request timeouts. Because of this, it is recommended to also pass in the subtype param. This will narrow the column set and help reduce the response time. The administrative levels are considered default fields, and will always be returned.

Another option for reducing the columns in the API response is to pass in the attributes param. Basically, you pass in a comma-separated list of columns that should be returned (e.g. attributes=IU_ID,MDA_2020,MDA_2021,MDA_2022). See the example above.

Response

MDA


    e.g. /api/data?iso2=GH&disease=lf&level=iu&type=forecast&subtype=mda

    [
      {
        "SN": 2475.0,
        "ESPEN_IU_ID": 21379,
        "ISO2": "GH",
        "ISO3": "GHA",
        "Country": "Ghana",
        "Province_Region": "Ashanti",
        "District_ID": 3390,
        "IU_ID": 21379,
        "IU_Name": "Adansi North",
        "Composite_IU_ID": "AGHA0216121379"
        "MDA_2020": "NE",
        "MDA_2021": "NE",
        "MDA_2022": "NE",
        "MDA_2023": "NE",
        "MDA_2024": "NE",
        "MDA_2025": "NE",
        "MDA_2026": "NE",
        "MDA_2027": "NE",
        "MDA_2028": "NE",
        "MDA_2029": "NE",
        "MDA_2030": "NE",
      }, ...
    ]

Impact Assessment


    e.g. /api/data?iso2=GH&disease=lf&level=iu&type=forecast&subtype=impact_assessment

    [
      {
        "SN": 2475.0,
        "ESPEN_IU_ID": 21379,
        "ISO2": "GH",
        "ISO3": "GHA",
        "Country": "Ghana",
        "Province_Region": "Ashanti",
        "District_ID": 3390,
        "IU_ID": 21379,
        "IU_Name": "Adansi North",
        "Composite_IU_ID": "AGHA0216121379"
        "IA2020": null,
        "IA2021": null,
        "IA2022": null,
        "IA2023": null,
        "IA2024": null,
        "IA2025": null,
        "IA2026": null,
        "IA2027": null,
        "IA2028": null,
        "IA2029": null,
        "IA2030": null,
      }, ...
    ]

Sample API Calls

Data API

GET /api/data?{params}

Params

Response

IU Forecast

Caution

Response

Sample API Calls

Authorization Expired.

Download file