Routing API

The Routing API works via HTTP GET requests and calculates routes between two or more waypoints. The API builds routes for automobiles, delivery trucks, cargo vans, bicycles, motor scooters, and walking or riding a bike. A returned result includes Directions and Turn-by-Turn navigation instructions.

You can now easily customize your routes using parameters to avoid specific road types and route parts, as well as locations that should be skipped. In addition, you can request detailed information like speed limits, route elevation profile, and more detailed navigation instructions.

We've created an API Playground where you can explore and examine the functionality of our API:

• Authentication and API key
• API reference: inputs
• API reference: outputs
• Code samples
• Pricing

Authentication and API key

To use the Routing API, you'll need an API key. You can register and get a Routing 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 Geoapify API key

1. Register on 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 "Routing 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: inputs

The Routing API calculates routes between provided waypoints for different modes, from buses and delivery trucks to hiking and mountain bicycles. You can choose between JSON, GeoJSON, and XML output formats to integrate the solutions quickly into your project.

Request URL

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

Here are Routing API requests examples (click on a URL to test the API):

• A driving route between 2 waypoints in GeoJSON format:
  https://api.geoapify.com/v1/routing?waypoints=50.679023,4.569876|50.66170,4.578667&mode=drive&apiKey=YOUR_API_KEY

• A light delivery truck route between 5 waypoints in JSON format:
  https://api.geoapify.com/v1/routing?waypoints=49.266798,4.0152071|49.267243,4.0166331|49.267668,4.0181211|49.267796,4.019288|49.2676078,4.02000185&mode=light_truck&format=json&apiKey=YOUR_API_KEY

• A hiking route with elevation profile in JSON format:
  https://api.geoapify.com/v1/routing?waypoints=lonlat:11.765165,46.556675|lonlat:11.793963,46.549250&mode=hike&details=elevation&format=json&apiKey=YOUR_API_KEY

• Get a road surface and road class information for a bicycle route:
  https://api.geoapify.com/v1/routing?waypoints=47.774732,9.027492|47.789538,9.0549636&mode=bicycle&details=route_details&apiKey=YOUR_API_KEY

• Get detailed Turn-by-Turn navigation or Directions instructions:
  https://api.geoapify.com/v1/routing?waypoints=48.776438,9.150830|48.535490,9.2707263&format=json&mode=drive&details=instruction_details&apiKey=YOUR_API_KEY

Request parameters

Travel modes

Here are the travel modes supported by the Routing API and their respective vehicle parameters:

	Mode	Max vehicle weight	Max vehicle height	Description
	drive	3.5t	1.6m	A passenger car
	light_truck	3.5t	3.2m	A light truck, for example, small delivery truck or camping car
	medium_truck	7.5t	4.1m	A medium-size truck
	truck	22t	4.1m	A truck
	heavy_truck	40t	4.1m	A heavy truck
	truck_dangerous_goods	22t	4.1m	A truck carrying dangerous goods
	long_truck	22t	4.1m	A long truck with a maximal length of 34m
	bus			A bus. This mode checks bus access during the route calculation.
	scooter			A motor scooter or moped.
	motorcycle			A motorcycle.
	bicycle			A city bicycle
	mountain_bike			A mountain bicycle to ride on unpaved surfaces but slower on paved terrain.
	road_bike			A road-style bicycle with narrow tires and lightweight construction.
	walk			A pedestrian mode
	hike			A hiking mode additionally to pedestrian mode uses hiking trails and higher difficulty trails
	transit			A transit or public transport mode.
	approximated_transit			A transit or public transport mode uses approximated (built on available in OSM transit routes) data for route calculation.

Route optimization type

The routing algorithm calculates the best route using specified input parameters. To help you build a route according to your requirements, we offer the following route optimization types:

Note! The less_maneuvers route optimization type is supported only in combination with the following transportation modes: drive, truck, light_truck, medium_truck, truck_dangerous_goods, heavy_truck, long_truck, bus.

Note! The short route optimization type is not supported in combination with the following transportation modes: transit, approximated_transit.

Supported languages

The lang parameter specifies the language for route directions instructions. The following languages are supported: bg, ca, cs, da, de, el, en-GB, en, es, et, fi, fr, hi, hu, it, ja, nb-NO, nl, pl, pt-BR, pt, ro, ru, sk, sl, sv, tr, uk

Route details

You can request details on the route by specifying the details parameter in the request's path:

Note! The route_details and elevation increase the API call cost. Note! The route_details and elevation information is not supported in combination with the following transportation modes: transit, approximated_transit.

Avoid parameter options

You can specify the types of roads and locations that should be avoided when generating routes:

Note! The routing algorithm will consider the avoids you've provided when it generates a route, but it won't exclude roads if there are no alternatives. Note! The avoids do increase the calculation time and add additional cost on the routing API call.

API reference: outputs

The route contains information about the route geometry and turn-by-turn navigation instructions. The resulting structure will differ depending on the requested output format.

Terminology

Before describing the Route object, let's clarify the terminology we will be using. The following picture shows a possible route schema for three waypoints. Let's use it as an example!

Here is the terminology we use for the route results:

Result object structure

Depending on the format parameter, the Routing API returns a GeoJSON.FeatureCollection object, JSON object or XML. Here are the response object structures riding on the result format:

GeoJSON.FeatureCollection object

Click to get an example of a GeoJSON response object:
https://api.geoapify.com/v1/routing?waypoints=50.679023,4.569876|50.66170,4.578667&mode=drive&apiKey=YOUR_API_KEY

JSON object or XML

JSON object (or XML object) differ a little bit from GeoJSON:

