MapIt : map postcodes and geographical points to administrative areas

<!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 : map postcodes and geographical points to administrative areas </title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link href="/static/mapit/css/mapit.251ea1f196a1.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> </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 <small>Global </small></h1></a> <nav role="navigation" class="site-nav"> <ul> <li> <a href="/overview">Overview</a> </li> <li> <a href="/">API Documentation</a> </li> </ul> </nav> </div> </header> <header class="homepage-section homepage-intro"> <div class="container"> <p class="lead"> MapIt is a service that maps geographical points to administrative areas. This edition is based on source data from the totally amazing <a href="http://www.openstreetmap.org/">OpenStreetMap</a> project, so add your boundaries there if they’re missing. If you’re in the UK our <a href="https://mapit.mysociety.org/">MapIt UK</a> with open Ordnance Survey data will probably be more useful. </p> <p> MapIt is useful for anyone who has the co-ordinates of a point on Earth, and who needs to find out what country, region, city, constituency, or state it lies within. It’s also great for looking up the shapes of all those boundaries. </p> <p>Charitable, low volume use of this service is free – <a href="/licensing">read more</a>.<br>You can <a href="https://github.com/mysociety/mapit">download the source on Github</a>.<br>Need a licence? <a href="/licensing">Read more</a>.</p> </div> </header> <div class="homepage-section homepage-try homepage-section--contrasting"> <form method="post" action="/point/" class="homepage-try__form"> <div class="container"> <label for="try-mapit-pc"> Try it out, enter a lat,lon: </label> <input type="text" name="pc" id="pc" placeholder="latitude,longitude"> <input class="btn" type="submit" value="Look up"> </div> </form> </div> <article class="content content--with-sidebar content--api-docs"> <h2>MapIt API Documentation</h2> <div class="api-docs-intro"> <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> </div> <header> <nav class="toc"> <p>Lookups</p> <ol> <li><a href="#api-by_point">Point</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="#about-mapit">About MapIt</a></li> <li><a href="#usage-licence">Usage & licence</a></li> <li><a href="https://github.com/mysociety/mapit">Source code</a></li> </ul> </nav> </header> <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 one you probably are interested in is 4326 for WGS84 normal lon/lat. </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> </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/4326/8.55,47.366667.html">Example of areas containing (47.366667,8.55)</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]</i> <li>/code/osm_rel/<i>[OSM relation ID]</i> <li>/code/osm_way/<i>[OSM way ID]</i> <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. geometry returns centroid, extent and area of the area. </dd> <dt>Examples:</dt> <ul> <li>Information held on Paris: <a href="/area/29746.html">/area/29746.html</a> <li>A KML file of Paris: <a href="/area/29746.kml">/area/29746.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 the areas touching Cambridgeshire: <a rel="nofollow" href="/area/25495/touches.html">/area/25495/touches.html</a> <li>All areas overlapping Cambridgeshire: <a rel="nofollow" href="/area/25495/overlaps.html">/area/25495/overlaps.html</a> <li>All areas covered by Cambridgeshire: <a rel="nofollow" href="/area/25495/covers.html">/area/25495/covers.html</a> <li>All areas covering Cambridgeshire: <a rel="nofollow" href="/area/25495/covered.html">/area/25495/covered.html</a> <li>All areas covered by or overlapping Cambridgeshire: <a rel="nofollow" href="/area/25495/coverlaps.html">/area/25495/coverlaps.html</a> <li>All areas that intersect Cambridgeshire: <a rel="nofollow" href="/area/25495/intersects.html">/area/25495/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 are: <small>O01 to O12</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 “Ven”: <a href="/areas/Ven.html">/areas/Ven.html</a> <li>Information on areas 29746 and 25495: <a href="/areas/29746,25495.html">/areas/29746,25495.html</a> <li>All level 2 (O02) areas: <a href="/areas/O02.html">/areas/O02.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>osm_rel</tt> (OSM relation ID) and <tt>osm_way</tt> (OSM way ID) </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 1st Arrondissement of Paris from from its OSM relation ID: <a href="/code/osm_rel/20727.html">/code/osm_rel/20727.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> <dt>Example</dt> <dd><a href="/generations.html">List of generations</a></dd> </dl> </section> <section id="general"> <h3>General information</h3> <dl> <dt>Format</dt> <dd> <p>All calls return JSON, you can generally get an HTML representation by sticking .html on the end.</p> <p>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.</p> </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> </dl> </section> <section id="about-mapit"> <h3>About MapIt</h3> <p>MapIt was written back in 2003 as a postcode lookup to power the original <a href="http://www.mysociety.org/">mySociety</a> sites such as <a href="http://www.writetothem.com/">WriteToThem</a>. Over time it gained features such as point lookup (for <a href="http://www.fixmystreet.com/">FixMyStreet</a>), 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 <a href="http://mapit.nuug.no/">Norway</a>, and in 2012 we released this global version based on OpenStreetMap data. </p> </section> <section id="usage-licence"> <h3>Usage & Licence</h3> <p>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 <a href="/licensing">acquire a licence</a>.</p> <p>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.</p> <p>If you use this service, you must attribute OpenStreetMap as per their licence. 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.</p> </section> </article> <div class="mysoc-footer" role="contentinfo"> <div class="container"> <div class="row"> <div class="col-sm-7"> <h2 class="mysoc-footer__site-name">MapIt: Global </h2> <div class="mysoc-footer__site-description"> <p>Point-to-boundary mapping, anywhere in the world. Input a geographical location, and MapIt returns the relevant administrative area. </p> </div> <div class="mapit-copyright"> <p id="copyright">This database contains OpenStreetMap data © <a href="http://www.openstreetmap.org/">OpenStreetMap</a> and contributors; the data from generation 1 can be used under the <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA-2.0</a> license, while the data from all more recent generations can be used under the <a href="http://opendatacommons.org/licenses/odbl/1.0/">ODbL</a>. </p> </div> </div> <div class="col-sm-2"> </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.mysociety.org?utm_source=mapit.mysociety.org&utm_content=footer+full+legal+details&utm_medium=link&utm_campaign=mysoc_footer">mySociety</a> is a registered charity in England and Wales (1076346) and a limited company (03277032). We provide commercial services through our wholly owned subsidiary <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 Ltd</a> (05798215).</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> </body> </html>

CINXE.COM

MapIt : map postcodes and geographical points to administrative areas