Retrieve Geometries for a Postcode using the Atlas API

Get the geometry (shape) of the geographies in the area that covers a postcode, as GeoJSON, for example to draw a delivery area on your own map.

Before you start

You need an API key with access to Geposit Atlas. If you don't have one, contact us at [email protected]. How to send the key and other basics: ATLAS API Support. You also need the Map ID.

1. Find the area that contains the postcode

(reference)

curl https://app-api.geposit.se/v2.0/container/postcode \
  --header 'x-api-key: {API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "map_id": "{map_id}",
    "postcode": "93391",
    "region": "se"
  }'

[
  {
    "id": "CONTAINER_ID",
    "map_id": "MAP_ID",
    "layer_id": "LAYER_ID",
    "name": "Arvidsjaur",
    "visible": true
  }
]

(Shortened.) id is the container ID. Only areas built from postcodes are found this way; see Validate postcode coverage for details.

2. List the geographies in the area

(reference)

curl 'https://app-api.geposit.se/v2.0/container/{container_id}?with_geo_names=true' \
  --header 'x-api-key: {API_KEY}'

{
  "id": "CONTAINER_ID",
  "map_id": "MAP_ID",
  "layer_id": "LAYER_ID",
  "name": "Arvidsjaur",
  "geo_ids_ref_groups": [
    {
      "ref_id": "REF_ID_1",
      "geo_type": "postalcode_5",
      "country": "se",
      "geo_ids": [
        {
          "polygon_id": "POLYGON_ID_1",
          "feature_id": "FEATURE_ID_1",
          "geo_name": "93391",
          "geo_code": "93391"
        }
      ],
      "custom_ids": null
    },
    {
      "ref_id": "REF_ID_2",
      "geo_type": "postalcode_adm",
      "country": "se",
      "geo_ids": [
        {
          "polygon_id": "POLYGON_ID_2",
          "feature_id": "FEATURE_ID_2",
          "geo_name": "93327",
          "geo_code": "93327"
        }
      ],
      "custom_ids": null
    }
  ],
  "custom_polygons": [],
  "area_sq.km": 1323.3
}

The geographies are grouped by dataset: each group has a ref_id (Ref ID) and each geography a feature_id (Feature ID). Shapes drawn by hand are listed in custom_polygons.

3. Get the geometry of each geography

Call this once per geography, with the region, ref_id and feature_id from step 2 (reference):

curl https://app-api.geposit.se/v2.0/datasets/ref/se/{ref_id}/feature/{feature_id}/geojson \
  --header 'x-api-key: {API_KEY}'

{
  "region": "se",
  "ref_id": "REF_ID_1",
  "feature_id": "FEATURE_ID_1",
  "type": "postalcode_5",
  "code": "93391",
  "name": "93391",
  "extra": "",
  "the_geom": "{\"type\":\"Polygon\",\"coordinates\":[[[19.1335792,65.6099202],[19.1356791,65.6131194],…]]}"
}

the_geom is a GeoJSON geometry as a string: parse it before use. Large geographies such as counties can be several hundred kB.

If the region is not enabled for your team, or the geography does not exist, the response is HTTP 404 with {}.