Maps API

This API will return the finalized GeoJSON that has the data included in the GeoJSON. For Site Level data, it will include coordinates for the latitude and longitude values. For IU data, the relevant data will be included in the IU features. This API will be used to dynamically generate the map PDFs.

Behind the scenes, we will do something like this:

  1. Get the country GeoJSON, along with the GeoJSON for each IU in the country
  2. Get the data based on country, disease, type, level, start year, and end year
  3. Calculate the categories
  4. Generate the final GeoJSON that has the disease data merged in

Here is more info on how the categories are calculated:

Map Category Logic and Queries

Here are all of the map type combinations, including which ones are complete:

Map Type Combinations

Here are a list of map types provided by Manta Ray:

Map types from website 2.0

This API is used to retrieve information about the maps. This will be used by the Country, Disease, and Search pages.

For Coendemicity, there will be new map types added. More info here:

Coendemicity Maps

For all map troubleshooting and QA, I'm gathering notes here:

Maps QA & Troubleshooting

What's left to do:

What's Left for the Maps

Misc MRM updates needed:

Misc MRM Updates Needed

GET /api/maps?{params}

Return a list of maps filtered on the following params: country, disease, level, type, subtype, start year, and end year.

The response includes categories, which is an array of name/value pairs for the categories of the map. The actual categories will differ depending on the disease, level, type, and subtype. For example, for Sentinel Site maps, this would be 'Non-endemic' and 'Endemic'. The legend will be used to populate the legend on the left side of the map templates, and to associate each category with a color.

For GeoJSON features that need to be colored, there will be a 'value' attribute. This will associate the feature with the value for the category in the legend of the map template. For IU, this will be on the IU GeoJSON feature. For Site Level, this will be on the Point features.

Here's a sample of an IU map:

    {
        "categories": [
            {"name": "Non-endemic", "value": 0},
            {"name": "Endemic", "value": 1},
        ],
        "geojson": {
          "type": "FeatureCollection",
          "features": [
                {
                    "type": "Feature",
              "properties": {
                        "iu": "Forecariah",
                        "iu_id": "22616",
                "value": 1
              },
              "geometry": {
                "type": "MultiPolygon",
                "coordinates": [
                  [
                    [
                      [
                        -996700.28959999979,
                        980558.14970000088
                      ], ...
                                ]
                            ]
                        ]
                    }
                }, ...
            ]
        }
    }

Here's a sample of a Site Level map. The GeoJSON includes MultiPolygon features for the IU boundaries, and Point features for the data.

    {
        "categories": [
            {"name": "Non-endemic", "value": 0},
            {"name": "Endemic", "value": 1},
        ],
        "geojson": {
          "type": "FeatureCollection",
          "features": [
                {
                    "type": "Feature",
                    "properties": {
                        "iu": "Forecariah",
                        "iu_id": "22616",
                    },
              "geometry": {
                "type": "MultiPolygon",
                "coordinates": [
                  [
                    [
                      [
                        -996700.28959999979,
                        980558.14970000088
                      ], ...
                                ]
                            ]
                        ]
                    }
                },
                {
                    "type": "Feature",
              "properties": {
                "value": 1
              },
              "geometry": {
                "type": "Point",
                "coordinates": [8.55, -9.48]
                    }
                }, ...
            ]
        }
    }

Hierarchy

The map data is generally organized into a hierarchy. See the example below.

Select disease (lf, loa, oncho, sth, sch, trachoma)

——> Select level (iu, site_level)

————> Select type (endemicity, mda_pc_coverage, mda_pc_rounds)

——————> Select subtype (therapeutic, geographic)

Params

    e.g. /api/maps?iso2=GH&disease=lf&level=sitelevel&type=sentinel_sites

    iso2: country ISO2 value, e.g. GH
    disease: { lf | oncho | loa | sch | sth | trachoma }
    level: { sitelevel | iu }

    # LF + Site Level
    type: { tas | sentinel_sites | mapping_surveys }

    # LF + IU
    type: { endemicity | mda_pc_rounds }

    # LF + IU MDA/PC Rounds
    subtype: { projections | therapeutic | geographic }

    # Oncho + Site Level
    type: { impact_assessment | mapping_surveys }
    subtype: { skin_biopsy | anti_ov16_test | nodule_palpation }

    # Oncho + IU
    type: { endemicity | mda_pc_coverage | mda_pc_rounds }

    # Oncho + IU + MDA/PC Coverage and Rounds
    subtype: { geographic | therapeutic }

    # Loa + Site Level
    type: { mapping_surveys }
    subtype: { ewh_questionnaire | blood_smear }

    # Loa + IU
    type: { endemicity }

    # SCH + Site Level
    type: { mapping_surveys }
    subtype: { all_species | s_haematobium | s_mansoni }

    # SCH + IU
    type: { endemicity | mda_pc_coverage | mda_pc_rounds }

    # SCH + IU + MDA/PC Coverage and Rounds
    subtype: { geographic_sac, geographic_total, therapeutic_sac, therapeutic_total }

    # STH + Site Level
    type: { mapping_surveys }
    subtype: { all_species | ascaris | hookworms | trichuris }

    # STH + IU
    type: { endemicity | mda_pc_coverage | mda_pc_rounds }

    # STH + IU + MDA/PC Coverage and Rounds
    subtype: { geographic_sac, geographic_total, therapeutic_sac, therapeutic_total }

    # Trachoma + IU
    admin1_id: admin1 id
    type: { endemicity }
    subtype: { baseline_tf | current_tf | current_tt }

    # 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

Cartography Params

For IU level only, the API accepts params that can be used to filter the data by the various cartography attributes. For example, you could return all LF IU data for Western Africa.

