How to Get Turn-by-Turn Navigation Instructions

API or service: Routing API
Task: Route waypoints and language → navigation steps

Examples: URL
Difficulty: Intermediate
Time: 10 min

Get turn-by-turn navigation instructions

You have route waypoints and need ordered directions that a navigation interface can present to a driver, cyclist, or pedestrian. The Routing API returns route legs containing steps, and each step can include human-readable text plus structured maneuver details.

Request format=json when your application primarily consumes route and instruction objects. Add details=instruction_details when it needs structured fields beyond the basic instruction text.

Task flow: waypoints, travel mode, and language → Routing API → legs and ordered navigation steps.

Request detailed instructions

This request calculates a driving route in Stuttgart and asks for detailed English instructions:

https://api.geoapify.com/v1/routing?waypoints=48.776438,9.150830|48.764165,9.180754&mode=drive&format=json&details=instruction_details&lang=en&apiKey=YOUR_API_KEY

The important parameters are:

Parameter	Purpose
`waypoints`	Ordered `latitude,longitude` pairs separated by `
`mode`	Applies the travel profile and access rules.
`format=json`	Returns route results organized into legs and steps.
`details=instruction_details`	Adds structured transition, street, exit, and maneuver information.
`lang=en`	Selects the language of human-readable instruction fields.

Read navigation steps

Read steps in their returned order within each leg. A route with intermediate stops normally contains multiple legs.

Reduced response:

{
  "results": [
    {
      "legs": [
        {
          "steps": [
            {
              "distance": 426,
              "time": 51.445,
              "instruction": {
                "text": "Drive east on Rosenbergstraße.",
                "type": "StartAtRight",
                "transition_instruction": "Drive east.",
                "pre_transition_instruction": "Drive east on Rosenbergstraße.",
                "post_transition_instruction": "Continue for 400 meters.",
                "streets": ["Rosenbergstraße"]
              }
            },
            {
              "distance": 904,
              "time": 94.811,
              "instruction": {
                "text": "Turn right onto Rosenbergplatz.",
                "type": "Right",
                "transition_instruction": "Turn right.",
                "post_transition_instruction": "Continue for 900 meters.",
                "streets": ["Rosenbergplatz"]
              }
            }
          ]
        }
      ]
    }
  ]
}

Use instruction.text for a ready-to-display direction. Use type and the structured fields when the interface needs maneuver icons, separate pre- and post-turn messages, street names, exit data, or preparation for the next maneuver.

Do not calculate progress from instruction count. Use step distances and the route geometry indexes associated with each step.

Localize turn-by-turn directions

Set lang when requesting the route. For German instructions, change only the language parameter:

https://api.geoapify.com/v1/routing?waypoints=48.776438,9.150830|48.764165,9.180754&mode=drive&format=json&details=instruction_details&lang=de&apiKey=YOUR_API_KEY

The route measurements remain the same, while human-readable instruction fields are localized:

{
  "english": {
    "text": "Drive east on Rosenbergstraße.",
    "transition_instruction": "Drive east.",
    "post_transition_instruction": "Continue for 400 meters."
  },
  "german": {
    "text": "Auf Rosenbergstraße Richtung Osten fahren.",
    "transition_instruction": "Richtung Osten fahren.",
    "post_transition_instruction": "400 Meter weiter der Route folgen."
  }
}

Keep the machine-readable maneuver type for application logic and use localized text for presentation. Choose a supported language deliberately and define an application fallback instead of assuming that every user locale has a matching routing language.

Learn more