Postcode

Performs a Find Your Nearest search based on:

A full UK Postcode
A 5-digit USA Zip Code
A full Canadian Postcode

Please note that this endpoint only supports the UK, USA, and Canada.

URL: /fyn/v1/postcode

Method: POST

Method Parameters

Name

Type

Required

Description

apiKey

string

Yes

The API key for your organisation.

model

object

Yes

The object detailing the specified values.

See Model Object Properties.

Model Object Properties

Name	Type	Required	Description
rulesetKey	string	Yes	The API key of the Ruleset to be used.
postcode	string	Yes	The postcode/zip used for searching. When passing: A full UK Postcode. region should be GB. A 5-digit USA Zip code. You may pass a ZIP+4, but the +4 is ignored. region should be US. A full Canadian Postcode. region should be CA.
region	string	No	Valid values are: GB (United Kingdom) US (USA) CA (Canada) Where no value is provided, the default value of GB is used.

Response

Code	Error Message	Notes
200		The request was a success. Note: It is possible to get a result from an Allocation rule with an invalid postcode, providing that part of the postcode was matched against a territory. If further results were requested and the postcode was invalid, you will get a successful response.
400	The API Key provided was either empty or null.	The API Key was empty or null. White-space is ignored.
400	No payload data was received.	The request's model object was null.
400	The Ruleset Key provided was either empty or null.	The rulesetKey value was either empty or null.
400	The Postcode provided was either empty or null.	The postcode value was either empty or null.
400	region=GB only The Postcode provided was not in the format of a full UK postcode.	The postcode value does not meet the expected format of a valid UK full Postcode. Expected formats: A0 0AA, A00 0AA, AA0 0AA, AA00 0AA, A0A 0AA, where A is a letter, and 0 is a number.
400	region=US only The ZIP code provided was not in the format of a ZIP code.	The postcode value does not meet the expected format of a valid 5-digit US ZIP code or ZIP+4. Expected formats: 00000 or 00000-0000. Note that the +4 is ignored.
400	region=CA only The Postcode provided was not in the format of a full Canadian postcode.	The postcode value does not meet the expected format of a valid full Canadian Postcode. Expected formats: A0A 0A0, where A is a letter, and 0 is a number.
400	The Ruleset provided does not have any rules attached.	A Ruleset matching the rulesetKey parameter value was found, but no rules have been set up for it.
400	This region is not yet supported. Please provide coordinates and use the alternative endpoint instead.	The region value is not supported.
404	No matching postcode could be found.	No result was found using an Allocation rule, and the supplied postcode could not be found.
404	The Ruleset could not be found using the key provided.	No Ruleset matching the rulesetKey parameter value could be found.

Example call

URL: https://api.vision-mapping.com/fyn/v1/postcode?apiKey=INSERT_YOUR_KEY_HERE

Body:

{
   rulesetKey: "abc",
   postcode: "abc",
   region: "abc"
}

Example response

[
   {
      name: "abc",
      uniqueKey: "abc",
      distanceInMiles: 123,
      dataFields: [
         {
            key: "abc",
            value: string | number | boolean | object 
         }
      ],
      matchedTags: [
         "abc",
         "abc"
      ]
   }
]

If receiving an object, the structure is as follows:

{
    lines: [""],
    city: "",
    county: "",
    postcode: "",
    country: ""  
}

Result Order

When more than one result is requested, the default order of results is by distance (nearest first, farthest last).

When tagKeys are provided, the order is changed to:

The number of tags matched
The distance

Note: This means that if three tagKeys were provided, any results matching all three would be placed first, ordered within themselves by distance, then any results matching two keys ordered by distance and so on. The first result, therefore, is not the closest, but the closest which matches the most tags.