A new service for South African map data

We’ve just launched MapIt (mapit.code4sa.org), a free API that makes it easy to provide localised information and draw South African maps in websites.

Making data local is one of the best ways of making it useful and relevant. This principle lies behind our projects such as Wazimap.co.za, the Cape Town Budget Project and OpenByLaws.org.za. In fact, MapIt powers the maps used in Wazimap.

MapIt is ready for anyone to use within reasonable limits. It replaces our old mapping API which has served us well but wasn’t scaling.

Local is lekker

To make data local you need to know where your user is and the localise the data for them. The Code for SA MapIt API helps you do this by:

• identifying what South African ward, municipality or province a user is in based on their latitude and longitude,
• providing boundary information for geographical areas in GeoJSON format,
• finding areas that touch, overlap or cover or intersect another area.

We’ll be adding additional functionality over time.

Using the API

The MapIt API is is a REST API that serves JSON, GeoJSON and KML data, and is documented at mapit.code4sa.org. Here’s a quick example of how you can use it.

1. Geographical areas in MapIt are identified using a code type and a code.
2. MapIt contains province, municipality and ward boundaries from the Municipal Demarcations Board which has a MapIt code type of MDB.
3. The beautiful Kou-Kamma municipality in the Eastern Cape has been given the code EC109 by the Demarcations Board.
4. Putting those two together, we have a code MDB:EC109 which identifies the Kou-Kamma municipality.

Visiting http://mapit.code4sa.org/area/MDB:EC109.html gives an overview of the data that MapIt has for that area. We can also easily put the municipality on a map by asking MapIt for the geometry of the municipality in GeoJSON format:

http://mapit.code4sa.org/area/MDB:EC109.geojson

Multiple areas

We can use MapIt to get the wards that make up the Kou-Kamma municipality by using special MDB-levels codes.

1. The MDB-levels codes can be used to find areas contained in an area.
2. Municipalities have a type code of MN and wards are WD.
3. To break Kou-Kamma with code EC109 into wards we use ``MDB-levels:MN-EC109|WD``
4. This is a way of saying break Municipality (MN) with code EC109 into areas of type WD (ward).
5. There are many wards in one municipality so we use the areas URL:

  http://mapit.code4sa.org/areas/MDB-levels:MN-EC109|WD.geojson

Using your location

We can also use your browser’s geolocation capabilities to put your current ward on a map.

1. We ask your browser for your location to get your latitude and longitude
2. We then ask MapIt what ward that point is in: /point/4326/[long],[lat]?type=WD
3. Then we get the boundary information for that ward and put it on the map.

You’ll need to click this button and let your browser use your location.

Show my ward

You can read more on using GeoJSON to drawn shapes on a Leaflet map in the Leaflet documentation.

Free to use

MapIt is free to use within reasonable usage limits (1 call per second in a rolling 3 minute period). Please provide a link back to mapit.code4sa.org if you use the service. If you’d like to use it more heavily please get in touch.

Shoulders of giants

Our MapIt service is built on the great work done by MySociety in the UK. We’ve made a few changes to it, particularly to support Wazimap, and we’re sending those back to MySociety to help improve MapIt globally.

Our customised version of MapIt is available on GitHub.

Our original maps API maps.code4sa.org showed us how powerful and useful a service of this type can be. By retiring the old service and building on MySociety’s MapIt platform, we can ensure that it scales to larger datasets and share in helping to make MapIt even better for everyone who uses it.