Global Distance Finder

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.

Base URL

https:// api.addressy.com/LocationServices/DistanceFinder/Nearby/v1.00

JSON

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.

Request parameters

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.

 

Locations/OriginLocation fields

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.

Back to top

Response Fields

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.

 

DestinationLocations Fields

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.

Back to top

Errors

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

Back to top

Examples

The examples below show requests to the API and the corresponding responses.

Example Distance Finder request using Location List

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
}

Example Response

{
    "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,
        }
    ]
}

Back to top

Example Distance Finder request using Locations

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
}

Example Response

{
    "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,
        }
    ]
}

 

Back to top

Get started for free today

  • No credit card required
  • Cancel any time
  • 24/7 support
Get started