MapIt API
The documentation below is for developers who want to use MapIt as a web service, describing its REST API. If that’s all Greek to you, please see our page for non-developers.
lookup by postcode
- URL:
- /postcode/[postcode]
- Returns:
-
Information on a particular postcode, including its location in WGS84 latitude/longitude, and the areas it is contained within.
- Optional query parameters:
-
generation, to return results from a previous generation.
- Example:
-
If your postcode was SW1A 1AA you would load /postcode/SW1A1AA
By default the response is in JSON, if you want a human readable page then append ‘.html’ to the url /postcode/SW1A1AA.html
lookup by partial postcode
- URL:
- /postcode/partial/[partial postcode]
- Returns:
-
Geographical details for the centroid of the partial postcode specified.
- Example:
-
- JSON: /postcode/partial/SW1A
- HTML: /postcode/partial/SW1A.html
lookup by point
- URL:
- /point/[SRID]/[x],[y]
- /point/[SRID]/[x],[y]/box
- Parameters:
-
SRID is a unique number referring to a particular co-ordinate system; the ones you probably are interested in are 27700 for British National Grid, 4326 for WGS84 lon/lat, and 29902 for the Irish National Grid.
x and y are the co-ordinates of the point in the co-ordinate system; note that x,y means longitude,latitude.
- Optional query parameters:
-
- type, to restrict results to a particular area type or types (multiple types separated by commas);
- generation, to return results for a previous generation.
- min_generation, to return results since that generation.
- Returns:
-
A hash of the areas that the point is contained within. If the /box version is used, only the area bounding boxes are considered.
- Example:
- Example of areas containing (400000,300000).
lookupnearest postcode
- URL:
- /nearest/[SRID]/[x],[y]
- Parameters:
- Same as for by point.
- Returns:
- The postcode closest to the particular point.
- Example
- Example of postcode nearest to (400000,300000).
lookup by area
- URL:
- /area/[area ID or ONS code]
- /area/[area ID]/example_postcode
- /area/[area ID]/geometry
- /area/[area ID].[kml or geojson or wkt]
- /area/[SRID]/[area ID].[kml or json or wkt]
- Optional query parameters:
- simplify_tolerance, a floating point parameter to simplify the polygons returned.
- Returns:
- Information on a particular area, including name, type, parent, and any associated codes (see below for details). The code lookups redirect to the area URI. example_postcode returns a random postcode within the area specified. geometry returns centroid, extent and area of the area.
- Examples:
-
- Information held on Birmingham City Council: /area/2514.html
- An example postcode in Birmingham City Council: /area/2514/example_postcode.html
- A KML file of the Isle of Wight Council: /area/2636.kml
lookup multiple areas
- URL:
- /areas/[area IDs]
- /areas/[area IDs]/geometry
- /areas/[type(s)]
- /areas/[name prefix]
- Parameters:
- Separate multiple parameters with commas. Name prefix means it will return any area that starts with the string given. The current area types are: CTY (county council), CED (county ward), COI (Isles of Scilly), COP (Isles of Scilly parish), CPC (civil parish/community), CPW (civil parish/community ward), DIS (district council), DIW (district ward), EUR (Euro region), GLA (London Assembly), LAC (London Assembly constituency), LBO (London borough), LBW (London ward), LGD (NI council), LGE (NI electoral area), LGW (NI ward), MTD (Metropolitan district), MTW (Metropolitan ward), NIE (NI Assembly constituency), OLF (Lower Layer Super Output Area, Full), OLG (Lower Layer Super Output Area, Generalised), OMF (Middle Layer Super Output Area, Full), OMG (Middle Layer Super Output Area, Generalised), SPC (Scottish Parliament constituency), SPE (Scottish Parliament region), UTA (Unitary authority), UTE (Unitary authority electoral division), UTW (Unitary authority ward), WAC (Welsh Assembly constituency), WAE (Welsh Assembly region), WMC (UK Parliamentary constituency).
- Optional query parameters:
- generation, to return areas in that generation (type and name lookups only).
- min_generation, to return areas since that generation (type and name lookups only).
- type, to restrict results to a type or types (multiple separated by commas; name lookup only).
- Returns:
-
Information on multiple areas that match the parameters provided, as a dictionary indexed by area ID. The geometry argument lets you fetch multiple single area geometry results at once.
- Examples:
-
- All areas starting “Bourn”: /areas/Bourn.html
- Information on areas 2636 and 2637: /areas/2636,2637.html
- All county council (CTY) areas: /areas/CTY.html
lookup by code
- URL:
- /code/[code type]/[code]
- Parameters:
- code type and a code should uniquely identify an area. (MapIt uses code types and codes to associate external identifiers with areas.) The current code types are: ons (SNAC codes, which are old ONS codes), gss (new ONS codes), unit_id (OS admin area IDs from Boundary-Line) and osni_old (old OSNI object IDs)
- Returns:
-
This returns an HTTP 302 Found redirect to the corresponding /area/[area ID] page. Any format extension (.html or .json) will be preserved in the URL that's redirected to.
- Examples:
-
- Look up the Edinburgh Central Scottish Parliament constituency from its GSS ID: code/gss/S16000104.html
Generations
- URL:
- /generations
- Returns:
- A list of all generations in this installation of MapIt. Note that only generations from 12 upwards actually exist, apart from some council names in generation 10 in order for FixMyStreet to show expired councils on its All Reports page.
- Example
- List of generations
General information
- Format
-
All calls return JSON, you can generally get an HTML representation by sticking .html on the end.
Whenever an area is returned from MapIt, it is as a dictionary with the following keys: id, name, country, type, parent_area, generation_low, generation_high, codes.
- Historical areas
- By default, calls will return active areas; for some calls you may specify a previous generation to look up instead. The main difference in generation 12 is that it contains the pre-2010 England and Wales Parliamentary constituencies; generation 14 contains the pre-2011 Scottish Parliament constituencies. Only current Northern Ireland constituencies are present; if you need pre-2010 UK Parliament NI constituencies, or pre-2011 Northern Ireland Assembly constituencies, you can work it out from the wards and the 2003 SNAC file in the data/ directory.
- Technical queries
- If you have any technical queries with the API, please contact us at mapit@mysociety.org.
About MapIt
MapIt was written back in 2003 as a postcode lookup to power the original mySociety sites such as WriteToThem. Over time it gained features such as point lookup (for FixMyStreet), and when Ordnance Survey data became freely available in 2010, it was rewritten and made public for the whole UK. Versions have appeared in other countries, such as Norway, and in 2012 we released a global version based on OpenStreetMap data.
Usage & Licence
As a UK registered charity our legal status only allows this service to be used free of charge by other registered charities, or individuals working unpaid on non-profit projects. The free usage limit for non-profit users is 50,000 calls to the API per year. All other uses need to acquire a licence.
Find out if you need a licence or get in touch so we can discuss how we can provide you with the service you require.
To maintain quality of service for our own websites, as well as our API users, this service is rate limited to an average of 1 call per second in a rolling 3 minute period.
We recommend that you register for an account and obtain an api key if you're going to use the api. Anonymous usage of the API is permitted, but is rate limited to 10 calls a minute and is meant for trials only.
If you use this service, you must attribute OS/RM/ONS as per their licences. We also ask that all non-profit users attribute MapIt at the point of use on sites or apps. Attribution should use the text “Powered by MapIt”, with a link back to this page.