Source: https://developers.woosmap.com/products/distance-api/features/isochrone/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Distance Isochrone **Complete API Specification** : [Isochrone Endpoint Reference](/api-reference/distance-api/get-distance-isochrone-json/) ## What is the Isochrone Endpoint? The Woosmap Isochrone Endpoint is a routing service that calculates and returns a reachable area around a given location within a specified travel time or distance limit. In simple terms, it answers the question: “How far can I get from this point in 15 minutes?” ### What It Does The Isochrone Endpoint calculates and returns a geographic polygon representing the area reachable from a starting location within a defined limit of travel time (isochrone) or travel distance (isodistance). In essence, it helps you visualize the true accessibility of a point on the road network, as the calculated boundary is based on actual road travel, not straight-line distance. The output is a polygon that can be overlaid directly onto a map for immediate spatial analysis. ### Key Characteristics It provides a realistic accessibility boundary by calculating reachability based on the flow of the physical road network, a significant improvement over simple, unrealistic circular distance measurements. ## When to Use This Endpoint The Isochrone Endpoint should be used whenever you need to calculate and visualize the true geographic area reachable from a point within a specific travel time or distance, based on the actual road network and selected travel mode. ## API Endpoint ```http GET https://api.woosmap.com/distance/isochrone/json ``` ### Authentication Authenticate using either a `key` (public API key for client-side requests) or `private_key` (for server-side requests). Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code. You can also use the `X-Api-Key` header for server-side or mobile authentication. ```shell # Client-side (query parameter) ?origins=48.862,2.329&value=20&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?origins=48.862,2.329&value=20&private_key=YOUR_PRIVATE_KEY # Server-side / Mobile (header) -H "X-Api-Key: YOUR_PRIVATE_KEY" ``` For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/). ## Request Parameters Overview ### Required Parameters **`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. You can use [Localities Geocoding](/products/localities/features/geocoding) to retrieve the coordinates of an address. **`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`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above. Please refer to the [documentation](/api-reference/authentication/) to get an API Key if necessary ### Key Optional Parameters **`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). [Check Supported Languages](/products/distance-api/concepts/language-support/#language-support-in-route-api) **`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`** - More details in the [Tuning section](/products/distance-api/guides/tuning-route-results/) ## Complete Parameter Reference For all available parameters and advanced options see: - [OpenAPI Specification](/api-reference/distance-api/get-distance-isochrone-json/) - Complete technical reference ##Request Examples ### Basic Isochrone (by duration) ```shell curl "https://api.woosmap.com/distance/isochrone/json?origin=48.865,2.347&value=20&key=YOUR_KEY" ``` ### Isochrone by Distance ```shell curl "https://api.woosmap.com/distance/isochrone/json?origin=48.865,2.347&value=20&method=distance&key=YOUR_KEY" ``` ## Understanding the Response The isochrone endpoint provides a JSON response containing the following root elements: - **status** contains metadata on the request. Check the [OpenAPI Specification](/api-reference/distance-api/get-distance-isochrone-json/) for the possible values. - **isoline** contains the properties of `isoline`. #### 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](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)) ## Response Examples ```json { "status": "OK", "isoline": { "origin": { "lat": 48.709, "lng": 2.403 }, "distance": { "value": 1, "text": "1 km" }, "geometry": "s|ihHouuMZ`GdClCsA~QhCnQmBhEpCfF|HxGpBtFfEnBnHqJpH}ADaEcCaB@sBnEiEYiGmVyFaG{G[eFoCw@gAiIkDYg@_DwA@", }, } ``` ## Usage limits The following usage limits are in place for the Distance Isochrone endpoint: - Maximum of 5 queries per second (QPS) per project (so possibly the sum of client-side and server-side queries) ## Working Code Example https://demo.woosmap.com/js-samples/samples/distance-isochrone/app/dist/ [](https://demo.woosmap.com/js-samples/samples/distance-isochrone/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/distance-isochrone/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/distance-isochrone/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/distance-isochrone)