GIS Support¶
This chapter assumes that the reader is familiar with the general principles explained in the Using the API - basic principles chapter.
The MFL 2 API server uses the excellent GeoDjango and PostGIS to provide The service catalog that can be used to generate facility maps, perform geographic queries and validate facility coordinate data. You can read more about this at the GIS Support page.
What is GIS?¶
A geographic information system (GIS) lets us visualize, question, analyze, and interpret data to understand relationships, patterns, and trends.
Master Facility List data is inherently geographical - the Master Facility List should have coordinates for all facilities in Kenya. The GIS APIs provided by this server support the visualization, interogation and analysis of this data.
Note
The official front-ends barely scratch the surface when it comes to the use of GIS data. These APIs are open to third party applications too.
GIS data formats¶
There are many GIS file formats to choose from. We chose to go with GeoJSON because it fits in with our general preference for JSON. It is easy to convert from GeoJSON to ESRI Shapefile and KML formats.
A brief note about points¶
In “day to day language”, we might be accustomed to expressing points as (latitude, longitude) pairs e.g (-1.300462, 36.791533) for the location of this writer’s office at the time of writing. When expressing that location as a GeoJSON “point”, we’ll need to “flip” the coordinates, so that the GeoJSON for this author’s office would be:
{
type: "Point",
coordinates: [
36.791533,
-1.300462
]
}
How do I move from GeoJSON to a map?¶
If you are building a web application, take a look at Leaflet and OpenLayers.
If you are working on a mobile application, you could take a look at the Google Maps API or its competitors e.g Bing Maps.
If you are working on on a desktop application, we assume that you know what you are doing and do not need any helpful pointers.
Administrative units¶
Kenya has a three tier administrative structure: the country has 47 counties. Each county has a number of constituencies, with the total for the country being 290 constituencies. Each constituency has a number of wards, with the total for the country being 1450 wards. The GIS enabled APIs follow this administrative structure.
Note
This server also has resources that contain country boundaries. The default distribution has data from the World Borders Dataset ( from http://thematicmapping.org/ ).
We have not documented the country boundary APIs for the following reasons:
- The county, constituency and ward boundary APIs meet all of the Kenyan MFL needs.
- The borders in the World Borders Dataset are inaccurate - sometimes lopping off several square kilometers around the borders.
Note
The default distribution has map ( boundary ) data for 1482 out of 1450 wards.
The administrative unit data is considered “setup data” - loaded at server install time, rarely changed afterward. For that reason, the documentation will focus on retrieval and interpretation. If you need to change or add, the basic principles explained in the Using the API - basic principles chapter still apply.
Counties¶
Counties can be listed by sending a GET
to /api/common/counties/
.
Every county is identified by a name
and code
.
An individual county’s detail record is available at
/api/common/counties/<pk>/
e.g
/api/common/counties/dd999449-d36b-47f2-a958-1f5bb52951d4/
for the county
whose id
is dd999449-d36b-47f2-a958-1f5bb52951d4
.
Note
The county detail view is “rich”. It embeds a facility_coordinates
key
that shows the location of every facility in that county.
The facility co-ordinates are a map, with the facility names as keys. For example:
facility_coordinates: {
AAR Gwh Health Care Ltd: {
type: "Point",
coordinates: [
36.80897,
-1.29467
]
},
Dr Musili Clinic (Afya Centre-Nairobi): {
type: "Point",
coordinates: [
36.82763,
-1.28799
]
},
// truncated for brevity
The county detail view also embeds within itself the appropriate
county_boundary
. The contents of this will be discussed in the next
section.
County Boundaries¶
County boundaries can be listed at /api/gis/county_boundaries/
. The list
view is a GeoJSON “FeatureCollection”, while the detail view is a GeoJSON
“Feature”.
Note
The border ( polygon ) is under the geometry
key for every feature.
Every boundary ( feature ) serialization has the following fields:
center
- aPoint
that represents the geometric centre of the areafacility_count
- the number of facilities in that geographic areadensity
- a synthetic value ( roughly comparable to facilities per square kilometer, although it is not actually facilities / sq.km ). This is used by front-end clients to color-code maps.constituency_ids
- a list of theid
s ( primary keys ) of the constituencies under that county. These can be appended to the/api/common/constituencies/
endpoint i.e/api/constituencies/<id>/
in order to retrieve the details of each constituency in the county.constituency_boundary_ids
- a list of theid
s of the constituency boundary objects for the constituencies under the county in question. These can be used to retrieve the constituency boundaries at/api/gis/constituency_boundaries/<pk>/
.
Constituencies¶
Constituencies can be listed by sending a GET
to
/api/common/constituencies/
. Every constituency is identified by a
name
and a code
.
Note
The constituency detail view is, like the county detail view, “rich”.
It embeds facility_coordinates
and the relevant
constituency_boundary
.
Constituency Boundaries¶
Constituency boundaries can be listed at /api/gis/constituency_boundaries/
.
The output is similar to that of the county boundary endpoints, with the
following differences: it embeds ward_ids
instead of constituency_ids
and ward_boundary_ids
instead of constituency_boundary_ids
.
Wards¶
Wards can be listed by sending a GET
to /api/common/wards/
. Every ward
is identified by a name
and a code
.
Note
The ward detail view is, like the county and constituency detail views,
“rich”. It embeds facility_coordinates
and the relevant
ward_boundary
.
Ward Boundaries¶
Ward boundaries can be listed at /api/gis/ward_boundaries/
.
The output is similar to that of the county boundary endpoints, with the
following differences: as the smallest administrative unit, a ward does not
embed the coordinates of any other administrative unit.
Lookup administrative units¶
It is possible to determine the location of a facility using it’s coordinates
by sending a POST
to /api/mfl_gis/ikowapi/
with the longitude and latitude.
{
"longitude": 1.3213,
"latitude": 4.53434
}
The response, if successful, shall provide the ward, constituency and county ids and names.
{
"ward": "<ward id>",
"ward_name": "<ward name>",
"ward_code": "<ward code>",
"constituency": "<constituency id>",
"constituency_name": "<constituency name>",
"constituency_code": "<constituency code>",
"county": "<id of the county>",
"county_name": "<county name>",
"county_code": "<county code>"
}
Facility Coordinates¶
The facility coordinates resources can be found at /api/gis/coordinates/
.
The example below will be used to explain the format:
{
id: "1051cac1-b6e1-46c6-8782-a182dd1a9c50",
type: "Feature",
geometry: {
type: "Point",
coordinates: [
34.92687,
0.88226
]
},
properties: {
created: "2015-05-06T17:29:47.710254Z",
updated: "2015-05-06T17:29:47.710266Z",
deleted: false,
active: true,
search: null,
collection_date: "2015-05-06T17:29:48.624415Z",
created_by: 1,
updated_by: 1,
facility: "7f91fb27-8fa5-4160-b572-2dc0ad7a554e",
source: "c027c6fa-19b2-4fcd-83fa-f84705be84ea",
method: "1a3f3df8-8c18-4cac-89cc-93dc59a0e057"
}
}
The facility’s location is the geometry
Point
. The facility in
question is identified by the facility
property, which contains a
facility primary key that can be used to retrieve the facilities from
/api/facilities/facilities/<pk>/
e.g.
/api/facilities/facilities/7f91fb27-8fa5-4160-b572-2dc0ad7a554e/
for
the example above.
To set up new facility coordinates, POST
to /api/gis/coordinates/
a payload similar to the example below:
{
"coordinates": {
"type": "Point",
"coordinates": [
34.96962,
0.45577
]
},
"facility": "be6ca131-5767-45b2-8213-104214becdd3",
"source": "c027c6fa-19b2-4fcd-83fa-f84705be84ea",
"method": "cd0bbbcf-60fa-4b76-b48c-5dcda414b43d"
}
Every geocode is associated with a geocode source and a geocode method.
The source
key in the payload above is for the geocode source while
the method
key is for the geocode method.
Geocode sources are viewed/created at /api/gis/geo_code_sources/
while geocode methods are viewed/created at /api/gis/geo_code_methods/
.
Both take a name
and a description
.