FYN - Address

Find Your Nearest using a free-form 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 FYN credit, AND
10 API credits

URL Request Format

https://api.vision-mapping.com/v3/fyn/address?apiKey={apiKey}&ruleset={ruleset}&address={address}&region={region}&minimumAccuracy={minimumAccuracy}

URL Request Example

https://api.vision-mapping.com/v3/fyn/address?apiKey={apiKey}&ruleset={ruleset}&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.
ruleset	String	Required. The identifier of the ruleset 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
  },
  "results": []
}

Results array element format – JSON

{
  "id": " d3f15688-92d5-4f13-9523-99ffb9f3f02d",
  "name": "John Smith",
  "uniqueKey": null,
  "distance": {
    "miles": 0,
    "km": 0
  },
  "attributes": []
}

Attributes array element format – JSON

{
  "id": "24f5d5f8-44a4-494f-8224-5fac7466be33",
  "type": "String",
  "value": "John Smith"
}

Response fields

Primary fields

Field

Description

matchedAddress

Object.

Summary information about the geocoded address.

results

Object array.

The result list, sorted in ascending order by distance.

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
id	String. The identifier of the result record.
name	String. The name of the result record.
uniqueKey	String or null. The UniqueKey of the result record.
distance	Object.
attributes	Object array.

distance object

Field

Description

miles

Double.

The distance the result is away from the result in miles.

Double.

The distance the result is away from the result in kilometres.

attribute object

Field	Description
id	String.
type	String. Possible values: String Number Bool Address Date
value	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 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 FYN.

404

Not Found

The ruleset 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.