This API is used to retrieve information and GeoJSON for countries, regions, districts, and subdistricts. It can also be used to split, merge, and reshape districts and subdistricts. When districts are split and merged, this will result in new IDs for those. When a district is reshaped, the GeoJSON is updated for that district but the ID stays the same.
This API will drive the District Management UI on the ESPEN Admin, as well as some maps that are rendered on the ESPEN Portal.
The Cartographies table was populated by parsing the 3 latest shapefiles, listed below. You can find notes on this process here:
Countries (admin0)
https://espenportal.blob.core.windows.net/shapefiles/AFRO_ADM0_201812_shapefiles.zip
https://espenportal.blob.core.windows.net/shapefiles/AFRO_ADM0_201812_geojson.zip
Regions (admin1)
https://espenportal.blob.core.windows.net/shapefiles/AFRO_ADM1_201812_shapefiles.zip
https://espenportal.blob.core.windows.net/shapefiles/AFRO_ADM1_201812_geojson.zip
IUs (admin2 or admin3)
https://espenportal.blob.core.windows.net/shapefiles/AFRO_IUs_201812_shapefiles.zip
https://espenportal.blob.core.windows.net/shapefiles/AFRO_IUs_201812_geojson.zip
Returns a list of cartographies, including all countries, regions, and IUs (districts and subdistricts). The results can be filtered on various attributes, like admin0, admin1, and admin2. You can search by any of the attributes that are returned by the index (e.g. iso2).
You also have the option to only return records of a certain administrative level. For example, passing a admin_level param with the value "admin0" will only return countries (which are admin level 0).
No GeoJSON is included in the response by default, but you can use the geojson=true flag to enable it.
By default, all attributes are returned. However, you can also provide an attributes parameter in the request, which is a comma-separated list of attributes. This will restrict the response to only those attributes.
There are three samples below. One for country, one for region, and one for district.
[
{
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "",
"admin1_id": "",
"admin1_alias": "",
"admin2": "",
"admin2_id": "",
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu_id": "",
"iu_name": "",
"old_iu_id": "",
"admin_level": "admin0",
"update_type": "",
"updated_at": "",
"parent_iu_id": "",
"parent_iu_id_2": "",
"active": true,
"population": 293858
},
{
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2280,
"admin1_alias": "",
"admin2": "",
"admin2_id": "",
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu_id": "",
"iu_name": "",
"old_iu_id": "",
"admin_level": "admin1",
"update_type": "",
"updated_at": "",
"parent_iu_id": "",
"parent_iu_id_2": "",
"active": true,
"population": 29475
},
{
"admin0": "Guinea",
"admin0_id": 20,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2280,
"admin1_alias": "",
"admin2": "Fria",
"admin2_id": 22617,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu_id": "AGIN0228122617",
"iu_name": "Fria",
"old_iu_id": "22617",
"admin_level": "admin2",
"update_type": "",
"updated_at": "2018-12-06 22:54:48.560",
"parent_iu_id": "",
"parent_iu_id_2": "",
"active": true,
"population": 1894
}, ...
]
Here's a sample response that includes in the GeoJSON.
[
{
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2280,
"admin1_alias": "",
"admin2": "Fria",
"admin2_id": 22617,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu_id": "AGIN0228122617",
"iu_name": "Fria",
"old_iu_id": "22617",
"admin_level": "admin2",
"update_type": "",
"updated_at": "2018-12-06 22:54:48.560",
"parent_iu_id": "",
"parent_iu_id_2": "",
"active": true,
"population": 1894
"geojson": {
"type": "Feature",
"properties": {
"CONTINENT": "Africa",
"REGION": "Western Africa",
"WHO_REGION": "AFRO",
"ADMIN0": "Guinea",
"ADMIN0ID": 21,
"ADMIN0_FIP": "GV",
"ADMIN0ISO2": "GN",
"ADMIN0ISO3": "GIN",
"ADMIN1": "Kindia",
"ADMIN1ID": 2280,
"ADMIN2": "Fria",
"ADMIN2ID": 22617,
"Alt_ADMIN2": null,
"ADMIN3": null,
"ADMIN3ID": 0,
"IUs_ADM": "ADM2",
"IU_ID": "GIN22617",
"IUs_NAME": "Fria",
"LASTUPDATE": 20160308,
"CARTO": "GEOCONNECT",
"IU_ID2": 22617,
"Alt_IU_Nam": null,
"Shape_Leng": 365497.65653600002,
"Shape_Le_1": 365497.65653600002,
"Shape_Area": 4376758460.1099997
...
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
723281.63850000128,
4451075.6977000012
], ...
]
]
}
}
}, ...
]
Results can be filtered by any of the cartography attributes listed in the API response. Additionally, results can be filtered by level.
Another important param is geojson, which determines whether or not GeoJSON is included in the response. This defaults to false.
e.g. /api/cartographies?iso2=GN
#Filter by attribute
admin0
admin0_id
iso2
iso3
continent: { 'Africa', 'Asia' }
region: { 'Eastern Africa', 'Middle Africa', 'Northen Africa', 'Northern Africa', 'Southern Africa', 'Western Africa', 'Western Asia' }
who_region: { 'AFRO', 'EMRO' }
admin1
admin1_id
admin2
admin2_id
admin2_alias
admin3
admin3_id
admin3_alias
iu_id
iu_name
admin_level: { admin0 | admin1 | admin2 | admin3 | iu }
update_type: { split | merge | reshape }
parent_iu_id
parent_iu_id_2
active: { default: true }
# Other params
geojson: { true | false }
attributes: comma-separated list of attributes to return
limit: for paging
offset: for paging
For now, only districts (IUs) can be split and merged.
The history of splits and merges are kept track of. The lineage of a district can be determined by paying attention to the following attributes:
active: { true | false }
update_type: { split | merge | reshape }
updated_at: when the update happened
parent_iu_id: iu id of the parent district
parent_iu_id_2: if a merge, the iu id of the other parent
When a district is split or merged, active is set to false for the parent district(s). Any newly created districts have active set to true.
Split a district into two new districts. The GeoJSON for the new districts can be passed in. The admin0 and admin1 levels will carry over to the new districts by default.
Note: an admin1_id can be passed in, which would change the admin1 for that IU. This is because sometimes, upon split, the IU could be put into a different region.
{
// The district to split
"iu_id": "AGIN0228122617"
// The new districts
"new_ius": [
{
name: "Fria East",
admin1_id: 2282,
population: 29479,
geojson: { ... }
},
{
name: "Fria West",
population: 8493,
geojson: { ... }
}
]
}
The response shows if the split was successful, and provides the full JSON representation of the new districts.
{
"success": true,
"districts": [
{
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2281,
"admin1_alias": "",
"admin2": "Fria East",
"admin2_id": 22618,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu": "Fria East",
"iu_id": "AGIN0228122618S",
"admin_level": "admin2",
"update_type": "split",
"updated_at": "2018-06-04 19:14:18",
"parent_iu_id": "AGIN0228122617",
"parent_iu_id_2": "",
"active": true,
"population": 29479,
"geojson": { ... }
},
{
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2281,
"admin1_alias": "",
"admin2": "Fria West",
"admin2_id": 22619,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu": "Fria West",
"iu_id": "AGIN0228122619S",
"admin_level": "admin2",
"update_type": "split",
"updated_at": "2018-06-04 19:14:18",
"parent_iu_id": "AGIN0228122619",
"parent_iu_id_2": "",
"active": true,
"population": 8493,
"geojson": { ... }
}
]
}
Merge two districts into a single district. The GeoJSON for the new districts can be passed in.
{
// The districts to merge
"iu_ids": ["AGIN0228122618S", "AGIN0228122619S"]
// The new district
"new_iu": {
"name": "Fria Merge",
"population": 29972,
"geojson": { ... }
}
}
{
"success": true,
"district": {
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2281,
"admin1_alias": "",
"admin2": "Fria Merge",
"admin2_id": 22620,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu": "Fria Merge",
"iu_id": "AGIN0228122620M",
"admin_level": "admin2",
"update_type": "merge",
"updated_at": "2018-06-04 20:14:18",
"parent_iu_id": "AGIN0228122617S",
"parent_iu_id_2": "AGIN0228122618S",
"active": true,
"population": 29479,
"geojson": { ... }
}
}
Reshape the boundaries for a district. Basically, this will set new GeoJSON for that district.
Behind the scenes, this will create a new record in the database. The IU_ID will stay the same for the new record, and the old one will be deactivated. This will allow us to keep a history of shapes for a district.
When a reshape happens, the update_type, updated_at, and geojson values will be updated.
{
"iu_id": "AGIN0228122620M",
"geojson": { ... }
}
{
"success": true,
"district": {
"admin0": "Guinea",
"admin0_id": 21,
"iso2": "GN",
"iso3": "GIN",
"continent": "Africa",
"region": "Western Africa",
"who_region": "AFRO",
"admin1": "Kindia",
"admin1_id": 2281,
"admin1_alias": "",
"admin2": "Fria Merge",
"admin2_id": 22620,
"admin2_alias": "",
"admin3": "",
"admin3_id": "",
"admin3_alias": "",
"iu": "Fria Merge",
"iu_id": "AGIN0228122620M",
"admin_level": "admin2",
"update_type": "reshape",
"updated_at": "2018-06-04 21:14:18",
"parent_iu_id": "AGIN0228122617S",
"parent_iu_id_2": "AGIN0228122618S",
"active": true,
"population": 29479,
"geojson": { ... }
}
}
The file will be sent to your email address shortly.