Coordinates

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: 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.