How to use the Route Directions API

Geoapify Route Directions

Have you ever needed to find the best route between multiple locations? Maybe you're planning a road trip and want to find the quickest way to your destination. Or perhaps you're a delivery driver and need to plan the most efficient route to make your deliveries.

Either way, you'll need a good routing API to help you plan the best route. Geoapify's Route Directions API is a great option for finding routes between multiple locations.

The Route Directions API is a web service that calculates routes between multiple locations. You can use the API to find the shortest, quickest, or most efficient route between two or more locations. The API is easy to use and well-documented. You can find all the information you need to get started on the Geoapify website.

There are many use cases for the Route Directions API. Here are a few examples:

  • Find the quickest route between multiple locations
  • Find the shortest route between multiple locations
  • Find the most efficient route for a delivery driver
  • Find the best route for a road trip

Getting Started

To use the Route Directions API, you first need to sign up for a Geoapify account. Once you have an account, you can create a new API key.

Then, once you have an API key, you can start making requests to the API. The API uses HTTP GET requests, so you can easily make requests from your web browser or from a scripting language.

Parameters of Route Directions API

The Route Directions API has different parameters to calculate different types of routes. Below is the list of all the parameters with a brief description. The API documentation page includes detailed information about our API.

  • type: The type of route to calculate. Possible values are short, balanced, and less_maneuvers. The default value is short.
  • avoid: The types of locations to avoid. Possible values are highways, tolls, location, and ferries. The default value is none.
  • details: Whether or not to include additional information about the route, such as the total distance and estimated travel time. Possible values are instruction_details,route_details and elevation.
  • traffic: The traffic model for route calculation. Only used for motorized vehicle modes, such as drive, truck, etc.
  • units: The units to use for distance and time values. Possible values are imperial and metric. The default value is metric.
  • lang: The language to use for display values. Possible values are en (English), de (German), es (Spanish), fr (French), it (Italian), and pt (Portuguese). The default value is en.
  • waypoint: The locations to calculate the route between. The format for each waypoint is latitude, longitude.
  • mode: The mode of transportation to use.

Now let's look at each parameter in more detail.

"avoid" Parameter

avoid parameter is used to specify the types of locations to avoid while calculating the route. The possible values are highways, tolls, location, and ferries. The default value is none.

For example, if you want to avoid highways, you would set the avoid parameter to highways.

Below is the URL with the avoid parameter set to highways:

https://api.geoapify.com/v1/routing?waypoints=40.9912087,-74.0326395|40.748428399999995,-73.98565461987332&mode=drive&avoid=highways&apiKey=YOUR_API_KEY

Route without the avoid parameter set

You can also avoid certain locations by specifying the latitude and longitude of the location. The syntax for this is avoid=location:lat,long.

For example, if you want to avoid the Englewood Cliff, which has the coordinates [40.884414, -73.947588], you would set the avoid parameter to avoid=location:40.851775,-73.952789.

https://api.geoapify.com/v1/routing?waypoints=40.9912087,-74.0326395|40.748428399999995,-73.98565461987332&mode=drive&avoid=highways|location:40.884414,-73.947588&apiKey=YOUR_API_KEY

Route with the avoid parameter set

"waypoint" Parameter

This parameter is used to specify the locations to calculate the route between. The format for each waypoint is latitude,longitude.

For example, let's say you want to find the best route between Los Angeles and San Francisco. You would specify the following waypoints:

waypoints=34.0428494,-118.2476732|37.7790262,-122.419906

Below is the URL with the waypoint parameter:

https://api.geoapify.com/v1/routing?waypoints=34.0428494,-118.2476732|37.7790262,-122.419906&mode=drive&apiKey=YOUR_API_KEY

Route between Los Angeles and San Francisco (two waypoints)

You can also specify additional waypoints if you want. For example, if you want to find the best route between Los Angeles, San Francisco, and Las Vegas, you would specify the following waypoints:

waypoints=34.0428494,-118.2476732|37.7790262,-122.419906|36.190364,-115.279104

Below is the URL with the waypoint parameter:

https://api.geoapify.com/v1/routing?waypoints=34.0428494,-118.2476732|37.7790262,-122.419906|36.190364,-115.279104&mode=drive&apiKey=YOUR_API_KEY

Route between Los Angeles, San Francisco, and Las Vegas (three waypoints)

"type" Parameter

The type parameter is used to specify the type of route to calculate. The possible values are short, balanced, and less_maneuvers. The default value is balanced.

A balanced route is a compromise between three main factors: time, cost, and distance traveled. You can use the balanced parameter to find a route that is a good balance between these three factors.