There are filters for each attribute returned by the Cartographies API, except for geojson. These are listed below, but you can also find them in documentation here:

Cartographies API

Note: filtering by continent, region, and who_region can potentially return a large payload. This will result in increased response times by the API, and potentially a request timeout (if the response takes longer than 30 seconds).

    admin0
    admin0_id
    iso2
    iso3
    continent
    region
    who_region
    admin1
    admin1_id
    admin2
    admin2_id
    admin2_alias
    admin3
    admin3_id
    admin3_alias
    iu_id
    old_iu_id
    admin_level: { admin0 | admin1 | admin2 | admin3 }
    update_type: { split | merge | reshape }
    created_at
    updated_at
    parent_iu_id
    parent_iu_id_2
    active: { default: true }
    population

Sample API Calls

These are for all levels, types, and subtypes that are fully or mostly working.

https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=lf&level=sitelevel&type=tas
https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=lf&level=sitelevel&type=sentinel_sites
https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=lf&level=sitelevel&type=mapping_surveys
https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=lf&level=iu&type=endemicity
https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=lf&level=iu&type=mda_pc_rounds&subtype=projections
https://admin.espen.afro.who.int/api/maps?iso2=NG&disease=lf&level=iu&type=mda_pc_rounds&subtype=therapeutic
https://admin.espen.afro.who.int/api/maps?iso2=NG&disease=lf&level=iu&type=mda_pc_rounds&subtype=geographic
https://admin.espen.afro.who.int/api/maps?iso2=GH&disease=oncho&level=iu&type=endemicity
https://admin.espen.afro.who.int/api/maps?iso2=CI&disease=oncho&level=iu&type=mda_pc_coverage&subtype=geographic
https://admin.espen.afro.who.int/api/maps?iso2=CI&disease=oncho&level=iu&type=mda_pc_coverage&subtype=therapeutic
https://admin.espen.afro.who.int/api/maps?iso2=CI&disease=oncho&level=iu&type=mda_pc_rounds&subtype=geographic
https://admin.espen.afro.who.int/api/maps?iso2=CI&disease=oncho&level=iu&type=mda_pc_rounds&subtype=therapeutic
https://admin.espen.afro.who.int/api/maps?iso2=CD&disease=oncho&level=sitelevel&type=impact_assessment&subtype=skin_biopsy
https://admin.espen.afro.who.int/api/maps?iso2=CD&disease=oncho&level=sitelevel&type=mapping_surveys&subtype=skin_biopsy
https://admin.espen.afro.who.int/api/maps?iso2=CD&disease=oncho&level=sitelevel&type=mapping_surveys&subtype=anti_ov16_test
https://admin.espen.afro.who.int/api/maps?iso2=CD&disease=oncho&level=sitelevel&type=mapping_surveys&subtype=nodule_palpation
https://admin.espen.afro.who.int/api/maps?iso2=GA&disease=loa&level=sitelevel&type=mapping_surveys&subtype=blood_smear
https://admin.espen.afro.who.int/api/maps?iso2=GA&disease=loa&level=sitelevel&type=mapping_surveys&subtype=ewh_questionnaire
https://admin.espen.afro.who.int/api/maps?iso2=TD&disease=loa&level=iu&type=endemicity
https://admin.espen.afro.who.int/api/maps?iso2=GM&disease=sch&level=sitelevel&type=mapping_surveys&subtype=all_species
https://admin.espen.afro.who.int/api/maps?iso2=GM&disease=sch&level=sitelevel&type=mapping_surveys&subtype=s_haematobium
https://admin.espen.afro.who.int/api/maps?iso2=GM&disease=sch&level=sitelevel&type=mapping_surveys&subtype=s_mansoni
https://admin.espen.afro.who.int/api/maps?iso2=TD&disease=sch&level=iu&type=endemicity
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sch&level=iu&type=mda_pc_coverage&subtype=geographic_sac
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sch&level=iu&type=mda_pc_coverage&subtype=geographic_total
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sch&level=iu&type=mda_pc_coverage&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sch&level=iu&type=mda_pc_coverage&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sch&level=iu&type=mda_pc_rounds&subtype=geographic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sch&level=iu&type=mda_pc_rounds&subtype=geographic_total
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sch&level=iu&type=mda_pc_rounds&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sch&level=iu&type=mda_pc_rounds&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=MZ&disease=sth&level=sitelevel&type=mapping_surveys&subtype=all_species
https://admin.espen.afro.who.int/api/maps?iso2=MZ&disease=sth&level=sitelevel&type=mapping_surveys&subtype=ascaris
https://admin.espen.afro.who.int/api/maps?iso2=MZ&disease=sth&level=sitelevel&type=mapping_surveys&subtype=hookworms
https://admin.espen.afro.who.int/api/maps?iso2=MZ&disease=sth&level=sitelevel&type=mapping_surveys&subtype=trichuris
https://admin.espen.afro.who.int/api/maps?iso2=GM&disease=sth&level=iu&type=endemicity
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sth&level=iu&type=mda_pc_coverage&subtype=geographic_sac
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sth&level=iu&type=mda_pc_coverage&subtype=geographic_total
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sth&level=iu&type=mda_pc_coverage&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=ZM&disease=sth&level=iu&type=mda_pc_coverage&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sth&level=iu&type=mda_pc_rounds&subtype=geographic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sth&level=iu&type=mda_pc_rounds&subtype=geographic_total
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sth&level=iu&type=mda_pc_rounds&subtype=therapeutic_sac
https://admin.espen.afro.who.int/api/maps?iso2=SL&disease=sth&level=iu&type=mda_pc_rounds&subtype=therapeutic_sac