November 08, 2024

Calculate Distance Isochrone

How to find all destinations that can be reached in a specific amount of time or a maximum travel distance

1. Required parameters
2. Optional parameters
3. Isochrone example
4. Isochrone endpoint Response
5. Example
6. Isochrone endpoint server side
7. Usage limits
8. Early Access

Isochrone endpoint is in Early Access stage. See more details on Early Access here.

An isochrone is a line that connects points of equal travel time around a given location. The isochrone endpoint computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of lines that you can display on a map. This endpoints also supports contours based on distance.

Requests should be built as follows:

        https://api.woosmap.com/distance/isochrone/json?parameters

    

Required parameters

Some parameters are required to initiate a Distance Isochrone API request. As it is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

        https://api.woosmap.com/distance/isochrone/json?origin=47.216485,-1.549285&value=30&key={PUBLIC_API_KEY}

    

origin

The point around which to center the isochrone. It should be supplied in the form of latitude/longitude coordinates. Latitude and longitude parts should be comma-separated. Ensure that no space exists between the latitude and longitude values.

value

The value to use for isochrone contour. You can specify time in minutes or distance in kilometers (cf. method parameter). The maximum value that can be specified is 120 (120 minutes : 2 hours or 120 km).

key

Your project’s API key. This key identifies your Woosmap Project for purposes of quota management (you should use key client side and private_key server side).

Please refer to the documentation to get an API Key if necessary

Optional parameters

        https://api.woosmap.com/distance/isochrone/json?origin=47.216485,-1.549285&value=30&mode=driving&language=fr&units=metric&method=time&key={PUBLIC_API_KEY}

    

mode

Specifies the mode of transport to use when calculating isochrone. Valid values are:

• driving (default)
• cycling
• walking

language

The language code, indicating in which language the results should be returned, if possible. If language is not supplied, the Distance API service will use the navigator language or “en” (english).

units

Specifies the unit system to use when expressing distance as text. Two different units supported:

• metric: returns distances in kilometers and meters (default)
• imperial: returns distances in miles and feet.

method

Specifies the method to compute the isoline:

• time: isochrone (default)
• distance: isodistance

avoid

Specify feature and/or zones to avoid when computing a route.

• A feature to avoid is given by its name, features currently supported are:
  • tolls: Find a route that does not pass through toll segments.
  • highways: Find a route that does not pass through highway segments.
  • ferries: Find a route that does not pass through ferry segments.
• A zone to avoid is given as a polygon, formed by a list of coordinates:
  • You need to give at least 3 coordinates for each zone
  • Each coordinate is separated by a semi-column (;)
  • A coordinate is given in the form of a couple of latitude,longitude.
• You can mix features and zones, using the pipe (|) separator
• Limitation : the total perimeter of each zone can not exceed 10km.

example : avoid=tolls|42.2345,2.4536;42.35664,2.66736;43.34534,3.25534|42.5543,2.2565;42.67764,2.5625;43.6736,3.5545

Isochrone example

The following example requests the isochrone within 1 minute from an origin, using the distance method and driving:

Isochrone call

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/distance/isochrone/json
  ?language=en
  &method=distance
  &mode=driving
  &origin=48.709%2C2.403
  &value=1
  &key=YOUR_PUBLIC_API_KEY
    

        curl -L -X GET 'https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    

        var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

    

        var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    

        import requests

url = "https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY"

payload={}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)


    

        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();

    

        require "uri"
require "net/http"

url = URI("https://api.woosmap.com/distance/isochrone/json?origin=48.709%2C2.403&value=1&mode=driving&language=en&method=distance&key=YOUR_PUBLIC_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body


    

Isochrone endpoint Response

The isochrone endpoint provides a JSON response containing the following root elements:
status contains metadata on the request. See Status Codes below.
isoline contains the properties of isoline. Example of a response for a distance-based isoline:

Distance Isochrone Response

JSON

        {
  "status": "OK",
  "isoline":
    {
      "origin": { "lat": 48.709, "lng": 2.403 },
      "distance": { "value": 1, "text": "1 km" },
      "geometry": "s|ihHouuMZ`GdClCsA~QhCnQmBhEpCfF|HxGpBtFfEnBnHqJpH}AF_EeCcB@sBnEiEYiGmVyFaG{G[eFoCw@gAiIkDYg@_DwA@",
    },
}

    

Status Codes

OK indicates that the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Distance API service (e.g. wrong API Key, wrong/no referer, …).
BACKEND_ERROR indicates a Distance API request could not be processed due to a server error. This may indicate that the origin and/or destination of this pairing could not be matched to the network. The request may or may not succeed if you try again.
MAX_ROUTE_LENGTH_EXCEEDED indicates that the origin and destination are too far away from each other.
OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) exceeds the usage limits.

Isoline

isoline contains the following fields: origin: the point around which the isochrone is centered time or distance: the time or the distance of the isochrone, with sub-fields value and text geometry: the geometry of the isochrone (encoded with the poyline algorithm)

Example

Here is a sample of a Distance Isochrone API call using Javascript and displaying the isoline result on Woosmap Map. Click on the map to change the origin and compute a new Isochrone.

• CodeSandbox
• JsFiddle
• Clone on Github

Isochrone endpoint server side

As for other Woosmap APIs, if you plan to use the isochrone endpoint of Distance API sever side you must use a private_key in your requests.

        https://api.woosmap.com/distance/isochrone/json?origin=47.216485,-1.549285&value=30&mode=driving&language=fr&units=metric&method=time&private_key={PRIVATE_API_KEY}

    

Usage limits

The following usage limits are in place for the isochrone endpoint of Distance API:

• Maximum of 5 queries per second (QPS) per project (so possibly the sum of client-side and server-side queries)

Early Access

Early Access products or features are ready for testing by customers. Publicly announced, Early Access features or products are feature-complete, covered by the Woosmap SLA and technical support, unless otherwise specified in product terms or the terms of a particular Early Access program. Early Access offerings are intended for feedbacks collection and to help Woosmap Teams finely tune product or feature based on those if necessary. The average Early Access stage lasts about six months. In some cases, accessing Early Access features or products may involve contacting our Support to get invitation or feature activation. If prices mentioned, they may be adjusted until the feature or product passes in General Availability stage.

‹ Route Route ›

Was this article helpful?

Have more questions? Submit a request