The short parameter optimizes a route by distance. This is the quickest route between two or more locations. If you're planning a road trip and want to get to your destination as quickly as possible, this is the parameter for you.

The less_maneuvers parameter extends the balanced routing type but adds additional penalties for maneuvers. This is the best route if you want to avoid making any turns or other maneuvers.

For example, if we take two mountainous locations: Denver and Idaho Springs in Colorado. If we set type=balanced then the API will try to find the best balance between time, distance, and cost of the route.

https://api.geoapify.com/v1/routing?waypoints=39.7392364,-104.984862|39.7425969,-105.5136365&mode=drive&type=balanced&apiKey=YOUR_API_KEY

Route between Denver and Idaho Springs, where the type property is set to balanced

But if we set type=short then the API will try to find the shortest route between the two locations.

https://api.geoapify.com/v1/routing?waypoints=39.7392364,-104.984862|39.7425969,-105.5136365&mode=drive&type=short&apiKey=YOUR_API_KEY

Route between Denver and Idaho Springs, where the type property is set to short

"detail" Parameter

The details parameter is used to specify whether or not to include additional information about the route, such as the total distance and estimated travel time.

Possible values are instruction_details,route_details and elevation. The default value is none, which means that no additional information will be included in the response.

If you set the details parameter to instruction_details, the API will return step-by-step instructions for the route. This can be useful if you're planning a road trip and need to know where to turn and when to stop.

Below is the URL with the detail parameter set to instruction_details:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&details=instruction_details&apiKey=YOUR_API_KEY

The returned GeoJSON object will have extra instructions for every step.

Returned GeoJSON object including route instructions

If you set the details parameter to route_details, the API will return information about the route, such as the total distance and estimated travel time. This can be useful if you're trying to find the quickest or most efficient route between multiple locations.

Below is the URL with the detail parameter set to route_details:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&details=route_details&apiKey=YOUR_API_KEY

The returned GeoJSON object will have extra route instructions for every step.

Returned GeoJSON object including route information

If you set the details parameter to elevation, the API will return information about the elevation of the route. This can be useful if you're trying to avoid hills or mountains.

Below is the URL with the detail parameter set to elevation:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&details=elevation&apiKey=YOUR_API_KEY

Route including elevation information

"traffic" Parameter

This parameter is used to set the traffic model for route calculation. The default value is free_flow, meaning that the route is calculated optimistically with no traffic influence. The approximated traffic model decreases speed for potentially heavy-loaded roads. The traffic model is only used for motorized vehicle modes, such as drive, truck, etc.

For example, there are two routes from point A to point B. One route has a length of 10 km and the other has a length of 12 km. If the traffic is free_flow, the first route will be chosen because it's shorter. But if the traffic is approximated, then the route will take into account the potential for traffic congestion.

Below we are taking waypoints for San Francisco and Las Vegas. First, we are calculating routes with the free_flow parameter and then with the approximated parameter.

free_flow

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&traffic=free_flow&apiKey=YOUR_API_KEY

Route where the traffic propery is set to free_flow

approximated

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&traffic=approximated&apiKey=YOUR_API_KEY

Route where the traffic propery is set to approximated

As you can see in the above example, the route with traffic parameter takes into account the potential for traffic congestion and finds a route that is longer but is estimated to take less time.

"mode" Parameter

The mode parameter specifies the mode of transportation to use when calculating the route. The API supports a variety of transportation modes, including drive, bike, walk, and transit.

Below is the URL format for the mode parameter:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&apiKey=YOUR_API_KEY

Route where the mode parameter is set to drive

"lang" Parameter

The lang parameter is used to specify the language that you want the API to use for display values. This includes things like the name of the place, the instructions for the route, and so on.

The possible values for this parameter are en (English), de (German), es (Spanish), fr (French), it (Italian), pt (Portuguese) and many others. The default value is en.

Below is an example of how to set the lang parameter to de:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&lang=de&details=instruction_details&apiKey=YOUR_API_KEY

API output when the lang parameter is set to DE

"unit" Parameter

The unit parameter specifies the units that should be used for distance and time values. The default value is metric, which uses meters. You can also specify imperial, which uses miles.

Below is an example of how to set the unit parameter to imperial:

https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&unit=imperial&apiKey=YOUR_API_KEY

Conclusion

In this article, we've covered how to use the Geoapify Route Directions API to find the best route between multiple locations. The API is easy to use and well-documented, and it has different parameters to calculate different types of routes.

You can try the Directions API without signing up using the Directions API Playground. Instead, you can register for a free API key and start using the API in your projects.

Please feel free to contact us with any questions you might have.