This tutorial shows how to use the Route Directions (Routing) API in practice: how to build requests, choose route parameters, and read response details for real routing scenarios.
Start here:
- Route Directions API page: Geoapify Routing API
- Documentation: Routing API Docs
- Playground: Routing API Playground
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
On this page
Quick Start
If you want to test the API quickly, use this request:
https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&details=route_details&apiKey=YOUR_API_KEYReplace YOUR_API_KEY with your key from Get Started with Maps API. You can also test requests first in the Routing API Playground.
In the response, check these fields first:
features[0].geometryfor the route linefeatures[0].properties.distanceandfeatures[0].properties.timefor route summaryfeatures[0].properties.legsfor segment-level details
Route Directions API Parameters
Use these parameters to control how routes are calculated and what extra data is returned. For the full specification and all supported options, see the Routing API documentation.
| Parameter | What it controls | Common values | Default | Example |
|---|---|---|---|---|
waypoints | Route start/end (and optional intermediate stops). Format: lat,lon|lat,lon... | Any valid coordinate pairs | Required | waypoints=37.7790262,-122.419906|36.190364,-115.279104 |
mode | Transportation profile | drive, truck, walk, bike, transit | drive | mode=drive |
type | Route optimization strategy | balanced, short, less_maneuvers | balanced | type=balanced |
avoid | Road/area constraints | highways, tolls, ferries, location:lat,lon (can combine with |) | none | avoid=highways|tolls|location:40.884414,-73.947588 |
details | Additional response sections | instruction_details, route_details, elevation | none | details=instruction_details |
traffic | Traffic model for motorized modes | free_flow, approximated | free_flow | traffic=approximated |
units | Distance/time units in response | metric, imperial | metric | units=imperial |
lang | Localized instruction/output language | en, de, es, fr, it, pt, ... | en | lang=de |
Now let's look at each parameter in more detail.
waypoints Parameter
Use waypoints to define the route points in order.
Format: lat,lon|lat,lon|... (start -> intermediate stops -> destination).
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
Request example (two waypoints):
https://api.geoapify.com/v1/routing?waypoints=34.0428494,-118.2476732|37.7790262,-122.419906&mode=drive&apiKey=YOUR_API_KEY
You can add intermediate stops. For example, route through Los Angeles -> San Francisco -> Las Vegas:
waypoints=34.0428494,-118.2476732|37.7790262,-122.419906|36.190364,-115.279104
Request example (three waypoints):
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
mode Parameter
Use mode to choose the transportation profile, such as drive, bike, walk, or transit.
Request example (mode=drive):
https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&apiKey=YOUR_API_KEY
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.
Use type=balanced for a practical balance between travel time, distance, and maneuver complexity.
Use type=short when you want the shortest route by distance (not always the fastest by time).
Use type=less_maneuvers to reduce turns and maneuver-heavy paths.
Example with two mountainous locations (Denver -> Idaho Springs) and type=balanced:
https://api.geoapify.com/v1/routing?waypoints=39.7392364,-104.984862|39.7425969,-105.5136365&mode=drive&type=balanced&apiKey=YOUR_API_KEY
With type=short, the API prefers the shortest route by length:
https://api.geoapify.com/v1/routing?waypoints=39.7392364,-104.984862|39.7425969,-105.5136365&mode=drive&type=short&apiKey=YOUR_API_KEY
avoid Parameter
Use avoid to exclude specific road types or locations from route calculation.
Common values are highways, tolls, ferries, and location:lat,lon. Default is none.
If you want to avoid highways, set avoid=highways.
Request example (avoid=highways):
https://api.geoapify.com/v1/routing?waypoints=40.9912087,-74.0326395|40.748428399999995,-73.98565461987332&mode=drive&avoid=highways&apiKey=YOUR_API_KEY
You can also avoid a specific point by coordinates using avoid=location:lat,lon.
For example, to avoid Englewood Cliffs (40.884414,-73.947588), use avoid=location:40.884414,-73.947588.
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
details Parameter
Use details to include additional route data in the response.
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.
details=instruction_details adds turn-by-turn instructions for each step.
For more advanced guidance on combining turn-by-turn instructions with static maps to create printable driving directions, see our tutorial on printable driving directions.
Request example (details=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_KEYThe returned GeoJSON includes extra instruction data per step.
details=route_details adds route-level metadata such as travel time and distance.
Request example (details=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_KEYThe returned GeoJSON object will include route-level metadata such as distance and travel time.
details=elevation adds elevation data for the route profile.
Request example (details=elevation):
https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&details=elevation&apiKey=YOUR_API_KEY
traffic Parameter
Use traffic to control how traffic conditions influence route estimation for motorized modes (drive, truck, etc.).
free_flow (default) assumes optimistic traffic, while approximated applies congestion-aware speed reductions.
In practice, approximated may select a longer route if its estimated travel time is lower under traffic.
Below we compare routes for San Francisco -> Las Vegas with both traffic models.
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
approximated
https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&traffic=approximated&apiKey=YOUR_API_KEY
As shown above, approximated can prefer a longer route when congestion makes it faster overall.
units Parameter
The units 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.
Request example (units=imperial):
https://api.geoapify.com/v1/routing?waypoints=37.7790262,-122.419906|36.190364,-115.279104&mode=drive&units=imperial&apiKey=YOUR_API_KEYlang Parameter
Use lang to localize display values and turn-by-turn instructions in the response.
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.
Request example (lang=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
Troubleshooting
If a route result looks wrong, start with a minimal request (waypoints, mode, apiKey) and then add one parameter at a time.
| Issue | Likely cause | How to fix |
|---|---|---|
| Locations are in unconnected regions. Please check waypoint coordinate order (lat/lon). | lat/lon swapped or points placed in disconnected areas | Confirm every waypoint is lat,lon (not lon,lat) and recheck coordinates on the map |
| Unexpected route choice | avoid, traffic, or type parameters are biasing results | Remove these parameters, then re-add one by one and compare distance and time |
| Travel time seems too optimistic | Default traffic=free_flow ignores congestion | Use traffic=approximated |
| Missing instructions or summary fields | Required details option not requested | Add details=instruction_details and/or details=route_details |
| Wrong language in instructions | lang missing or instructions details not requested | Set lang (for example, de) and include details=instruction_details |
| Too many requests (HTTP 429) | Request bursts exceed rate limits | Add client-side rate limiting, queue requests, and retry with backoff |
| Auth errors (401/403) | Invalid/missing API key or insufficient access | Confirm apiKey is present, valid, and enabled for routing |
Learn More
Explore related Routing API resources to deepen implementation and integration. These guides cover route visualization, elevation profiles, printable directions, and production API usage.
How to draw routes on a Maplibre GL (Mapbox GL) map
Drawing Route Elevation Profile with Chart.js
How to Create Printable Driving Directions with Geoapify
FAQ
What is the difference between type=balanced and type=short?
balanced aims for a practical balance between travel time and route quality, while short prioritizes shortest distance. The shortest route is not always the fastest route.
How do I avoid toll roads or highways?
Use the avoid parameter. Example: avoid=highways|tolls. You can also avoid a specific point with avoid=location:lat,lon.
How do I get turn-by-turn instructions?
Set details=instruction_details. The response will include step-level instruction data you can use for navigation UI.
How do I include route summary data like time and distance?
Set details=route_details. This adds route-level metadata such as travel time and distance.
How can I test the Routing API before integration?
Use the Routing API Playground for quick tests, then integrate with your key from Get Started with Maps API.
Where can I find full Routing API documentation?
See the official Routing API Documentation for full parameter details and examples.