Create areas and set attributes

Create an area from postcodes and give it attribute values with the API, for example to show revenue per sales area on a 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] or read more about Atlas zoning. How to send the key and other basics: ATLAS API Support.

This example assumes you have a map with an attribute list for its areas. Create the map at app.geposit.se/maps and the attribute list at app.geposit.se/attributes. You need the Map ID.

Note the trailing slashes in the URLs below: without them the API answers with a redirect and nothing is created.

1. Create a group

A group (layer) holds areas (reference):

curl https://app-api.geposit.se/v2.0/layer/ \
  --header 'x-api-key: {API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "type": "area",
    "map_id": "{map_id}",
    "name": "My group"
  }'

The response is the new group; its id is the layer_id for the next step.

2. Create an area

An area (container) belongs to a group (reference):

curl https://app-api.geposit.se/v2.0/container/ \
  --header 'x-api-key: {API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "layer_id": "{layer_id}",
    "map_id": "{map_id}",
    "name": "My sales area"
  }'

The response is the new area; its id is the container_id for the next step.

3. Add postcodes to the area

Each postcode becomes a polygon (geography) in the area (reference):

curl https://app-api.geposit.se/v2.0/geometry/polygon/ \
  --header 'x-api-key: {API_KEY}' \
  --header 'content-type: application/json' \
  --data '{
    "country_code": "se",
    "container_id": "{container_id}",
    "map_id": "{map_id}",
    "type": "default",
    "geo_type": "postalcode_5",
    "geo_name": "11127"
  }'

• geo_type says what kind of geography to add, for example postalcode_5, postalcode_3, municipality, county, locality, deso or regso.
• geo_name is the name of the geography; you can send geo_code (the code) instead. For postcodes they are the same.
• country_code must be a region enabled for your team, otherwise the call fails with "no permission for country code".
• To add many geographies in one call, use POST /v2.0/geometry/polygon/multi (reference).

The response contains the new polygon's polygon_id. After these three calls the area is visible in the web app:

4. Set attribute values

Set a value for the postcode (reference). You need the attribute's ID (see Attribute List Item ID) and the Polygon ID:

curl https://app-api.geposit.se/v2.0/attribute/map/{map_id}/object-type/polygon \
  --header 'x-api-key: {API_KEY}' \
  --header 'content-type: application/json' \
  --data '[
    {
      "attribute_id": "{attribute_id}",
      "object_id": "{polygon_id}",
      "object_type": "polygon",
      "type": "numeric",
      "value": 12345
    }
  ]'

The body is a list, so you can set many values in one call. To set one value for a whole area, use object type container with the container ID as object_id.

How values are stored

• Area or geography. A value set on an area (container) applies to all its geographies and replaces their own values. When every geography in an area ends up with the same value, the value is stored on the area instead. So for an area with a single postcode, like this example, the value set above ends up on the area, and the response says "object_type": "container".
• Default values. Setting a value back to the attribute's default_value removes the stored value.

Explore the data in Atlas

Open your map at app.geposit.se/maps to see the areas and their values, filter on attributes and colour the map by value.