FlowData

How do I calculate a route with Maps?

Published on 10. November 2026

The Maps routing endpoint calculates distance and travel time between two or more points. That helps with travel costs in a quote, delivery areas or planning routes for a field team. You get the distance, the duration, the course of the route and the individual turn instructions.

The request

A route is a GET to https://api.flowdata.one/v1/maps/directions. Start (origin) and destination (destination) are required, each as longitude,latitude, so longitude comes first.

curl "https://api.flowdata.one/v1/maps/directions?origin=13.4050,52.5200&destination=13.7373,51.0504&profile=driving&language=en" \
  -H "Authorization: Bearer fd_YOUR_KEY"

The example calculates a drive from Berlin to Dresden. To get coordinates for an address, use geocoding; see How do I convert an address to coordinates and back?.

All parameters

Parameter Meaning
origin Start point as longitude,latitude, required.
destination Destination as longitude,latitude, required.
waypoints Stops along the way, separated by a vertical bar |, for example 12.3731,51.3397|11.5820,50.9271. In a URL, write it as %7C.
profile Means of transport: driving-traffic (car with current traffic, default), driving (car), walking or cycling.
alternatives 1 also returns alternative routes where possible. Use 1, not true.
avoid Road types to avoid, for example motorway, toll or ferry. Separate multiple values with commas.
language Language of the directions. The default is de.

If you don't set profile, Maps calculates with driving-traffic, that is by car taking current traffic into account. Turn instructions are always included in the response; you don't need to switch them on.

The response

{
  "success": true,
  "routes": [
    {
      "distance": 193412.6,
      "duration": 7380.4,
      "geometry": {"type": "LineString", "coordinates": [[13.405, 52.52], [13.4061, 52.5183], "..."]},
      "legs": [
        {
          "distance": 193412.6,
          "duration": 7380.4,
          "summary": "A 13",
          "steps": [
            {
              "distance": 412.3,
              "duration": 61.2,
              "geometry": {"type": "LineString", "coordinates": ["..."]},
              "instruction": "Drive south on Spandauer Straße.",
              "maneuver": {"type": "depart", "modifier": null, "location": [13.405, 52.52]}
            }
          ]
        }
      ],
      "summary": "",
      "weight": 7811.9
    }
  ],
  "waypoints": [
    {"name": "Spandauer Straße", "location": [13.405, 52.52]},
    {"name": "Wilsdruffer Straße", "location": [13.7373, 51.0504]}
  ],
  "attribution": "NOTICE: © 2026 ..."
}

The values in the example are shortened and made up. How to read the fields:

  • distance: distance in meters, so 193412.6 is a little over 193 kilometers.
  • duration: travel time in seconds, so 7380.4 is about two hours and three minutes.
  • routes: the route, or several with alternatives=1. The first one is the recommended one.
  • legs: one section per part of the route. Without stops there is one section; with two stops there are three.
  • steps: the individual driving instructions, with the text in instruction and the maneuver.
  • geometry: the course of the route as a GeoJSON line (LineString) for drawing on a map. Here too, points are [longitude, latitude].
  • waypoints: start, stops and destination as Maps placed them on the road network.

When something goes wrong

  • HTTP 422 "Invalid parameters": the start or destination is missing, profile has an unknown value, or alternatives isn't 0 or 1. details names the field, for example {"profile":["..."]}. The message text itself is in German at the moment.
  • HTTP 404 "No route found for the specified coordinates": there is no route between the points, such as by car across the sea, or a point is too far from any road. An invalid value for avoid also leads to this message.
  • HTTP 500 with {"message":"Server Error"}: check the format of the coordinates. Each point needs exactly two numbers with a period as the decimal separator, separated by a comma, and valid values. Maps currently answers a wrong format with a server error instead of a clear message.
  • The route ends in a completely wrong place: longitude and latitude are usually swapped. See Maps finds nothing or the wrong place: what can I do?.

What does a route cost?

Routes are billed per 1,000 successful requests and have their own price, higher than that of search and geocoding. Responses with HTTP 404 or 422 and server errors are free. The amounts are on the pricing page, with details in Understanding FlowData prices.

Good to know

  • If you repeat a request with exactly the same points, options and language, Maps answers it from a cache. That's faster and is billed like any successful response, but with driving-traffic it also means the travel time reflects the traffic at the time of the first calculation. For quotes and planning, driving is therefore often the better choice.
  • The response includes a usage notice in the attribution field. The data must not be stored permanently.

Was this article helpful?

Back to Maps