Vepler logo
v5.34.0

Look up what contains an area, what it contains, and where its record came from

Six geography endpoints answer what contains an area, what it contains and where its record came from, with a fit on every row. Land constraint metadata gains two keys.

Added

  • GET /v1/geography/areas/{codes} looks up areas by GSS code, up to 100 comma-separated codes in one request. Each area carries code, areaType, vintage, name, nation and tier. nation is ENG, WAL, SCO or NIR, and null for an area that crosses a border. name is null where the publisher gives none, and is not unique. Narrow the lookup with areaType or vintage; without them every edition held comes back.
  • GET /v1/geography/areas/{code}/ancestors lists everything that contains an area, and GET /v1/geography/areas/{code}/descendants everything inside it. Each row adds depth, which is 1 for a direct relationship, and minFit, which is exact, best_fit or spatial and reports the weakest fit anywhere along the path. Anything other than exact means a figure summed along that path is an approximation, so carry minFit into any aggregation you build on it. Return only ancestors at one tier with tier, or only descendants of one layer with descendantType.
  • Descendants are paged with limit, from 1 to 1,000 and 100 by default, and offset, and total_count reports the size of the whole set. A unitary authority is both a district and a county under one code, so set areaType to the layer you mean: a request without it returns each descendant once for each layer the code belongs to.
  • GET /v1/geography/areas/{code}/children lists only the immediate children of an area, each with its fitType and sourceId. Return only children of one layer with childType.
  • GET /v1/geography/areas/{code}/provenance says where an area's record came from: custodian, title, url, licence, fetchedAt, and attribution, the acknowledgement line the custodian requires, to reproduce verbatim wherever you pass the data on. sha256 identifies the exact file the record was read from, and fromArchive is true when that file came from an archived copy because the publisher could not be reached.
  • GET /v1/geography/release returns the current geography release. Ancestors, descendants and children accept release to pin a query to one release, and follow the current release when it is left out. A code or release the graph does not hold returns an empty data list rather than a 404.
  • The place graph returns areas and the relationships between them, not boundaries. It is available on the same product access as /v1/area-reference and /v1/location.
  • Land constraint designations carry two more metadata keys on POST /v1/land-constraint/designations/query and GET /v1/land-constraint/designations/{designationId}. On an Article 4 direction area, permitted_development_rights records which rights the direction withdraws, in the local authority's own wording: most entries are semicolon-separated class codes from the Town and Country Planning (General Permitted Development) (England) Order 2015, such as 1A;1C;1D;1F;2A;2B, and the rest are a sentence naming the Parts and Classes, so parse it defensively. On an agricultural land classification area, bmv is true where the grade counts as Best and Most Versatile agricultural land. Like the rest of metadata, both keys need the designationSourceData permission on your licence, and the reference lists the keys each designation product returns.

Affected endpoints