MapIt API Documentation

<!DOCTYPE HTML> <html lang="en-gb"> <head> <meta charset="UTF-8"> <meta http-equiv="imagetoolbar" content="false"> <meta name="description" content="MapIt: a web service that maps postcodes and geographical points to administrative areas."> <title>MapIt API Documentation - MapIt</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link href="/static/css/main.7ddcc581f40e.css" rel="stylesheet"> <link rel="stylesheet" href="/static/mapit/leaflet/leaflet.a84d4203ddf5.css" />  <script src="/static/mapit/js/reqwest.min.c949fe855720.js"></script> <script src="/static/mapit/leaflet/leaflet.f1cc0a70c78b.js"></script> <link rel="shortcut icon" href="/static/img/favicon.dc3a6eb8c323.ico"> <script defer>Object.defineProperty(document,"cookie",{get:function(){var t=Object.getOwnPropertyDescriptor(Document.prototype,"cookie").get.call(document);return t.trim().length>0&&(t+="; "),t+="_ga=GA1.1."+Math.floor(1e9*Math.random())+"."+Math.floor(1e9*Math.random())},set:function(t){t.trim().startsWith("_ga")||Object.getOwnPropertyDescriptor(Document.prototype,"cookie").set.call(document,t)}});</script> <script defer src="https://www.googletagmanager.com/gtag/js?id=G-LQR5VVLXWM"></script> <script> var client_id = Math.floor(Math.random() * 1000000000) + '.' + Math.floor(Math.random() * 1000000000); window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config','G-LQR5VVLXWM', {'client_id': client_id, 'cookie_expires': 1}); </script> </head> <body> <div class="ms-header"> <nav class="ms-header__row"> <a class="ms-header__logo" href="https://www.mysociety.org">mySociety</a> </nav> </div> <header class="site-header"> <div class="container"> <a href="/" class="site-title"><h1>MapIt</h1></a> <nav role="navigation" class="site-nav"> <ul> <li> <a href="/">Home</a> </li> <li> <a href="/pricing/">Pricing</a> </li> <li> <a href="/docs/">Documentation</a> </li> <li> <a href="/account/login/">Log in</a> </li> <li> <a href="/account/signup/">Sign up</a> </li> </ul> </nav> </div> </header> <div class="content content--with-sidebar content--api-docs"> <h2>MapIt API Documentation</h2> <p>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 <a href="/overview">our page for non-developers</a>.</p> <hr> <header> <h2>MapIt API</h2> <nav class="toc"> <p>Lookups</p> <ol> <li><a href="#api-quota">Quota</a></li> <li><a href="#api-by_postcode">Postcode</a></li> <li><a href="#api-by_partial_postcode">Partial postcode</a></li> <li><a href="#api-by_point">Point</a></li> <li><a href="#api-nearest">Nearest postcode</a></li> <li><a href="#api-by_area_id">Area</a></li> <li><a href="#api-related_areas">Related areas</a></li> <li><a href="#api-multiple_areas">Multiple areas</a></li> <li><a href="#api-code">Code</a></li> <li><a href="#api-generations">Generations</a></li> </ol> <p>Information</p> <ul> <li><a href="#general">General information</a></li> <li><a href="https://github.com/mysociety/mapit">Source code</a></li> <li><a href="/changelog">Changelog</a></li> </ul> </nav> </header> <section id="general"> <h3>General information</h3> <dl> <dt>Format</dt> <dd> <p>All calls return JSON, and you can generally get an HTML representation by adding .html on the end.</p> <p>To use your API key, include it in each API call as either an <code>api_key</code> URL query parameter, e.g. <small>https://mapit.mysociety.org/area/2244?api_key=KEY</small>, or an <code>X-Api-Key</code> HTTP request header. All API responses include your current usage and limit in the <code>X-Quota-Current</code> and <code>X-Quota-Limit</code> response headers. <p>Whenever an area is returned from MapIt, it is as a dictionary with the following keys: <code>id</code>, <code>name</code>, <code>country</code>, <code>type</code>, <code>parent_area</code>, <code>generation_low</code>, <code>generation_high</code>, and <code>codes</code>.</p> </dd> <dt>Errors</dt> <dd> Whenever an error is returned from MapIt, it is as a dictionary with an <code>error</code> key (which contains a textual description such as “Postcode […] is not valid.” or “Usage limit reached.”) and an optional <code>code</code> key (which, if present, will be a copy of the HTTP status code). </dd> <dt>Historical areas</dt> <dd> By default, calls will return active areas; for some calls you may specify a previous generation to look up instead. </dd> <dt>Technical queries</dt> <dd>If you have any technical queries with the API, please <a href="/contact">contact us</a>. </dd> </dl> </section> <section id="api-quota"> <h3><em>lookup</em> quota</h3> <dl> <dt>URL:</dt> <dd>/quota</dd> <dt>Returns:</dt> <dd> <p>Your current quota usage and limit. Note: Accessing this endpoint does not count against your limit.</p> </dd> </dl> </section> <section id="api-by_postcode"> <h3> <em>lookup by</em> postcode </h3> <dl> <dt>URL:</dt> <dd> /postcode/<em>[postcode]</em> </dd> <dt>Returns:</dt> <dd> <p>Information on a particular postcode, including its centroid location in WGS84 latitude/longitude, and the areas that is contained within.</p> </dd> <dt>Optional query parameters:</dt> <dd><ul><li> <i>generation</i>, to return results from a previous generation. </li><li> <i>min_generation</i>, to return results since that generation. </li><li> <i>max_generation</i>, to return results up to that generation, not active after. </li></ul></dd> <dt>Shortcuts:</dt> <dd> <p> As well as the <kbd>areas</kbd> hash of all areas, the results include a <kbd>shortcuts</kbd> key that provides a quick lookup of council, ward, and WMC IDs. If the area is two-tier, the council and ward values will be objects with keys of <kbd>county</kbd> and <kbd>district</kbd>. </p> </dd> <dt>Example:</dt> <dd> <p>If your postcode was <em>SW1A 1AA</em> you would load <a href="/postcode/SW1A1AA">/postcode/SW1A1AA</a> </p> <p> By default the response is in JSON, if you want a human readable page then append ‘<em>.html</em>’ to the url <a href="/postcode/SW1A1AA.html">/postcode/SW1A1AA.html</a> </p> </dd> </dl> </section> <section id="api-by_partial_postcode"> <h3><em>lookup by</em> partial postcode</h3> <dl> <dt>URL:</dt> <dd> /postcode/partial/<em>[partial postcode]</em> </dd> <dt>Returns:</dt> <dd> <p>Geographical details for the centroid of the partial postcode specified.</p> </dd> <dt>Example:</dt> <dd> <ul> <li>JSON: <a href="/postcode/partial/SW1A">/postcode/partial/SW1A</a> <li>HTML: <a href="/postcode/partial/SW1A.html">/postcode/partial/SW1A.html</a> </ul> </dd> </dl> </section> <section id="api-by_point"> <h3><em>lookup by</em> point</h3> <dl> <dt>URL:</dt> <dd><ul> <li>/point/<i>[SRID]</i>/<i>[x]</i>,<i>[y]</i></li> <li>/point/<i>[SRID]</i>/<i>[x]</i>,<i>[y]</i>/box</li> </ul> <dt>Parameters:</dt> <dd> <p><i>SRID</i> 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. </p> <p><i>x</i> and <i>y</i> are the co-ordinates of the point in the co-ordinate system; note that <i>x,y</i> means <i>longitude,latitude</i>.</p> </dd> <dt>Optional query parameters:</dt> <dd> <ul> <li> <i>type</i>, to restrict results to a particular area type or types (multiple types separated by commas); </li> <li> <i>generation</i>, to return results for a previous generation. </li> <li> <i>min_generation</i>, to return results since that generation. </li> <li> <i>max_generation</i>, to return results up to that generation, not active after. </li> <li> <i>country</i>, to restrict results to areas with particular country codes (multiple country codes separated by commas). </li> <li> <i>within</i>, to show results within the specified distance (up to 10000 metres) of the point, not just the point itself (not /box). </li> </ul> </dd> <dt>Returns:</dt> <dd> <p>A hash of the areas that the point is contained within. If the /box version is used, only the area bounding boxes are considered.</p> <dt>Example:</dt> <dd><a href="/point/27700/400000,300000.html">Example of areas containing (400000,300000)</a>.</dd> </dl> </section> <section id="api-nearest"> <h3><em>lookup</em>nearest postcode</h3> <dl> <dt>URL:</dt> <dd> /nearest/<i>[SRID]</i>/<i>[x]</i>,<i>[y]</i> </dd> <dt>Parameters:</dt> <dd>Same as for <a href="#api-by_point">by point</a>.</dd> <dt>Returns:</dt> <dd>The postcode closest to the particular point. <dt>Example</dt> <dd><a href="/nearest/27700/400000,300000.html">Example of postcode nearest to (400000,300000)</a>.</dd> </dl> </section> <section id="api-by_area_id"> <h3><em>lookup by</em> area</h3> <dl> <dt>URL:</dt> <dd><ul> <li>/area/<i>[area ID or ONS code]</i> <li>/area/<i>[area ID]</i>/example_postcode <li>/area/<i>[area ID]</i>/geometry <li>/area/<i>[area ID]</i>.<i>[kml or geojson or wkt]</i> <li>/area/<i>[SRID]</i>/<i>[area ID]</i>.<i>[kml or json or wkt]</i> </ul></dd> <dt>Optional query parameters:</dt> <dd><i>simplify_tolerance</i>, a floating point parameter to simplify the polygons returned.</dd> <dt>Returns:</dt> <dd> Information on a particular area, including name, type, parent, and any associated codes (see <a href="#general">below for details</a>). 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. </dd> <dt>Examples:</dt> <dd> <ul> <li>Information held on Birmingham City Council: <a href="/area/2514.html">/area/2514.html</a> <li>An example postcode in Birmingham City Council: <a href="/area/2514/example_postcode.html">/area/2514/example_postcode.html</a> <li>A KML file of the Isle of Wight Council: <a href="/area/2636.kml">/area/2636.kml</a> </ul> </dd> </dl> </section> <section id="api-related_areas"> <h3><em>lookup</em> related areas</h3> <dl> <dt>URL:</dt> <dd><ul> <li>/area/<i>[area ID]</i>/children <li>/area/<i>[area ID]</i>/touches <li>/area/<i>[area ID]</i>/overlaps <li>/area/<i>[area ID]</i>/covers <li>/area/<i>[area ID]</i>/covered <li>/area/<i>[area ID]</i>/coverlaps <li>/area/<i>[area ID]</i>/intersects </ul></dd> <dt>Optional query parameters:</dt> <dd><ul> <li><i>type</i>, to restrict results to a particular type or types.</li> <li><i>generation</i>, to return results from a previous generation (children only).</li> <li><i>min_generation</i>, to return areas since that generation (children only).</li> <li><i>max_generation</i>, to return results up to that generation, not active after (children only).</li> </ul></dd> <dt>Returns:</dt> <dd>A hash of areas that match the requested lookup. <dt>Examples:</dt> <dd> <ul> <li>All electoral divisions of a county council: <a href="/area/2236/children.html">/area/2236/children.html</a> <li>All the constituencies touching Witney: <a rel="nofollow" href="/area/65622/touches.html?type=WMC">/area/65622/touches.html?type=WMC</a> <li>All areas overlapping Barking and Dagenham council: <a rel="nofollow" href="/area/2511/overlaps.html">/area/2511/overlaps.html</a> <li>All parish councils covered by Witney: <a rel="nofollow" href="/area/65622/covers.html?type=CPC">/area/65622/covers.html?type=CPC</a> <li>All areas covering Witney: <a rel="nofollow" href="/area/65622/covered.html">/area/65622/covered.html</a> <li>All constituencies covered by or overlapping Barking and Dagenham: <a rel="nofollow" href="/area/2511/coverlaps.html?type=WMC">/area/2511/coverlaps.html?type=WMC</a> <li>All areas that intersect Cambridgeshire: <a rel="nofollow" href="/area/2218/intersects.html">/area/2511/intersects.html</a> </ul> </dd> </dl> </section> <section id="api-multiple_areas"> <h3><em>lookup</em> multiple areas</h3> <dl> <dt>URL:</dt> <dd><ul> <li>/areas/<i>[area IDs]</i> <li>/areas/<i>[area IDs]</i>/geometry <li>/areas/<i>[area IDs]</i>.<i>[kml|geojson]</i> <li>/areas/<i>[type(s)]</i> <li>/areas/<i>[name prefix]</i> </ul></dd> <dt>Parameters:</dt> <dd>Separate multiple parameters with commas. Name prefix means it will return any area that starts with the string given. The current area types include: <small> 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), ER (English 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), TTW (Travel to Work Area), UTA (Unitary authority), UTE (Unitary authority electoral division), UTW (Unitary authority ward), WAC (Welsh Assembly constituency), WAE (Welsh Assembly region), WMC (UK Parliamentary constituency)</small>. </dd> <dt>Optional query parameters:</dt> <dd><ul> <li><i>generation</i>, to return areas in that generation (type and name lookups only).</li> <li><i>min_generation</i>, to return areas since that generation (type and name lookups only).</li> <li><i>max_generation</i>, to return results up to that generation, not active after (ditto)..</li> <li><i>type</i>, to restrict results to a type or types (multiple separated by commas; name lookup only).</li> <li><i>country</i>, to restrict results to areas with particular country codes (multiple separated by commas; type and name lookups only).</li> </ul></dd> <dt>Returns:</dt> <dd> <p> 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. </p> </dd> <dt>Examples:</dt> <dd> <ul> <li>All areas starting “Bourn”: <a href="/areas/Bourn.html">/areas/Bourn.html</a> <li>Information on areas 2636 and 2637: <a href="/areas/2636,2637.html">/areas/2636,2637.html</a> <li>All county council (CTY) areas: <a href="/areas/CTY.html">/areas/CTY.html</a> </ul> </dd> </dl> </section> <section id="api-code"> <h3><em>lookup by</em> code</h3> <dl> <dt>URL:</dt> <dd><ul> <li>/code/<i>[code type]</i>/<i>[code]</i> </ul></dd> <dt>Parameters:</dt> <dd><i>code type</i> and a <i>code</i> should uniquely identify an area. (MapIt uses code types and codes to associate external identifiers with areas.) The current code types are: <tt>ons</tt> (SNAC codes, which are old ONS codes), <tt>gss</tt> (new ONS codes), <tt>unit_id</tt> (OS admin area IDs from Boundary-Line) and <tt>osni_old</tt> (old OSNI object IDs) </dd> <dt>Returns:</dt> <dd> <p> This returns an HTTP 302 Found redirect to the corresponding /area/<i>[area ID]</i> page. Any format extension (<tt>.html</tt> or <tt>.json</tt>) will be preserved in the URL that's redirected to. </p> </dd> <dt>Examples:</dt> <dd> <ul> <li>Look up the Edinburgh Central Scottish Parliament constituency from its GSS ID: <a href="/code/gss/S16000104.html">code/gss/S16000104.html</a> </ul> </dd> </dl> </section> <section id="api-generations"> <h3>Generations</h3> <dl> <dt>URL:</dt> <dd>/generations</dd> <dt>Returns:</dt> <dd>A list of all generations in this installation of MapIt.</dd> Note that only generations from 12 upwards actually exist, apart from some council names in generation 10 in order for <a href="http://www.fixmystreet.com/">FixMyStreet</a> to show expired councils on its All Reports page. <dt>Example</dt> <dd><a href="/generations.html">List of generations</a></dd> </dl> </section> </div> <div class="mysoc-footer" role="contentinfo"> <div class="container"> <div class="row"> <div class="col-sm-5"> <h2 class="mysoc-footer__site-name">MapIt: UK </h2> <div class="mysoc-footer__site-description"> <p>Point-to-boundary mapping for the UK. Input a postcode or geographical location, and MapIt returns the relevant constituency or authority. </p> </div> </div> <div class="col-sm-4"> <nav class="mysoc-footer__links"> <ul> <li role="presentation"><a href="/">Home</a></li> <li role="presentation"><a href="/pricing/">Pricing</a></li> <li role="presentation"><a href="/docs/">Documentation</a></li> </ul> <ul> <li role="presentation"><a href="/legal/">Terms</a></li> <li role="presentation"><a href="/privacy/">Privacy</a></li> <li role="presentation"><a href="/contact">Contact</a></li> </ul> </nav> </div> <div class="col-sm-3"> <div class="mysoc-footer__donate"> <p>Your donations keep this site and others like it running</p> <a href="https://www.mysociety.org/donate?utm_source=mapit.mysociety.org&utm_content=footer+donate+now&utm_medium=link&utm_campaign=mysoc_footer" class="mysoc-footer__donate__button">Donate now</a> </div> </div> </div> <hr class="mysoc-footer__divider" role="presentation"> <div class="row"> <div class="col-sm-3"> <div class="mysoc-footer__orgs"> <p class="mysoc-footer__org"> Built by <a href="https://www.mysociety.org?utm_source=mapit.mysociety.org&utm_content=footer+logo&utm_medium=link&utm_campaign=mysoc_footer" class="mysoc-footer__org__logo mysoc-footer__org__logo--mysociety">mySociety</a> </p> </div> </div> <div class="col-sm-6"> <div class="mysoc-footer__legal"> <p> <a href="https://www.societyworks.org?utm_source=mapit.mysociety.org&utm_content=footer+full+legal+details&utm_medium=link&utm_campaign=mysoc_footer">SocietyWorks</a> is a limited company (05798215). It is a trading subsidiary of <a href="https://www.mysociety.org?utm_source=mapit.mysociety.org&utm_content=footer+full+legal+details&utm_medium=link&utm_campaign=mysoc_footer">mySociety</a>, a registered charity in England and Wales (1076346). </p> </div> </div> <div class="col-sm-3"> <ul class="mysoc-footer__badges"> <li role="presentation"><a href="https://github.com/mysociety/mapit" class="mysoc-footer__badge mysoc-footer__badge--github">Github</a></li> <li role="presentation"><a href="https://twitter.com/mysociety" class="mysoc-footer__badge mysoc-footer__badge--twitter">Twitter</a></li> <li role="presentation"><a href="https://www.facebook.com/mysociety" class="mysoc-footer__badge mysoc-footer__badge--facebook">Facebook</a></li> </ul> </div> </div> </div> </div> <script src="/static/js/jquery-1.12.4.min.4f252523d4af.js"></script> <script src="/static/js/analytics.bad0af22f731.js"></script> </body> </html>

CINXE.COM

MapIt API Documentation - MapIt