Isochrone (Early Access)

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 endpoint Response
  4. Example
  5. Isochrone endpoint server side
  6. Usage limits
  7. 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:

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:

method

Specifies the method to compute the isoline:

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 time-based isoline:

{
  "status": "OK",
  "isoline": {
    "origin": {
      "lat": 47.216485,
      "lng": -1.549285
    },
    "time": {
      "value": 30,
      "text": "30 minutes"
    },
    "geometry": "polyline_encoding_with_polyline_algorithm"
  }
}

Example of a response for a distance-based isoline:

{
  "status": "OK",
  "isoline": {
    "origin": {
      "lat": 47.216485,
      "lng": -1.549285
    },
    "distance": {
      "value": 30,
      "text": "30 km"
    },
    "geometry": "polyline_encoding_with_polyline_algorithm"
  }
}

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.

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:

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.

Was this article helpful?
Have more questions? Submit a request