UK Data AtlasAPI

Search places by name

Type a place name and get back every area it could mean. Place names are slippery: "Newport" is thirteen different areas across Wales, the Isle of Wight and Shropshire. Rather than guessing, this lists them all so you can choose.

get
/places

Good to know

  • Matching ignores case, accents, punctuation and ampersands, so Brighton & Hove and Ynys Mon find what was published.
  • Official titles are set aside too: "Bristol" finds the council published as "Bristol, City of".
  • Each result has a place reference, like localAuthority/E06000023, that you can pass straight to Get a value for a place.

Query parameters

  • qstringrequired

    A place name, an area code, a unit postcode, or a place reference such as localAuthority/E08000003 or postcode/SW1A1AA.

  • limitinteger 1–500optional

    How many candidate places to return, 1 to 500.

    Default10
  • asOfstringoptional

    Select the member codes effective on this date for curated named locations. Omit it to return the complete dated definition.

  • geographystringoptional

    Restrict an exact area lookup to one geography type.

  • releasestringoptional

    Restrict an exact area lookup to one boundary release.

  • datestringoptional

    Calendar date (YYYY-MM-DD) or month (YYYY-MM) that selects a release. Requires geography and cannot be combined with release.

  • countrystringoptional

    Restrict a date-selected release to one country.

    One ofGB-ENGGB-NIRGB-SCTGB-WLS

Returns

Envelope

The candidate places, best match first. Empty when nothing matches.

  • apiVersionv1required
  • atlasReleasestringrequired

    The immutable /atlas-release releaseId for the artifacts that produced this response.

  • metaobjectrequired
    Show1 child field
    • nextCursorstring | nullrequired

      Opaque cursor for the next page, or null at the end.

When it goes wrong

  • 400A query parameter is malformed or its cursor is not valid for this result set.
  • 503The referenced build artifact has not been built yet.

Every error has the same shape. See Errors for how to handle them.

Technical notes

Show the precise behaviour

Turns a name into candidate places, each saying what kind of place it is. A name is rarely one area: "Manchester" is a local authority, a county and unitary authority, a major town, a travel to work area and a ward, and "Newport" is thirteen codes across Wales, the Isle of Wight and Shropshire. This never chooses among them.

Names match with case, accents, punctuation and the ampersand set aside, so "Brighton & Hove" and "Ynys Mon" find what was published, and an alias matches as well as a name. An administrative title is set aside too, so "Bristol" finds the authority published as "Bristol, City of", reported as exact-without-title. Names that merely begin with the query follow, as prefix, once equal names leave room: "Richmond" lists its wards and parish first, then Richmond upon Thames. A bare area code, or a place reference, is looked up directly.

A place held in several releases is returned once, with its releases newest first. Equal matches are listed headline geographies first, then wards and smaller areas; that is a presentation order and asserts nothing about which was meant. Curated named locations appear with their member codes, or the codes active on asOf.

A unit postcode, typed in any case and with or without its space, leads the candidates as a place of its own: kind postcode, a place reference such as postcode/SW1A1AA, its centroid as point, and an href to /postcodes/{postcode}, which places it in areas. Nothing is placed here, so a search stays as fast as a name lookup. Pass the reference as place to /data/{measure-id}/value to answer a measure for the postcode. A query that reads as a postcode district or sector, or a unit postcode the directory does not hold or this API may not serve, carries a postcodeHint saying so.

Add geography or release to resolve only exact area identities in that scope. date, with a geography, selects the latest published release on or before that date; country can narrow that selection.