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:
|
|
region |
string |
No |
Valid values are:
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":"abc"}],"matchedTags":["abc","abc"]}]
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.
Comments
0 comments
Article is closed for comments.