<div class="container">
  <div class="row">
    <div class="col-md-9 documentation">
      <h2 class="doc-header anchor" id="Overview">Overview</h2>
      <h4>
        Postcodes.io is a free postcode lookup API and geocoder for the UK
      </h4>
      <h3 id="Endpoint">Endpoint</h3>
      <p>All services can be accessed from the following HTTP[S] endpoint</p>
      <pre><h4>https://api.postcodes.io</h4></pre>
      <p>
        The API accepts GET and POST requests. POST methods use content type
        <code>application/json</code>
      </p>
      <h3 id="Extraction">Data Extraction</h3>
      <p>The Postcodes.io application and database are packaged as Docker images for rapid local deployment and data extraction.</p>
      <p>To perform one-time data extraction tasks using SQL, see our <a href="https://ideal-postcodes.co.uk/guides/postcodes-io-database">local data extraction guide</a>.</p>
      <h3 id="Responses">Responses</h3>
      <p>JSON(P) only. CORS is enabled.</p>
      <p>
        Each response comes with an appropriate HTTP Status code (except for
        JSONP requests). These include 200 for success, 400 for a bad request,
        404 for not found and 500 for server error. The HTTP Status code is also
        included in the response body.
      </p>
      <h3 id="Authentication">Authentication</h3>
      <p>Postcodes.io does not require any authentication.</p>
      <h3 id="Error-Handling">Error Handling</h3>
      <p>
        To check for errors, examine the HTTP response code. 200 response
        indicates success while any other code will provide important
        information about why an error occured.
      </p>
      <p>
        Alternatively, you can examine status code in the 'status' property in
        the result body.
      </p>
      <p>
        All JSONP requests return 200 responses because of silent errors. When
        using JSONP, be sure to use the latter method to check for errors.
      </p>
      <h3 id="JSONP">JSONP</h3>
      <p>
        JSONP requests are supported. Simply appended the URI with a callback
        name. e.g.
      </p>
      <pre><h4>https://api.postcodes.io/postcodes/GU50BD?callback=foo</h4></pre>
      <h3 id="Versioning">Versioning</h3>
      <p>
        The API currently does not use any form of versioning. Any changes to
        the API will be backwards-compatible, this includes: adding new
        properties to responses, adding new endpoints, adding new optional
        request parameters and changing the order of properties.
      </p>
      <p>
        If we make backwards-incompatible changes in the future, this will be
        released under a versioned endpoint.
      </p>
      <h3 class="anchor" id="Data">Available Data Fields</h3>
      <h4>Postcode Data (Ordnance Survey Postcode Directory Dataset)</h4>
      <p>
        Data points returned by the <code>/postcodes</code> and
        <code>/outcodes</code> API
      </p>
      <p>
        <b>Note:</b> Some fields may be <code>null</code> if not applicable or
        populated. These fields return type is specified as
        <code>type|null</code>
      </p>
      <table class="table table-hover">
        <thead>
          <tr>
            <th>Field</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr id="postcode">
            <td>
              postcode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Postcode.</strong> All current (‘live’) postcodes within
              the United Kingdom, the Channel Islands and the Isle of Man,
              received monthly from Royal Mail. 2, 3 or 4-character outward
              code, single space and 3-character inward code.
            </td>
          </tr>
          <tr id="outcode">
            <td>
              outcode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Outward Code.</strong> The outward code is the part of the
              postcode before the single space in the middle. It is between two
              and four characters long. A few outward codes are non-geographic,
              not divulging where mail is to be sent. Examples of outward codes
              include "L1", "W1A", "RH1", "RH10" or "SE1P".
            </td>
          </tr>
          <tr id="incode">
            <td>
              incode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Inward Code.</strong> The inward part is the part of the
              postcode after the single space in the middle. It is three
              characters long. The inward code assists in the delivery of post
              within a postal district. Examples of inward codes include "0NY",
              "7GZ", "7HF", or "8JQ".
            </td>
          </tr>
          <tr id="quality">
            <td>
              quality <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Positional Quality.</strong> Shows the status of the
              assigned grid reference.
              <ul>
                <li>
                  1 = within the building of the matched address closest to the
                  postcode mean
                </li>
                <li>
                  2 = as for status value 1, except by visual inspection of
                  Landline maps (Scotland only)
                </li>
                <li>3 = approximate to within 50m</li>
                <li>
                  4 = postcode unit mean (mean of matched addresses with the
                  same postcode, but not snapped to a building)
                </li>
                <li>
                  5 = imputed by ONS, by reference to surrounding postcode grid
                  references
                </li>
                <li>6 = postcode sector mean, (mainly | PO Boxes)</li>
                <li>
                  8 = postcode terminated prior to Gridlink® initiative, last
                  known ONS postcode grid reference1
                </li>
                <li>9 = no grid reference available</li>
              </ul>
            </td>
          </tr>
          <tr id="eastings">
            <td>
              eastings <br />
              <code>integer|null</code>
            </td>
            <td>
              <strong>Eastings.</strong> The Ordnance Survey postcode grid
              reference Easting to 1 metre resolution. Grid references for
              postcodes in Northern Ireland relate to the Irish Grid system. May
              be <code>null</code> if geolocation not available.
            </td>
          </tr>
          <tr id="northings">
            <td>
              northings <br />
              <code>integer|null</code>
            </td>
            <td>
              <strong>Northings.</strong> The Ordnance Survey postcode grid
              reference Northing to 1 metre resolution. Grid references for
              postcodes in Northern Ireland relate to the Irish Grid system. May
              be <code>null</code> if geolocation not available.
            </td>
          </tr>
          <tr id="country">
            <td>
              country <br />
              <code>string</code>
            </td>
            <td>
              <strong>Country.</strong> The country (i.e. one of the four
              constituent countries of the United Kingdom or the Channel Islands
              or the Isle of Man) to which each postcode is assigned.
            </td>
          </tr>
          <tr id="nhs_ha">
            <td>
              nhs_ha <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Strategic Health Authority.</strong> The health area code
              for the postcode.
            </td>
          </tr>
          <tr id="admin_county">
            <td>
              admin_county <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>County.</strong> The current county to which the postcode
              has been assigned.
            </td>
          </tr>
          <tr id="admin_district">
            <td>
              admin_district <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>District.</strong> The current district/unitary authority
              to which the postcode has been assigned.
            </td>
          </tr>
          <tr id="admin_ward">
            <td>
              admin_ward <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Ward.</strong> The current administrative/electoral area
              to which the postcode has been assigned.
            </td>
          </tr>
          <tr id="longitude">
            <td>
              longitude <br />
              <code>double float|null</code>
            </td>
            <td>
              <strong>Longitude.</strong> The WGS84 longitude given the
              Postcode's national grid reference. May be <code>null</code> if
              geolocation not available.
            </td>
          </tr>
          <tr id="latitude">
            <td>
              latitude <br />
              <code>double float|null</code>
            </td>
            <td>
              <strong>Latitude.</strong> The WGS84 latitude given the Postcode's
              national grid reference. May be <code>null</code> if geolocation
              not available.
            </td>
          </tr>
          <tr id="parliamentary_constituency">
            <td>
              parliamentary_constituency <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Westminster Parliamentary Constituency.</strong> The
              Westminster Parliamentary Constituency code for each postcode.
            </td>
          </tr>
          <tr id="european_electoral_region">
            <td>
              european_electoral_region <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>European Electoral Region (EER).</strong> The European
              Electoral Region code for each postcode.
            </td>
          </tr>
          <tr id="primary_care_trust">
            <td>
              primary_care_trust <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Primary Care Trust (PCT).</strong> The code for the
              Primary Care areas in England, LHBs in Wales, CHPs in Scotland,
              LCG in Northern Ireland and PHD in the Isle of Man; there are no
              equivalent areas in the Channel Islands. Care Trust/ Care Trust
              Plus (CT)/ local health board (LHB)/ community health partnership
              (CHP)/ local commissioning group (LCG)/ primary healthcare
              directorate (PHD).
            </td>
          </tr>
          <tr id="region">
            <td>
              region <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Region (formerly GOR).</strong> The Region code for each
              postcode. The nine GORs were abolished on 1 April 2011 and are now
              known as ‘Regions’. They were the primary statistical subdivisions
              of England and also the areas in which the Government Offices for
              the Regions fulfilled their role. Each GOR covered a number of
              local authorities.
            </td>
          </tr>
          <tr id="parish">
            <td>
              parish <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Parish (England)/community (Wales).</strong> The smallest
              type of administrative area in England is the parish (also known
              as 'civil parish'); the equivalent units in Wales are communities.
            </td>
          </tr>
          <tr id="lsoa">
            <td>
              lsoa <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>2011 Census lower layer super output area (LSOA).</strong>
              The 2011 Census lower layer SOA code for England and Wales, SOA
              code for Northern Ireland and data zone code for Scotland.
            </td>
          </tr>
          <tr id="msoa">
            <td>
              msoa <br />
              <code>string|null</code>
            </td>
            <td>
              <strong
                >2011 Census middle layer super output area (MSOA).</strong
              >
              The 2011 Census middle layer SOA (MSOA) code for England and Wales
              and intermediate zone for Scotland.
            </td>
          </tr>
          <tr id="ced">
            <td>
              ced <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>County Electoral District.</strong> The county electoral
              division code for each English postcode. Pseudo codes are included
              for the remainder of the UK. The field will be
              <code>null</code> for English postcodes with no grid reference.
              English county councils use county electoral divisions (CED) to
              elect councillors. These CEDs must be confined within district
              boundaries, but need not be based on whole electoral wards. The
              only exceptions are the Isles of Scilly and the Greater London
              Authority (GLA). CEDs do not exist within UAs.
            </td>
          </tr>
          <tr id="ccg">
            <td>
              ccg <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Sub ICB Location (LOC)/ Local Health Board (LHB)/ Community Health Partnership (CHP)/ Local Commissioning Group (LCG)/ Primary Healthcare Directorate (PHD)</strong>.

              The code for the Sub ICB Locations in England, LHBs in Wales, CHPs in Scotland, LCG in Northern Ireland and PHD in the Isle of Man; there are no equivalent areas in the Channel Islands.

              This was formerly Clinical Commissioning Group. From July 2022, CCGs were replaced by Sub-ICB locations.
            </td>
          </tr>
          <tr id="nuts">
            <td>
              nuts <br />
              <code>string|null</code>
            </td>
            <td>
              <strong
                >International Terratorial Levels (ITL) (Former Nomenclature of Units for Territorial Statistics (NUTS).</strong> The national LAU1-equivalent code for each postcode. Pseudo codes are included for Channel Islands and Isle of Man. The field will otherwise be blank for postcodes with no grid reference.
              <br />
              <br />
              As of May 2021. NUTS has changed to International Territorial Levels (ITL). Postcodes.io will report ITL in <code>nuts</code> and <code>codes.nuts</code> to preserve backwards compatibility.
              <br />
              <br />
              Following the UK’s withdrawal from the EU, a new UK-managed international statistical geography - ITL (International Territorial Levels) - was introduced from 1st January 2021, replacing the former NUTS classification. They align with international standards, enabling comparability both over time and internationally. To ensure continued alignment, the ITLs mirror the NUTS system. They also follow a similar review timetable – every three years.
              <br />
              <br />
              NUTS is a hierarchical classification of spatial units that provides a breakdown of the European Union’s territory for producing regional statistics that are comparable across the Union.
              <br />
              <br />
              The ITL area classification in the UK comprises current national administrative and electoral areas, except in Scotland where some ITL areas comprise whole and/or part Local Enterprise Regions.
              <br />
              <br />
              The ONSPD contains the LAU1 code (9-character LAD/UA code for England, Wales and Northern Ireland and 'S30' code for Scotland). A comprehensive lookup of LAU and ITL codes is included with the accompanying metadata.
            </td>
          </tr>
          <tr id="codes">
            <td>
              codes <br />
              <code>Object</code>
            </td>
            <td>
              <strong
                >Returns an ID or Code associated with the postcode.</strong
              >
              Typically, these are a 9 character code known as an ONS Code or
              GSS Code. This is currently only available for districts,
              parishes, counties, CCGs, NUTS and wards.
            </td>
          </tr>
          <tr>
            <td>
              codes.admin_district <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>admin_district</code> field.</td>
          </tr>
          <tr>
            <td>
              codes.admin_county <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>admin_county</code> field.</td>
          </tr>
          <tr>
            <td>
              codes.admin_ward <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>admin_ward</code> field.</td>
          </tr>
          <tr>
            <td>
              codes.parish <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>parish</code> field.</td>
          </tr>
          <tr>
            <td>
              codes.ccg <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>ccg</code> field.</td>
          </tr>
          <tr>
            <td>
              codes.ccg_code <br />
              <code>string|null</code>
            </td>
            <td>CCG Short Code. e.g. <code>"07N"</code>.</td>
          </tr>
          <tr>
            <td>
              codes.nuts <br />
              <code>string|null</code>
            </td>
            <td>The ITL code associated with the postcode.</td>
          </tr>
          <tr>
            <td>
              codes.lau2 <br />
              <code>string|null</code>
            </td>
            <td>The LAU2 code associated with the postcode.</td>
          </tr>
          <tr>
            <td>
              codes.lsoa <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>lsoa</code> field.</td>
          </tr>
          </tr>
          <tr>
            <td>
              codes.msoa <br />
              <code>string|null</code>
            </td>
            <td>See description of <code>msoa</code> field.</td>
          </tr>
        </tbody>
      </table>

      <h4>Outcode Data (Ordnance Survey Postcode Directory Dataset)</h4>
      <p>Data returned by the <code>/outcodes</code> API</p>

      <table class="table table-hover">
        <thead>
          <tr>
            <th>Field</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr id="outcode">
            <td>
              outcode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Outcode.</strong> The outcode or outward code is the part
              of the postcode before the single space in the middle. It is
              between two and four characters long. Examples of outward codes
              include "L1", "W1A", "RH1", "RH10" or "SE1P". A few outward codes
              are non-geographic, not divulging where mail is to be sent.
            </td>
          </tr>
          <tr id="outcode-eastings">
            <td>
              eastings <br />
              <code>integer|null</code>
            </td>
            <td>
              <strong>Eastings.</strong> The Ordnance Survey postcode grid
              reference Easting to 1 metre resolution; blank for postcodes in
              the Channel Islands and the Isle of Man. Grid references for
              postcodes in Northern Ireland relate to the Irish Grid system.
              Computed as the arithmetic mean of the input coordinates. Returns
              0 if geolocation is not available.
            </td>
          </tr>
          <tr id="outcode-northings">
            <td>
              northings <br />
              <code>integer|null</code>
            </td>
            <td>
              <strong>Northings.</strong> The Ordnance Survey postcode grid
              reference Northing to 1 metre resolution; blank for postcodes in
              the Channel Islands and the Isle of Man. Grid references for
              postcodes in Northern Ireland relate to the Irish Grid system.
              Computed as the arithmetic mean of the input coordinates. Returns
              0 if geolocation is not available.
            </td>
          </tr>
          <tr id="outcode-admin_county">
            <td>
              admin_county <br />
              <code>string[]</code>
            </td>
            <td>
              <strong>County.</strong> The current counties under the outcode.
            </td>
          </tr>
          <tr id="outcode-admin_district">
            <td>
              admin_district <br />
              <code>string[]</code>
            </td>
            <td>
              <strong>District.</strong> The current district/unitary authorites
              under the outcode.
            </td>
          </tr>
          <tr id="outcode-admin_ward">
            <td>
              admin_ward <br />
              <code>string[]</code>
            </td>
            <td>
              <strong>Ward.</strong> The current administrative/electoral areas
              under the outcode.
            </td>
          </tr>
          <tr id="outcode-longitude">
            <td>
              longitude <br />
              <code>double float | null</code>
            </td>
            <td>
              <strong>Longitude.</strong> The WGS84 longitude given the
              Postcode's national grid reference. Computed as the arithmetic
              mean of input coordinates. May be <code>null</code> if geolocation
              not available.
            </td>
          </tr>
          <tr id="outcode-latitude">
            <td>
              latitude <br />
              <code>double float | null</code>
            </td>
            <td>
              <strong>Latitude.</strong> The WGS84 latitude given the Postcode's
              national grid reference. Computed as the arithmetic mean of input
              coordinates. May be <code>null</code> if geolocation not
              available.
            </td>
          </tr>
          <tr id="outcode-country">
            <td>
              country <br />
              <code>string[]</code>
            </td>
            <td>
              <strong>Country.</strong> The countries included in the outcode.
            </td>
          </tr>
          <tr id="outcode-parish">
            <td>
              parish <br />
              <code>string[]</code>
            </td>
            <td>
              <strong>Parish (England)/community (Wales).</strong> The parishes
              included in the outcode.
            </td>
          </tr>
        </tbody>
      </table>
      <h4>Scottish Postcode Data (Scottish Postcode Directory)</h4>
      <p>Data returned by the <code>/scotland/*</code> APIs</p>
      <table class="table table-hover">
        <thead>
          <tr>
            <th>Field</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr id="postcode">
            <td>
              postcode <br />
              <code>string</code>
            </td>
            <td><strong>Postcode. </strong> Royal Mail postcode.</td>
          </tr>
          <tr id="scottish_parliamentary_constituency">
            <td>
              scottish_parliamentary_constituency <br />
              <code>string</code>
            </td>
            <td>
              <strong>Scottish Parliamentary Constituency </strong>2014 Scottish
              Parliamentary Constituency.
            </td>
          </tr>
          <tr id="codes-spd">
            <td>
              codes <br />
              <code>Object</code>
            </td>
            <td>
              <strong
                >Returns an ID or Code associated with the postcode.</strong
              >
              Typically, these are a 9 character code known as an ONS Code or
              GSS Code.
            </td>
          </tr>
          <tr id="code-scottish_parliamentary_constituency">
            <td>
              codes.scottish_parliamentary_constituency <br />
              <code>string</code>
            </td>
            <td>
              <strong>Scottish Parliamentary Constituency GSS Code. </strong> A
              code that identifies a 2014 Scottish Parliamentary Constituency.
            </td>
          </tr>
        </tbody>
      </table>
      <h4>
        Terminated Postcode Data (Ordnance Survey Postcode Directory Dataset)
      </h4>
      <p>Data returned by the <code>/terminated_postcodes/*</code> APIs</p>
      <table class="table table-hover">
        <thead>
          <tr>
            <th>Field</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr id="postcode-terminated">
            <td>
              postcode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Postcode. </strong>All currently terminated postcodes
              within the United Kingdom, the Channel Islands and the Isle of
              Man, received every 3 months from Royal Mail. 2, 3 or 4-character
              outward code, single space and 3-character inward code.
            </td>
          </tr>
          <tr id="year-terminated">
            <td>
              year_terminated <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Termination year. </strong>Year of termination of a
              postcode.
            </td>
          </tr>
          <tr id="month-terminated">
            <td>
              month_terminated <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Termination month. </strong>Month of termination of a
              postcode. 1-January, 2-February ... 12-December.
            </td>
          </tr>
          <tr id="longitude-terminated">
            <td>
              longitude <br />
              <code>double float</code>
            </td>
            <td>
              <strong>Longitude. </strong>The WGS84 longitude given the
              Postcode's national grid reference.
            </td>
          </tr>
          <tr id="latitude-terminated">
            <td>
              latitude <br />
              <code>double float</code>
            </td>
            <td>
              <strong>Latitude. </strong>The WGS84 latitude given the Postcode's
              national grid reference.
            </td>
          </tr>
        </tbody>
      </table>
      <h4>Places Data (Ordnance Survey Open Names Dataset)</h4>
      <p>Data returned by the <code>/places</code> API</p>
      <p>
        <b>Note:</b> Some fields may be <code>null</code> if not applicable or
        populated. These fields return type is specified as
        <code>type|null</code>
      </p>
      <table class="table table-hover">
        <thead>
          <tr>
            <th>Field</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr id="places-code">
            <td>
              code <br />
              <code>string</code>
            </td>
            <td>
              <strong>code.</strong> A unique identifier that enables records to
              be identified easily. The identifier will be persistent for all
              LocalTypes except Section of Named Road and Section of Numbered
              Road.
            </td>
          </tr>
          <tr id="places-eastings">
            <td>
              eastings <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Eastings.</strong> The Ordnance Survey postcode grid
              reference Easting to 1 metre resolution; blank for postcodes in
              the Channel Islands and the Isle of Man.
            </td>
          </tr>
          <tr id="places-northings">
            <td>
              northings <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Northings.</strong> The Ordnance Survey postcode grid
              reference Northing to 1 metre resolution; blank for postcodes in
              the Channel Islands and the Isle of Man.
            </td>
          </tr>
          <tr id="places-maxminnorthingseastings">
            <td>
              [max|min]_northings, [max|min]_eastings <br />
              <code>integer</code>
            </td>
            <td>
              <strong>Maximum &amp; Minimum, Northings &amp; Eastings.</strong>
              Bounding box or Minimum Bounding Rectangle (MBR) for roads and
              settlements. For Settlements and Sections of Named and Numbered
              Roads, the MBR gives a representation of the extent of these
              features and is not snapped to the real world extent.
            </td>
          </tr>
          <tr id="places-country">
            <td>
              country <br />
              <code>string</code>
            </td>
            <td>
              <strong>Country.</strong> OS Places relates to Great Britain only.
              i.e. <code>England</code>, <code>Scotland</code>, <code>Wales</code>.
            </td>
          </tr>
          <tr id="places-longitude">
            <td>
              longitude <br />
              <code>double float</code>
            </td>
            <td>
              <strong>Longitude.</strong> The WGS84 longitude given the Place's
              national grid reference.
            </td>
          </tr>
          <tr id="places-latitude">
            <td>
              latitude <br />
              <code>double float</code>
            </td>
            <td>
              <strong>Latitude.</strong> The WGS84 latitude given the Place's
              national grid reference.
            </td>
          </tr>
          <tr id="places-local_type">
            <td>
              local_type <br />
              <code>string</code>
            </td>
            <td>
              <strong>Local Type.</strong> The Ordnance Survey classification
              for the named place being represented by the specific feature,
              e.g. <code>City</code>, <code>Town</code>, <code>Village</code>,
              <code>Hamlet</code>, <code>Other Settlement</code>,
              <code>Suburban Area</code>.
            </td>
          </tr>
          <tr id="places-outcode">
            <td>
              outcode <br />
              <code>string</code>
            </td>
            <td>
              <strong>Outcode.</strong> The postcode district, for example,
              <code>SO15</code>.
            </td>
          </tr>
          <tr id="places-name-1">
            <td>
              name_1 <br />
              <code>string</code>
            </td>
            <td>
              <strong>Name.</strong> The proper noun that applies to the real
              world entity. Names that are prefixed by the definite article are
              not formatted for alphabetical sorting, that is, ‘The Pennines’
              not ‘Pennines, The’.
            </td>
          </tr>
          <tr id="places-name-1-lang">
            <td>
              name_1_lang <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Language of Name.</strong> The language type is only set
              where more than one name exists, e.g. <code>cym</code> (Welsh),
              <code>eng</code> (English), <code>gla</code> (Scottish Gaelic).
            </td>
          </tr>
          <tr id="places-name-2">
            <td>
              name_2 <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Name (in case of multiple languages).</strong> The proper
              noun that applies to the real world entity. Names that are
              prefixed by the definite article are not formatted for
              alphabetical sorting, that is, ‘The Pennines’ not ‘Pennines, The’.
            </td>
          </tr>
          <tr id="places-name-2-lang">
            <td>
              name_2_lang <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Language of Name.</strong> The language type is only set
              where more than one name exists, e.g. cym (Welsh), eng (English),
              gla (Scottish Gaelic).
            </td>
          </tr>
          <tr id="places-county-unitary">
            <td>
              county_unitary <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Administrative Area.</strong> The name of the County
              (non-metropolitan or Metropolitan), Unitary Authority or Greater
              London Authority administrative area that the point geometry for
              feature is within or nearest to.
            </td>
          </tr>
          <tr id="places-county-unitary-type">
            <td>
              county_unitary_type <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Administrative Area Type.</strong> Classifies the type of
              administrative unit.
            </td>
          </tr>
          <tr id="places-district-borough">
            <td>
              district_borough <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>District or Borough.</strong> The name of the District,
              Metropolitan District or London Borough administrative unit that
              the point geometry for the feature is within.
            </td>
          </tr>
          <tr id="places-district-borough-type">
            <td>
              district_borough_type <br />
              <code>string|null</code>
            </td>
            <td>
              <strong>Borough Type.</strong> Classifies the type of
              administrative unit.
            </td>
          </tr>
          <tr id="places-region">
            <td>
              region <br />
              <code>string</code>
            </td>
            <td>
              <strong>Region.</strong> The name of the European Region (was
              Government O ice Region) that the point geometry for the feature
              is within or nearest to.
            </td>
          </tr>
        </tbody>
      </table>
      <h2 class="doc-header anchor" id="Methods">Methods</h2>
      <h4>The following is a list of available API methods</h4>
      <h3 id="Postcode-Lookup">Postcode Lookup</h3>
      <p>This uniquely identifies a postcode.</p>
      <p>
        Returns a single postcode entity for a given postcode (case, space
        insensitive).
      </p>
      <p>If no postcode is found it returns "404" response code.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes/:postcode</h4></pre>
      <h3 id="Bulk-Postcode-Lookup">Bulk Postcode Lookup</h3>
      <p>
        Accepts a JSON object containing an array of postcodes. Returns a list
        of matching postcodes and respective available data.
      </p>
      <p>
        Be sure to submit JSON requests setting <code>Content-Type</code> to
        <code>application/json</code>
      </p>
      <p>Accepts up to 100 postcodes.</p>
      <pre><h4><div class="http-method">POST</div>https://api.postcodes.io/postcodes</h4></pre>
      <h4>Post Data</h4>
      <p>
        This method requires a JSON object containing an array of postcodes to
        be posted, e.g.
      </p>
      <pre>
{
  "postcodes" : ["PR3 0SG", "M45 6GN", "EX165BL"]
}</pre
      >
      <h4>Optional Query Parameters</h4>
      <p>
        <code>filter=</code> (not required) A comma separated whitelist of
        attributes to be returned in the result object(s), e.g.
        <code>filter=postcode,longitude,latitude</code>.
        <code>null</code> responses will continue to return <code>null</code>.
        If no attributes match the result object, an empty object is returned
      </p>
      <h3 id="Geocode-Postcode">Reverse Geocoding</h3>
      <p>Returns nearest postcodes for a given longitude and latitude.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes?lon=:longitude&amp;lat=:latitude</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <p>
        <code>radius=</code> (not required) Limits number of postcodes matches
        to return. Defaults to 100m. Needs to be less than 2,000m.
      </p>
      <p>
        <code>widesearch=</code> (not required) Search up to 20km radius, but
        subject to a maximum of 10 results. Since lookups over a wide area can
        be very expensive, we've created this method to allow you choose to make
        the trade off between search radius and number of results. Defaults to
        false. When enabled, radius and limits over 10 are ignored.
      </p>
      <h4>Additional Response Attributes</h4>
      <p><code>distance</code> Distance in metres from specified postode</p>
      <h4>Legacy</h4>
      <p>
        Note that the old style of reverse geocoding (including optional headers
        above) will still be supported. Namely,
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes/lon/:longitude/lat/:latitude</h4></pre>
      <h3 id="Bulk-Geocode-Postcode">Bulk Reverse Geocoding</h3>
      <p>
        Bulk translates geolocations into Postcodes. Accepts up to 100
        geolocations.
      </p>
      <pre><h4><div class="http-method">POST</div>https://api.postcodes.io/postcodes</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Applies a global limit parameter to all geolocation lookup objects. Defaults to 10. Needs to be less than 100.
      </p>
      <p>
        <code>radius=</code> (not required) Applies a global search radius to all geolocation lookup objects. Defaults to 100m. Needs to be less than 2,000m.
      </p>
      <p>
        <code>widesearch=</code> (not required) Applies a global widesearch parameter to all geolocation lookup objects. Defaults to `false`.
      </p>
      <h4>Post Data</h4>
      <p>
        This method requires a JSON object containing an array of geolocation
        objects to be POSTed. Each geolocation object accepts an optional radius
        (metres) and limit argument. Both default to 100m and 10 respectively.
        It also accepts a widesearch argument, e.g.
      </p>
      <pre>
{
  "geolocations" : [{
  "longitude" : -3.15807731271522,
  "latitude" : 51.4799900627036
  },{
  "longitude" : -1.12935802905177,
  "latitude" : 50.7186356978817,
  "limit" : 100,
  "radius" : 500
  }]
}</pre
      >
      <h4>Optional Geolocation Object Parameters</h4>
      <p>
        <code>filter=</code> (not required) A comma separated whitelist of
        attributes to be returned in the result object(s). e.g.
        <code>filter=postcode,longitude,latitude</code>.
        <code>null</code> responses will continue to return <code>null</code>.
        If no attributes match the result object, an empty object is returned
      </p>
      <p>
        <code>widesearch=</code> (not required) Search up to 20km radius, but
        subject to a maximum of 10 results
      </p>
      <h4>Additional Response Attributes</h4>
      <p><code>distance</code> Distance in metres from specified postode</p>
      <h3 id="Postcode-Query">Postcode Query</h3>
      <p>
        Submit a postcode query and receive a complete list of postcode matches
        and all associated postcode data.
      </p>
      <p>
        This is essentially a postcode search which prefix matches and returns
        postcodes in sorted order (case insensitive)
      </p>
      <p>
        This method is space sensitive, i.e. it detects for spaces between
        outward and inward parts of the postcode (some examples detailed
        <a href="https://github.com/ideal-postcodes/postcodes.io/issues/44"
          >in this issue</a
        >)
      </p>
      <p>
        The result set can either be empty or populated with up to 100 postcode
        entities. Either way it will always return a 200 response code
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes?q=[query]</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p><code>query=</code> (not required) aliases to<code>q=</code></p>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <h3 id="Postcode-Validation">Postcode Validation</h3>
      <p>
        Convenience method to validate a postcode. Returns true or false
        (meaning valid or invalid respectively)
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes/:postcode/validate</h4></pre>
      <p>View our guide on <a href="https://ideal-postcodes.co.uk/guides/postcode-validation">postcode validation</a> to see a more detailed explanation</p>
      <h3 id="Nearest-Postcode">Nearest Postcode</h3>
      <p>Returns nearest postcodes for a given postcode.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes/:postcode/nearest</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <p>
        <code>radius=</code> (not required) Limits number of postcodes matches
        to return. Defaults to 100m. Needs to be less than 2,000m.
      </p>
      <h4>Additional Response Attributes</h4>
      <p><code>distance</code> Distance in metres from specified postode</p>
      <h3 id="Postcode-Autocomplete">Postcode Autocomplete</h3>
      <p>Convenience method to return an list of matching postcodes.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/postcodes/:postcode/autocomplete</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <h3 id="Random-Postcode">Random Postcode</h3>
      <p>Returns a random postcode and all available data for that postcode.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/random/postcodes</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>outcode=</code> (not required) Filters random postcodes by
        outcode. Returns null if invalid outcode.
      </p>
      <h3 id="Show-Outcode">Outward Code Lookup</h3>
      <p>
        Geolocation data for the centroid of the outward code specified. The
        outward code represents the first half of any postcode (separated by a
        space).
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/outcodes/:outcode</h4></pre>
      <h3 id="Geocode-Outcode">Outcode Reverse Geocoding</h3>
      <p>Returns nearest outcodes for a given longitude and latitude.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/outcodes?lon=:longitude&amp;lat=:latitude</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <p>
        <code>radius=</code> (not required) Limits number of postcodes matches
        to return. Defaults to 5,000m. Needs to be less than 25,000m.
      </p>
      <h3 id="Nearest-Outcode">Nearest Outcode</h3>
      <p>Returns nearest outcodes for a given outcode.</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/outcodes/:outcode/nearest</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p>
        <code>limit=</code> (not required) Limits number of postcodes matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <p>
        <code>radius=</code> (not required) Limits number of postcodes matches
        to return. Defaults to 5,000m. Needs to be less than 25,000m.
      </p>
      <h3 id="scottish-postcode">Scottish Postcode Lookup</h3>
      <p>
        Lookup a Scottish postcode. Returns SPD data associated with postcode.
        At the moment this is just Scottish Parliamentary Constituency.
      </p>
      <p>
        Returns 404 if postcode does not exist in SPD or is not valid. For
        postcodes not in SPD but in ONSPD, 404 is returned with error message
        <code>Postcode exists in ONSPD but not in SPD</code>.
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/scotland/postcodes/:postcode</h4></pre>
      <h3 id="Terminated">Terminated Postcode Lookup</h3>
      <p>
        Lookup a terminated postcode. Returns the postcode, year and month of
        termination. Returns 404 if postcode does not exist in our database of
        terminated postcodes or not valid.
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/terminated_postcodes/:postcode</h4></pre>
      <h3 id="Place-Lookup">Place Lookup</h3>
      <p>
        Find a place by OSGB code (e.g. "osgb4000000074564391"). Returns all
        available data if found. Returns 404 if place does not exist.
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/places/:code</h4></pre>
      <h3 id="Place-Query">Place Query</h3>
      <p>
        Submit a place query and receive a complete list of places matches and
        associated data.
      </p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/places?q=[query]</h4></pre>
      <h4>Optional Query Parameters</h4>
      <p><code>query=</code> (not required) aliases to<code>q=</code></p>
      <p>
        <code>limit=</code> (not required) Limits number of places matches to
        return. Defaults to 10. Needs to be less than 100.
      </p>
      <h3 id="Random-Place">Random Place</h3>
      <p>Returns a random place and all associated data</p>
      <pre><h4><div class="http-method">GET</div>https://api.postcodes.io/random/places</h4></pre>

      <hr />

      <h2 class="doc-header anchor" id="Install-notes">
        Self Hosting &amp; Local Installations
      </h2>

      <p>
        There may be occasions where you want to host postcodes.io yourself.
        We've laid out instructions below on how to do this.
      </p>
      <p>
        We currently provide 4 methods to import the necessary datasets and run
        the postcodes.io API application:
      </p>
      <ol>
        <li>
          <strong>Docker Installation.</strong> Use our Docker application and
          database images.
        </li>
        <li>
          <strong>Install Script</strong>. Clone the repository, install
          dependencies and <code>npm run setup</code>. This will download the
          database and import the data from a <code>pg_dump</code> into a
          locally running instance of PostgreSQL.
        </li>
        <li>
          <strong>Manual Installation via</strong> <code>pg_dump</code>. You can download the
          <code>pg_dump</code> and attempt to import the database yourself with
          <code>psql</code> or <code>pg_restore</code>.
        </li>
        <li>
          <strong>Manual Installation</strong>. Retrieve the raw CSV datasets
          from Ordnance Survey and ONS; then import it with our import scripts.
        </li>
      </ol>

      <h3 class="doc-header anchor" id="docker-install">
        1. Docker Installation
      </h3>

      <p>
        Postcodes.io can be installed using two Docker containers: the
        postcodes.io application container and the postcodes.io database
        container.
      </p>

      <h4 id="docker-install-requirements">Requirements</h4>
      <ul>
        <li>
          Local copy of
          <a href="https://github.com/ideal-postcodes/postcodes.io">postcodes.io repository</a
          >
        </li>
        <li><a href="https://docker.com">Docker</a></li>
      </ul>

      <h4>Quickstart</h4>

      <p>
        If you want to launch the postcodes.io HTTP interface and underlying
        database quickly, you may do so with <code>docker-compose</code>.
      </p>

      <p>Clone the project repository and run docker-compose:</p>

      <pre>$ docker-compose up -d</pre>

      <p align="center">
        <img
          src="https://img.ideal-postcodes.co.uk/postcodesio-docker-compose-demo.gif"
          alt="Docker Compose Demo"
        />
      </p>

      <p>
        Running the above command in your terminal will create and network the
        containers. The HTTP service will be available on port
        <code>8000</code>.
      </p>

      <h4>Application Container</h4>

      <p>
        The Postcodes.io application, which provides the HTTP interface, is
        packaged as a Docker container identified on the Docker Hub as
        <code>idealpostcodes/postcodes.io</code>.
      </p>

      <p>Example usage:</p>
      <pre>$ docker run -d -p 8000 idealpostcodes/postcodes.io</pre>

      <p>Configuration available via Environment Variables:</p>
      <ul>
        <li><code>POSTGRES_USER</code></li>
        <li><code>POSTGRES_PASSWORD</code></li>
        <li><code>POSTGRES_DATABASE</code></li>
        <li><code>POSTGRES_HOST</code></li>
        <li><code>POSTGRES_PORT</code></li>
        <li><code>PORT</code> (HTTP Port to run on)</li>
      </ul>

      <h4>Database Container</h4>
      <p>
        <code>idealpostcodes/postcodes.io.db</code> points to a
        <a href="https://hub.docker.com/r/mdillon/postgis/"
          >PostgreSQL &amp; PostGIS</a
        >
        base image and preloads the latest <code>pg_dump</code> in the
        initialisation process.
      </p>

      <p>
        The database Docker image is updated with new releases of the ONSPD dataset.
        See the <a href="https://github.com/ideal-postcodes/postcodes.io/blob/master/CHANGELOG.md">Changelog</a> for when a new dataset has been ingested.
      </p>

      <p>
        <strong>Take Note:</strong> Upon starting a container for the first
        time, PostGIS will be enabled and the <code>pg_dump</code> will take
        15-60s to restore depending on your system resources.
      </p>

      <p>Example usage:</p>

      <pre>
$ docker run -p 5432 -e POSTGRES_USER=postcodesio -e POSTGRES_DB=postcodesiodb -e POSTGRES_PASSWORD=password idealpostcodes/postcodes.io.db</pre
      >

      <p>
        As this contains the official PostreSQL base image, the available
        configuration environment variables are documented at:
        <a href="https://hub.docker.com/_/postgres/"
          >hub.docker.com/_/postgres/</a
        >
      </p>

      <h3 id="install-script">2. Install Script</h3>

      <h4 id="install-requirements">Requirements</h4>

      <ul>
        <li>
          Local copy of
          <a href="https://github.com/ideal-postcodes/postcodes.io"
            >postcodes.io repository</a
          >
        </li>
        <li><a href="https://nodejs.org">Node.js</a></li>
        <li>
          <a href="https://postgis.net/install/">PostgreSQL and PostGIS</a>
        </li>
      </ul>
      <p>
        Currently the install process targets Linux and macOS systems. Please
        <a href="/about">let us know</a> if you have issues on those or any
        other operating systems.
      </p>
      <p>
        Postcodes.io is packaged with a<a
          href="https://github.com/ideal-postcodes/postcodes.io/blob/master/bin/setup.sh"
        >
          script</a
        >
        to provision PostgreSQL and download a dump of the dataset. The script
        will:
      </p>
      <ul>
        <li>
          Prompt you for your PostgreSQL superuser credentials (most of the
          setup steps require this level of privilege)
        </li>
        <li>Create a new database</li>
        <li>Create a new readonly user for the new database</li>
        <li>
          Download, unzip and stream the <code>pg_dump</code> into the new
          database
        </li>
      </ul>
      <p>To run,</p>
      <pre>$ npm run setup</pre>

      <h3 id="import-from-pgdump">
        3. Manual Installation <code>pg_dump</code>
      </h3>

      <p>
        You can download a <code>pg_dump</code> of the database. This is the
        same dump used by the install script. The link to the latest dump can be
        found in our<a
          href="https://github.com/ideal-postcodes/postcodes.io/blob/master/latest"
        >
          repository.</a
        >
      </p>
      <p>
        To setup the database from our <code>pg_dump</code> download,
        <code>gunzip</code> and use either <code>psql</code> or
        <code>pg_restore</code> to import the data into PostgreSQL.
      </p>
      <p>For example,</p>
      <pre>$ cat postcodeiodb.sql | psql postcodesiodb</pre>

      <h3 id="import-from-ons">4. Manual Installation</h3>
      <p>
        The install scripts can be linked to your shell (or can be found in the
        <code>bin/</code> directory). To link, navigate to
        <code>postcodes.io/</code> and run <code>$ npm link</code>
      </p>
      <br />

      <h4>ONS Postcode Directory</h4>
      <p>
        Download the latest Office for National Statistics "Postcode Lookup
        Dataset". Unzip the data locally. Run the import script
        <code>$ postcodesio-onspd</code> passing the path to the CSV data.
      </p>
      <pre>$ postcodesio-onspd /path/to/data/ONSPD/Data/data.csv</pre>
      <br />

      <h4>Scottish Postcode Directory</h4>
      <p>
        Download the latest National Records Scotland "Scottish Postcode
        Directory". Unzip the data locally. Run the import script
        <code>$ postcodesio-scotpd</code> passing the path CSV data directory.
      </p>
      <pre>$ postcodesio-scotpd /path/to/data</pre>
      <br />

      <h4>OS Open Names</h4>
      <p>
        Download the latest Ordnance Survey Open Names dataset. Unzip the data
        locally. Run the import script <code>$ postcodesio-oson</code> passing
        the path that contains the CSV data files.
      </p>
      <pre>$ postcodesio-oson /path/to/data/opname_csv_gb/Data/</pre>

      <h3 id="configuration">Configuration</h3>
      <p>
        Application configuration is documented in
        <a
          href="https://github.com/ideal-postcodes/postcodes.io/blob/master/config/README.md"
          >the configuration README</a
        >
        at <code>/config/README.md</code>.
      </p>
      <p></p>
    </div>
  </div>
</div>
