Isoline API

The Isoline API is designed to calculate the accessible areas from a specific location. In simple terms, it helps you determine the site you can travel from a place and identify new opportunities for businesses or locations.

This API provides two key features that enable you to calculate the areas that are reachable from your location:

• Isochrones - which are isolines that represent the areas that you can reach within a specific travel time.
• Isodistances - which are isolines that represent the areas that you can reach within a specific travel distance.

To make it easy for you to get started with the Isoline API, we have created an API Playground where you can create your own isochrones and isodistances.

• Authentication and API key
• API reference
• Code samples
• Pricing

Authentication and API key

To use the Isoline API, you'll need an API key. You can register and get an Isoline API Key for free without a credit card.

We offer a free plan, so there's no need to stress about cost. Start for free and upgrade to a paid plan when the needs of your project increase. For more information on our plans, visit the Pricing page.

How to get the Geoapify API key

1. Register on the Geoapify MyProjects page.
2. Create a new project.
3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
4. Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
5. Choose "Isoline API" and an API key to generate a URL and programming code.
6. Press the "Try" button to execute the API call and get the result object example.

API reference

The Isoline API is an HTTP Get request API that is used to obtain single or multi-value isolines.

Request URL

The URL for accessing the Isoline API is:

https://api.geoapify.com/v1/isoline?REQUEST_PARAMS

Request parameters

The Isoline API offers a range of parameters that can be used to customize the reachability map for your use case:

Here is a URL example:

https://api.geoapify.com/v1/isoline?lat=28.293067&lon=-81.550409&type=time&mode=drive&range=1800&apiKey=YOUR_API_KEY

The isoline ID parameter is a unique identifier assigned to each isoline generated by the Isoline API. This ID is returned as a part of the Isoline API response and can be used to retrieve previously generated isolines within a 24-hour window.

The isoline ID parameter is particularly useful when referencing previously generated isolines and avoiding recalculating them. Simply provide the corresponding isoline ID using the ID parameter to retrieve the desired isoline data:

Here is a URL example:

https://api.geoapify.com/v1/isoline?id=a235ce27b9fa8a22688f06915cfe53e3&apiKey=YOUR_API_KEY

Response Object

The Isoline API returns different types of response objects based on the HTTP status code received:

• If the calculation is successful and an HTTP status code of 200 is returned, the response object will contain a GeoJSON FeatureCollection object.
• If an HTTP status code of 202 is returned, the response will contain an object with a "properties" field that includes the "id" of the request.
• If an HTTP status code of 400 or 401 is returned, the response will contain an error object.

When the Isoline API returns a successful response with an HTTP status code of 200, it includes a FeatureCollection object that contains one or more features. Each feature represents an isoline corresponding to the requested range.

If the request includes a single range, the GeoJSON.FeatureCollection object will contain only one feature representing the isoline for that range. On the other hand, if the request consists of multiple ranges (e.g., range=300,600,900), the response will contain a GeoJSON.FeatureCollection object with multiple features, each representing an isoline for one of the requested ranges.

Each GeoJSON Feature returned by the Isoline API includes a Polygon or MultiPolygon geometry type, depending on the shape of the isoline. In addition, the features contain the following properties:

Response HTTP status codes

Calculating isolines can be time-consuming, especially for larger areas or when multiple ranges are requested. Therefore, the Isoline API may return an HTTP status code of 202 and an empty FeatureCollection object if the calculation takes too long to complete.

In this case, the response object will include a "properties" field with an "id" value that can be used to retrieve the isoline data at a later time. You can use the ID parameter to retrieve the previously requested isoline data once it becomes available.

Here are the possible status codes that you may encounter when using the Isoline API:

Code samples

Geoapify provides data in the GeoJSON format, which can be easily visualized using most map client libraries. The examples below demonstrate how to add a GeoJSON object to a map:

Visualize isoline with "Leaflet" library

If you want to display isolines on an interactive map, one of the most popular and versatile client libraries to use is Leaflet. With Leaflet, you can easily create and customize maps that display isolines generated by the Geoapify Isoline API. Here is how to use Leaflet to visualize isolines on a map:

L.geoJSON(data, {
    style: function (feature) {
        // add layer style here
        return {color: '#222222'};
    }
}).addTo(map);

This code creates a Leaflet GeoJSON layer with the provided data and adds it to the specified map. The style option is used to define the style of the isoline layer. In this example, the function provided for the style option sets the color of the isoline to a dark gray (hex color code #222222).

Visualize isoline with MapLibre GL / Mapbox GL library

If you're looking to create interactive maps with isolines, another popular option is to use MapLibre GL (a community-driven fork of Mapbox GL) library. With MapLibre GL, you can add isolines generated by the Geoapify Isoline API to a map and customize their appearance and behavior. This code sample demonstrates how to add isolines to a MapLibre GL map:

this.map.addSource('isoline-data-source', {
  type: "geojson",
  data: isolineGeoJSON,
});

this.map.addLayer({
  id: 'isoline-line',
  type: "line",
  source: 'isoline-data-source',
  paint: {
    "line-color": '#6666ff',
    "line-width": 2,
  },
});

this.map.addLayer({
  id: `isoline-fill`,
  type: "fill",
  source: 'isoline-data-source',
  paint: {
    "fill-color": '#6666ff',
    "fill-opacity": 0.3,
  },
});

First, we create a new source called 'isoline-data-source' of type "geojson". The data parameter contains the GeoJSON object returned by the Geoapify Isoline API.

Then, two new layers are added to the map. The first layer, with an ID of 'isoline-line', is a line layer that displays the isoline as a simple line on the map. The paint property is used to set the color and width of the line. The second layer, with an ID of 'isoline-fill', is a fill layer that displays the area enclosed by the isoline. The paint property is used to set the color and opacity of the fill.

Visualize isoline with "OpenLayers" library

OpenLayers is one more powerful open-source JavaScript library used for creating web-based mapping applications. Here is how to visualize isolines using the OpenLayers library.

var vectorSource = new ol.source.Vector({
    features: (new ol.format.GeoJSON({
        featureProjection: "EPSG:3857"
    })).readFeatures(data)
});

var style = new ol.style.Style({
    stroke: new ol.style.Stroke({
        color: 'rgba(0, 0, 255, 1.0)',
        width: 3
    }),
    fill: new ol.style.Fill({
        color: 'rgba(0, 0, 255, 0.1)'
    })
});

var vectorLayer = new ol.layer.Vector({
    source: vectorSource,
    style: style
});

map.addLayer(vectorLayer);

The isoline data is converted to a vector source using the GeoJSON format, which is then used to create a vector layer.

The style for the vector layer is defined using the ol.style.Style object, which lets to set the stroke and fill properties for the isoline.

Finally, the vector layer is added to the map using the addLayer method.

Pricing

We use credits to calculate the cost of each Geoapify request, which simplifies our pricing and standardizes API calls.

The following rules determine the cost of Isoline API requests:

Our free pricing plan includes 3000 credits per day. You can start with the free plan and upgrade later if needed. Additionally, we allow you to cache or store the calculated isolines on your side without restrictions.