Performs a Find Your Nearest search based on a coordinate.
URL: /fyn/v1/coordinates
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. |
|
tagKeys |
string array |
No |
Optional. A collection of Tag API key values to use for filtering results. This works as an "Any" rule, not an "All" rule, but note that results are prioritised based on the number of tags matched. |
|
coordinates |
object |
Yes |
See Coordinate Object Properties. The coordinates in which search from. |
Coordinate Object Properties
|
Name |
Type |
Required |
Description |
|
latitudeY |
decimal |
Yes |
The value for the Latitude. Ranges from -90.0 to +90.0. |
|
longitudeX |
decimal |
Yes |
The value for the Longitude. Ranges from -180.0 to +180.0. |
Response
|
Code |
Error Message |
Notes |
|
200 |
|
The request was successful. |
|
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 |
No coordinates were provided. |
The coordinates parameter object was not provided. |
| 400 |
Longitudes must range from -180.0 to 180.0. |
The longitudeX parameter value of the coordinate parameter object was out of range. |
| 400 |
Latitudes must range from -90.0 to 90.0. |
The latitudeY parameter value of the coordinate parameter object was out of range. |
| 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. |
| 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/coordinates?apiKey=INSERT_YOUR_KEY_HERE
Body:
{"rulesetKey":"abc","tagKeys":["abc","abc1","abc2"],"coordinates":{"longitudeX":123,"latitudeY":123}}
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.