Search by Address

Check territory availability from an address.

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

Request data

HTTPS Method: `GET`

Request credit cost

Each request uses:

1 Territory Checker credit, AND
10 API credits

URL Request Format

https://api.vision-mapping.com/v3/territory-checker/address?apiKey={apiKey}&pot={pot}&address={address}&region={region}&minimumAccuracy={minimumAccuracy}

URL Request Example

https://api.vision-mapping.com/v3/territory-checker/address?apiKey={apiKey}&pot={pot}&address=8A%20Cyrus%20Way%20Hampton%20PE7%208HP&region=GB&minimumAccuracy=2

Request parameters

Required parameters must be used or the call will fail.
Optional parameters may be used.
Placeholders enclosed in curly braces (e.g. {apiKey}) must be replaced with their actual value.
The order of request parameters is not important.

Parameter	Type	Notes
apiKey	String	Required. API key of the organisation.
pot	String	Required. The identifier of the pot being queried.
address	String	Required. Value must be between 1 and 512 characters in length. Should be properly URL encoded.
region	String	Required. Must be a 2-character ISO 3166 Alpha-2 country code.
minimumAccuracy	Int	Optional. Default value is 2. Allowed values: 1 - Rooftop 2 - Street or Street Segment 3 - Geometric centre (centre of polygon/polyline) 4 - Approximate

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

{
  "matchedAddress": {
    "address": {
      "lines": [
        "8A",
        "Cyrus Way"
      ],
      "city": "District",
      "county": "Peterborough",
      "postcode": "PE7 8HP",
      "country": "United Kingdom"
    },
    "coordinates": {
      "lat": 52.5430597,
      "lon": -0.255117
    },
    "accuracy": 1
  },
  "result": {
    "availability": "Available",
    "searchRadiusInMetres": 16093.44  
  }
}

Response fields

Primary fields

Field

Description

matchedAddress

Object.

Summary information about the geocoded address.

result

Object.

Contains details about the result.

matchedAddress object

Field	Description
address	Object. Structured address object.
coordinates	Object. Coordinates of the matched address.
accuracy	Accuracy of the matched address. Possible values: 1 - Rooftop 2 - Street or Street Segment 3 - Geometric centre (centre of polygon/polyline) 4 - Approximate

address object

Field	Description
lines	String array.
city	String.
county	String.
postcode	String.
country	String.

coordinates object

Field	Description
lat	Double.
lon	Double.

result object

Field

Description

availability

String.

Possible values:

Available
Unavailable
Pending

searchRadiusInMetres

Double.

The radius of the search area, in metres, from the geocoded co-ordinates.

Response codes

Code

Description and possible causes

200

The search was successful and returned zero or more results.

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.
Subscription does not include Territory Checker.

404

Not Found

The pot was not found.

422

Unprocessable Entity

Possible causes include:

No result was found when geocoding the address.
The address was geocoded, but the accuracy did not meet the minimumAccuracy requested.

429

Too Many Requests

The API key is over the QPS limit.

500

Internal Server Error

Something went wrong at our end.

504

Gateway Timeout

The geocoding request did not complete in time.

Error response

Error bodies are provided in the problem+json format.