Here is an example of a JSON response object:
https://api.geoapify.com/v1/routing?waypoints=50.679023,4.569876|50.66170,4.578667&format=json&mode=drive&apiKey=YOUR_API_KEY

Route object

The route object contains information such as the calculated distance and estimated time of arrival at the destination, as well as turn-by-turn navigation instructions:

RouteLeg object

A RouteLeg object consists of information about a route between two waypoints:

LegStep object

A route step contains details about a road segment, including the general-purpose road type, lane guidance for part of the direction, and turn instructions. Some information about the road segment is added by default, but additional information is provided only when the user requests more specific details from the route within the details parameter.

StepInstruction object

An instruction object contains turn-by-turn navigation directions in human-readable and machine-readable form. The human-readable instructions can be localized with a lang input parameter.

Error response and status codes

An error may occur when an API request is malformed, or some problem arises during the generation of a route:

Code samples

The Routing API is just an HTTP request away. Requests are platform-independent and can be made from most programming languages. For our code samples, we use JavaScript. You can reimplement them in similar ways with the language of your choice.

Call Routing API

The call to the Routing API is a simple HTTP Get request. For example:

const myAPIKey = "YOUR_API_KEY";
const fromWaypoint = [38.937165,-77.045590]; // latutude, longitude
const toWaypoint = [38.881152,-76.990693]; // latitude, longitude
const url = `https://api.geoapify.com/v1/routing?waypoints=${fromWaypoint.join(',')}|${toWaypoint.join(',')}&mode=drive&details=instruction_details&apiKey=${myAPIKey}`;

fetch(url).then(res => res.json()).then(result => {
    console.log(result);
}, error => console.log(err));

Show the result route on a Leaflet map

When you want to display a route on a map, GeoJSON is the easiest format to use. That format is natively supported by most popular map libraries, including Leaflet.

It’s simple. Here’s how to insert a route into the map:

L.geoJSON(routeResult, {
  style: (feature) => {
    return {
      color: "rgba(20, 137, 255, 0.7)",
      weight: 5
    };
  }
}).bindPopup((layer) => {
  return `${layer.feature.properties.distance} ${layer.feature.properties.distance_units}, ${layer.feature.properties.time}`
}).addTo(map);

Check out the live demo on JSFiddle >>

Show turn-by-turn instructions on a Leaflet map

Each step in a route has from and to positions. You can pick up their coordinates from the route geometry by using the leg index in the legs array and from_index and to_index of the step. When creating a turn-by-turn navigator, you need to show a transition instruction at the beginning of each step.

Here is how to visualize the beginning of each step with a turn-by-turn instruction on a map:

const turnByTurns = []; // collect all transitions
routeResult.features.forEach(feature => feature.properties.legs.forEach((leg, legIndex) => leg.steps.forEach(step => {
  const pointFeature = {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": feature.geometry.coordinates[legIndex][step.from_index]
    },
    "properties": {
      "instruction": step.instruction.text
    }
  }
  turnByTurns.push(pointFeature);
})));

L.geoJSON({
  type: "FeatureCollection",
  features: turnByTurns
}, {
  pointToLayer: function(feature, latlng) {
    return L.circleMarker(latlng, turnByTurnMarkerStyle);
  }
}).bindPopup((layer) => {
  return `${layer.feature.properties.instruction}`
}).addTo(map);

Check out the live demo on JSFiddle >>

Show the result route on a MapLibre GL (Mapbox GL) map

You can use GeoJSON when you want to display a route on the map. GeoJSON is the most popular file format for representing geographical features.

map.addSource('route', {
  type: 'geojson',
  data: routeResult
});

map.addLayer({
  'id': 'route-layer',
  'type': 'line',
  'source': 'route',
  'layout': {
    'line-cap': "round",
    'line-join': "round"
  },
  'paint': {
    'line-color': "#6084eb",
    'line-width': 8
  },
  'filter': ['==', '$type', 'LineString']
});

Check out the live demo on JSFiddle >>

Get route steps geometry

You may need to display route steps, for example, to show different route segment details. You can do it in this way:

const steps = [];
routeResult.features[0].properties.legs.forEach((leg, legIndex) => {
  const legGeometry = routeData.features[0].geometry.coordinates[legIndex];
  leg.steps.forEach((step, index) => {
    if (step.from_index === step.to_index) {
      // destination point
      return;
    }

    const stepGeometry = legGeometry.slice(step.from_index, step.to_index + 1);
    steps.push({
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": stepGeometry
      },
      properties: step
    });
  });
});

Check out the live demo on JSFiddle >>

Pricing

We charge in units called "credits", for each Geoapify API call. Accumulated credits per day are called Daily usage.

Geoapify offers a variety of Pricing Plans to meet your business needs. Pricing plans start with a Free plan, including 3000 credits/day.

Here is a pricing calculation rules for the Routing API:

Pricing calculation examples

1. A route between Los Angeles, CA and Prunedale, CA, which is 498991m (< 500km), costs 1 credit.
2. A route with an elevation between Los Angeles, CA and Prunedale, CA, which is 498991m, costs 2 credit.
3. A route with an elevation and route_details between Los Angeles, CA and Prunedale, CA, which is 498991m (< 500km), costs 3 credit.
4. A route between Los Angeles, CA and Marin County, CA, which is 630340m (> 500km), costs 2 credit.
5. A route with an elevation and route_details between Los Angeles, CA and Marin County, CA, which is 630340m (> 500km), costs 6 credit.
6. A route between Los Angeles, CA and Lewisville, TX, which is 2268071m, costs 4 credit.