The Global Distance Finder API takes an input of an origin location and one or more destination locations, and returns road-based distance and travel times for each of them. When crossing bodies of water, ferry transport will be taken into consideration where data is available.
Please note that there are no limits to how many points you can send us, however your results returned will be limited to the nearest 100 points within a maximum of a 500km radius. In general there is a linear correlation between number of points/distance and response times. Due to this we recommend limiting to the fewest points possible for your application.
Travel times are calculated using historical traffic data.
This API supports most international locations. Distance calculation is supported between countries (e.g. France to Germany) provided that those countries are within the same region (e.g. Europe, Africa, Asia).
This method will consume credit. It is charged per request regardless of the number of destinations.
https:// api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.00
Note: we don't support API connections using HTTP - all calls should use HTTPS.
https://api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.00/json4.ws
Note: A REST endpoint with a JSON payload is the only call style supported.
Each request to the web service requires a number of parameters, all of which are listed below. All requests require a key which can be generated in your account.
Note: where potentially sensitive data is used in these parameters, remember to make the request as secure as possible (see the API Security page for more information).
* = required field
| Name | Type | Example values | Description |
|---|---|---|---|
| Key* | String | AA11-AA11-AA11-AA11 | The Loqate key used to authenticate with the service. |
| locationListID | String | b035b09f-e08f-4789-8224-0042a2dd4d36 | A GuID that identifies a list previously created using our Create List API. When this field is populated with a valid ID, the API will utilise the list for your destination locations. |
| locations | Array of Strings | "locations": [ { "id": "Test Point 1", "latitude": 51.508930, "longitude": -0.131387, "name": "test" } ] |
An array of strings that is populated with information about a location. Any points in the locations object will be used to calculate distances from your origin location. If not using a previously uploaded Location List then at least one location must be sent in the request. |
| originLocation* | Array of Strings | "originLocation": { "id": "Loqate Office", "name": "Loqate Worcester Office", "description": "Loqate's Worcester Office. ", "address": "Waterside, Basin Rd, Worcester WR5 3DA", "latitude": "52.18291", "longitude": "-2.22200" } |
An array of strings that is populated with information about your origin location. This will be the starting point for all distances calculated via the API. |
| maxDistance | Integer | 100000 | The maximum straight line distance radius of results that will be returned, starting from the original location, in metres. For example, setting a maxDistance of 100000 will only return results within a 100km radius of the origin. By default this is set to 100km with a maximum value of 500km. A smaller search radius will improve performance. |
| orderBy | String | distance/time | The order in which you want results to be returned. By default this will return locations in ascending distance order (i.e. closest location first). Time can be passed instead, to return in order of ascending travel time. |
| maxResults | Integer | 10 | The maximum number of locations you want returned. By default this is set to 10 with a maximum value of 100. Reducing the number of results returned will also improve performance. |
Further information on the fields contained within the “locations” and “originLocation” arrays.
Note: Most of these fields are not required and exist to provide contextual information about the location if results are being displayed.
| Name | Type | Example values | Description |
|---|---|---|---|
| id* | String | 12345 | Identifier for the location. This must be unique for each location provided within the request. |
| latitude* | String | 51.508930 | The WGS 84 latitude in decimal degrees format. |
| longitude* | String | -0.131387 | The WGS 84 longitude in decimal degrees format. |
| name | String | Loqate Office | Name of the location. |
| description | String | Loqate’s Worcester Office | Description of the location for display purposes. |
| address | String | Waterside, Basin Rd, Worcester WR5 3DA | Address of the location for display purposes. |
The response from the web service is a table with the specification below. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will not follow this format. Instead the response will be an error table.
| Name | Type | Example values | Description |
|---|---|---|---|
| OriginLocation | Array of Strings | "originLocation": { "id": "Loqate Office", "name": "Loqate Worcester Office", "description": "Loqate's Worcester Office. ", "address": "Waterside, Basin Rd, Worcester WR5 3DA", "latitude": "52.18291", "longitude": "-2.22200" } |
An array of strings containing the originLocation from the original request. |
| Destination Locations | Array of Objects | "DestinationLocations": [ { "DestinationLocation": { "Id": "some_id_format_1", "Name": "test", "Latitude": "51.50893", "Longitude": "-0.131387" }, "Distance": "1.32 km", "Distance": "0.82 mi", "DistanceMeters": 1323, "Time": "9 mins", "TimeSeconds": 591 }, ] |
An array of objects containing the destination locations and results for distance/time calculation. |
Further information on the fields contained within the DestinationLocations array.
| Name | Type | Example values | Description |
|---|---|---|---|
| DestinationLocation | Array of Strings | "DestinationLocation": { "Id": "Shopping Centre", "Latitude": "51.50893", "Longitude": "-0.131387" }, |
This field contains the information provided as part of the locations array in the original request. |
| Distance | String | 1.32 km | The distance by road in kilometres returned as a string. |
| DistanceMeters | Int | 1323 | The distance by road in metres returned as an integer. |
| Time | String | 9 mins | The travel time displayed as seconds, minutes or hours. |
| TimeSeconds | Int | 591 | The travel time displayed in seconds as an integer. |
Below are the errors which are specific to this web service. If an error occurs, an error table like the one below will be returned. To check for an error response, test for a 4-column table with columns "Error", "Description", "Cause" and "Resolution" containing a single row.
For a list of errors applicable to all APIs, have a look at the list of common errors.
| Number | Description | Cause | Resolution |
|---|---|---|---|
| 1001 | MissingOriginLocation | Origin location Not Supplied | Please supply Origin location |
| 1003 | MissingDestinationLocations | Destination Locations Not Supplied | Please supply one or more Destination Locations |
| 1004 | InvalidOriginLatLong | Invalid lat or long Supplied | Check input data |
| 1005 | InvalidOriginId | Invalid Id Supplied for origin | Check input data |
| 1006 | NoListFound | No list of that ID can be found associated with your account | Correct ListID and try again |
| 1007 | InvalidDestinationLatLong | Invalid lat or long Supplied | Check input data |
| 1008 | InvalidDestinationId | Invalid Id Supplied for destination | Check input data |
| 1009 | DuplicateDestinationId | Id Supplied for destination are not unique | Check input data |
| 1010 | ProviderFailure | Internal Server Error. | Please try again later |
| 1011 | InvalidSearchArea | Invalid search area provided | Check that input origin and destinations are in the same country and that the origin is near a road |
The examples below show requests to the API and the corresponding responses.
POST https:// api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.00/json4.ws
Content-Type: application/json
Note: You must generate a list using our Location Management API (see the Create List API) and have a valid ListID before using this method.
{
"key": "aa11-aa11-aa11-aa11",
"locationlistid": "b035b09f-e08f-4789-8224-0042a2dd4d36",
"originlocation": {
"id": "loqate office",
"name": "loqate worcester office",
"description": "loqate's worcester office. ",
"address": "waterside, basin rd, worcester wr5 3da",
"latitude": "52.18291",
"longitude": "-2.22200"
},
"maxdistance":500000,
"orderby": "distance",
"maxresults": 10
}{
"originlocation": {
"id": "loqate office",
"name": "loqate worcester office",
"description": "loqate's worcester office. ",
"address": "waterside, basin rd, worcester wr5 3da",
"latitude": "52.18291",
"longitude": "-2.22200"
},
"destinationlocations": [
{
"destinationlocation": {
"id": "65e7e2bc-3586-4c45-a18c-2979474c06b2",
"name": "point a",
"description": "a point",
"address": "over there",
"latitude": "51.5119437",
"longitude": "-0.1279533"
},
"distance": "219.96 km",
"distancemiles": "136.67 mi",
"distancemeters": 219964,
"time": "182 mins",
"timeseconds": 10923,
},
{
"destinationlocation": {
"id": "cc1f3a28-793d-4f72-ac20-87894e3ee3f7",
"name": "point b",
"description": "b point",
"latitude": "51.8119437",
"longitude": "0.1279533"
},
"distance": "253.53 km",
"distancemiles": "157.53 mi",
"distancemeters": 253529,
"time": "189 mins",
"timeseconds": 11363,
},
{
"destinationlocation": {
"id": "f2d71c98-e458-454a-8df7-4d0d7fa2e6b1",
"name": "point c",
"description": "c point",
"latitude": "52.5119437",
"longitude": "-0.1274533"
},
"distance": "193.25 km",
"distancemiles": "120.07 mi",
"distancemeters": 193254,
"time": "176 mins",
"timeseconds": 10616,
},
{
"destinationlocation": {
"id": "692ff52a-76f4-4c9d-8106-d16c3c466b54",
"name": "point d",
"description": "d point",
"latitude": "53.5119437",
"longitude": "-1.1279533"
},
"distance": "203.12 km",
"distancemiles": "126.21 mi",
"distancemeters": 203119,
"time": "148 mins",
"timeseconds": 8912,
},
{
"destinationlocation": {
"id": "7f0699c6-a89e-4443-bc7e-11c598dcab14",
"name": "point e",
"description": "e point",
"address": "over there",
"latitude": "51.5889437",
"longitude": "-0.9279533"
},
"distance": "166.50 km",
"distancemiles": "103.45 mi",
"distancemeters": 166499,
"time": "126 mins",
"timeseconds": 7591,
}
]
}POST https:// api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.00/json4.ws
Content-Type: application/json
{
"key": "aa11-aa11-aa11-aa11",
"locations": [
{
"id": "point a",
"latitude": 52.47952,
"longitude": -1.89618,
"name" : "example point a",
"address" : "example address 1",
"description" : "an example description"
},
{
"id": "point b",
"latitude": 52.05817,
"longitude": -2.71764,
"name" : "example point b",
"address" : "example address 2",
"description" : "an example description"
}
],
"originlocation": {
"id": "loqate office",
"name": "loqate worcester office",
"description": "loqate's worcester office. ",
"address": "waterside, basin rd, worcester wr5 3da",
"latitude": "52.18291",
"longitude": "-2.22200"
},
"maxdistance":100000,
"orderby": "distance",
"maxresults": 10
}{
"originlocation": {
"id": "loqate office",
"name": "loqate worcester office",
"description": "loqate's worcester office. ",
"address": "waterside, basin rd, worcester wr5 3da",
"latitude": "52.18291",
"longitude": "-2.22200"
},
"destinationlocations": [
{
"destinationlocation": {
"id": "point a",
"name": "example point a",
"description": "an example description",
"address": "example address 1",
"latitude": "51.50893",
"longitude": "-0.131387"
},
"distance": "219.66 km",
"distancemiles": "136.49 mi",
"distancemeters": 219657,
"time": "190 mins",
"timeseconds": 11439,
},
{
"destinationlocation": {
"id": "point b",
"name": "example point b",
"description": "an example description",
"address": "example address 2",
"latitude": "51.50893",
"longitude": "-0.131387"
},
"distance": "219.66 km",
"distancemiles": "136.49 mi",
"distancemeters": 219657,
"time": "190 mins",
"timeseconds": 11439,
}
]
}