Create Location

Create a new location. Optionally set its classification, and zero or more attribute values.

Note: This endpoint is rate limited to no more than 5 queries per second (QPS).

Request data

HTTPS Method: `POST`

Request credit cost

Each request uses:

1 or 10 API credits. See position object.

URL Request Format

https://api.vision-mapping.com/v3/locations?apiKey={apiKey}

Request parameters

Required parameters must be used or the call will fail.
Placeholders enclosed in curly braces (e.g. {apiKey}) must be replaced with their actual value.

Parameter

Type

Notes

apiKey

String

Required.

API key of the organisation.

Request body

Request structure - JSON

{
  "layer": "da3b3286-223d-484c-b1d0-74a4a166b1ab",
  "name": "My new location",
  "uniqueKey": null,
  "position": {
    "postcode": {
      "value": "PE7 8HP",
      "region": "GB"
    },
    "address": {
      "region": "GB",
      "value": "8A Cyrus Way Hampton Peterborough PE7 8HP",
      "minimumAccuracy": 2
    },
    "coordinates": {
      "lat": 52.5430597,
      "lon": -0.255117
    }
  },
  "classification": {
    "id": "ce93395a-6e2d-407e-bb85-2733351e3488"
  },
  "attributes": [
    {
      "id": "d8f13592-2736-4c28-861b-8fec3df3df4c",
      "type": "Date",
      "value": "2025-09-29"
    },
    {
      "id": "c58717ae-a41f-4ab2-8699-1ce1802d5dc9",
      "type": "Bool",
      "value": true
    },
    {
      "id": "a18f3f18-c8d7-4ac1-9957-71a63a879cc4",
      "type": "Address",
      "value": {
        "lines": [
          "8A",
          "Cyrus Way"
        ],
        "city": "Peterborough",
        "county": "Cambridgeshire",
        "postcode": "PE7 8HP",
        "country": "United Kingdom"
      }
    },
    {
      "id": "cdd89126-36df-4817-a737-9797119c6bbf",
      "type": "String",
      "value": "John Smith"
    },
    {
      "id": "697aaa1c-628a-48d3-836a-607091615a69",
      "type": "Number",
      "value": 100
    }
  ]
}

Request fields

Primary fields

Field	Description
layer	Required. String. The identifier of the layer.
name	Required. String. The name of the location. Value must be between 1 and 100 characters in length.
uniqueKey	Optional. If set, value must be between 1 and 100 characters in length.
position	Required. At least one sub-object must be provided. If multiple methods of positioning are provided, they will be prioritised in the following order: Coordinates Address Postcode (GB only)
classification	Optional. Object.
attributes	Optional. Object array.

position object

Field	Description
address	Optional. Object. Uses 10 API credits.
coordinates	Optional. Object. Uses 1 API credit.
postcode	Optional. Object. Uses 1 API credit. GB only.

address object

Field	Description
value	Required. String. Value must be between 1 and 512 characters.
region	Required. String.
minimumAccuracy	Optional. Int. Default value is 2. Allowed values: 1 - Rooftop 2 - Street or Street Segment 3 - Geometric centre (centre of polygon/polyline) 4 - Approximate

coordinates object

Field	Description
lat	Required. Double.
lon	Required. Double.

postcode object

Field

Description

region

Required. String.

Allowed values: “GB”.

value

Required. String.

Value must be between 5 and 8 characters in length and be a well-formed full UK postcode.

classification object

Field

Description

Required. String.

The identifier of the classification.

attribute object

Field	Description
id	Required. String.
type	Required. String. Possible values: String Number Bool Address Date
value	Required. Varies based on type. If type is String, a String value or null. If type of Number, a double value or null. If type is Bool, a bool value or null. If type is Address, an address object or null. If type is Date, a String value with a date in ISO 8601 format or null.

Response data

Response body

For illustrative purposes the examples below are neatly indented and include all possible response fields. Actual responses are more compact and the data available will vary based on your organisation's settings and stored data.

All responses are in JSON format.

Response structure – JSON

{
  "id": "58018b6c-df4a-4ecc-a690-4e4035ae325e"
}

Response codes

Code

Description and possible causes

201

Created

The location was successfully created.

This code is returned when positioning is determined by coordinates or postcode geocoding.

202

Accepted

The location was accepted for creation.

This code is returned when positioning is determined by address geocoding.

Note: It is possible the location will not be created for the following causes during processing:

The layer was not found.
There was a UniqueKey conflict.
No result was found when geocoding the address.
The address was geocoded, but the accuracy did not meet the minimumAccuracy requested.

400

Bad Request

One or more parameters were incorrectly specified.

401

Unauthorised

API key is missing or invalid.

403

Forbidden

Possible causes include:

Subscription is frozen.
Subscription is not active.
API call count quota reached.

404

Not Found

The layer was not found.

409

Conflict

Another location with the same UniqueKey as the one attempting to be created already exists in the layer.

422

Unprocessable Entity