Terrafab by SigSenAI

Terrafab is a service that maps postcodes and geographical points to administrative areas. It’s useful for anyone who has the co-ordinates of a particular point, and needs to find out what regions it lies within. It’s also great for looking up the shapes of all those boundaries.

Terrafab API Documentation

The documentation below is for developers who want to use Terrafab as a billed web service, describing its versioned REST API. If that’s all Greek to you, please see our page for non-developers.

API version and base URL

Programmatic access uses the versioned API under /api/v1/. The same endpoints are also available at /v1/ and /v1/boundaries/.

Responses include an X-API-Version header. Deprecated versions also return Deprecation: true.

Authentication

All versioned API requests require an organization API key. Send it as a Bearer token, an X-API-Key header, or an api_key query parameter: 

Authorization: Bearer sk_live_…
X-API-Key: sk_live_…
GET /api/v1/area/123?api_key=sk_live_…

All API responses include your current usage and limit in the X-Quota-Current and X-Quota-Limit response headers.

You can create and manage keys, including allowed host restrictions, from your customer dashboard.

Billing and access

API access requires an active subscription on your organization. Usage is metered against your plan limits. Manage subscriptions from the dashboard or start checkout via the billing API:

Billing API calls use your logged-in session (not an API key). Legacy unversioned paths at the site root remain for compatibility but new integrations should use /api/v1/.

lookup by postcode

URL:
/api/v1/postcode/[postcode]
Returns:

Information on a particular postcode, including its centroid location in WGS84 latitude/longitude, and the areas that is contained within.

Optional query parameters:
  • generation, to return results from a previous generation.
  • min_generation, to return results since that generation.
  • max_generation, to return results up to that generation, not active after.

lookup by partial postcode

URL:
/api/v1/postcode/partial/[partial postcode]
Returns:

Geographical details for the centroid of the partial postcode specified.

lookup by point

URL:
  • /api/v1/point/[SRID]/[x],[y]
  • /api/v1/point/[SRID]/[x],[y]/box
Parameters:

SRID 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.

x and y are the co-ordinates of the point in the co-ordinate system; note that x,y means longitude,latitude.

Optional query parameters:
  • type, to restrict results to a particular area type or types (multiple types separated by commas);
  • generation, to return results for a previous generation.
  • min_generation, to return results since that generation.
  • max_generation, to return results up to that generation, not active after.
  • country, to restrict results to areas with particular country codes (multiple country codes separated by commas).
Returns:

A hash of the areas that the point is contained within. If the /box version is used, only the area bounding boxes are considered.

lookupnearest postcode

URL:
/api/v1/nearest/[SRID]/[x],[y]
Parameters:
Same as for by point.
Returns:
The postcode closest to the particular point.

lookup by area

URL:
  • /api/v1/area/[area ID]
  • /api/v1/area/[area ID]/example_postcode
  • /api/v1/area/[area ID]/geometry
  • /api/v1/area/[area ID].[kml or geojson or wkt]
  • /api/v1/area/[SRID]/[area ID].[kml or json or wkt]
Optional query parameters:
simplify_tolerance, a floating point parameter to simplify the polygons returned.
Returns:
Information on a particular area, including name, type, parent, and any associated codes (see below for details). 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.

lookup multiple areas

URL:
  • /api/v1/areas/[area IDs]
  • /api/v1/areas/[area IDs]/geometry
  • /api/v1/areas/[area IDs].[kml|geojson]
  • /api/v1/areas/[type(s)]
  • /api/v1/areas/[name prefix]
Parameters:
Separate multiple parameters with commas. Name prefix means it will return any area that starts with the string given.
Optional query parameters:
  • generation, to return areas in that generation (type and name lookups only).
  • min_generation, to return areas since that generation (type and name lookups only).
  • max_generation, to return results up to that generation, not active after (ditto)..
  • type, to restrict results to a type or types (multiple separated by commas; name lookup only).
  • country, to restrict results to areas with particular country codes (multiple separated by commas; type and name lookups only).
Returns:

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.

lookup by code

URL:
  • /api/v1/code/[code type]/[code]
Parameters:
code type and a code should uniquely identify an area. (Terrafab uses code types and codes to associate external identifiers with areas.)
Returns:

This returns an HTTP 302 Found redirect to the corresponding /api/v1/area/[area ID] page. Any format extension (.html or .json) will be preserved in the URL that's redirected to.

Types

URL:
/api/v1/types
Returns:
A list of all area types in this installation of Terrafab.
Example
List of types

Generations

URL:
/api/v1/generations
Returns:
A list of all generations in this installation of Terrafab.
Example
List of generations

Quota

URL:
/api/v1/quota
Returns:
Your current quota usage and limit for boundary API requests. Accessing this endpoint does not count against your limit.
Example
/api/v1/quota

General information

Authentication

Send your organization API key on every request:

Authorization: Bearer sk_live_…
X-API-Key: sk_live_…
?api_key=sk_live_…

All API responses include your current usage and limit in the X-Quota-Current and X-Quota-Limit response headers.

Create keys from the customer dashboard. Requests without a valid key receive 401; inactive keys, disallowed hosts, or missing subscriptions receive 403.

Format

All calls return JSON, you can generally get an HTML representation by sticking .html on the end.

Whenever an area is returned from Terrafab, it is as a dictionary with the following keys: id, name, country, type, parent_area, generation_low, generation_high, codes.

Whenever an error is returned from Terrafab, it is as a dictionary with an error key (which contains a textual description such as “Postcode […] is not valid.” or “Usage limit reached.”) and an optional code key (which, if present, will be a copy of the HTTP status code).

Historical areas
By default, calls will return active areas; for some calls you may specify a previous generation to look up instead.

About Terrafab

Terrafab was written back in 2003 as a postcode lookup to power the original mySociety sites such as WriteToThem. Over time it gained features such as point lookup (for FixMyStreet), 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 Norway, and in 2012 we released a global version based on OpenStreetMap data.

Usage & Licence

API access is billed per organization subscription. Usage is metered against your plan limits; manage billing from the customer dashboard or the billing API.

If you use this service, we ask that you attribute Terrafab at the point of use on sites or apps. Attribution should use the text “Powered by Terrafab”, with a link back to this page.