Skip to content



All endpoints return HTTP status 401 Unauthorized

Your requests have no Authorization header at all or the header is invalid. See authentication for details.

My application stopped working after some weeks and all API calls are answered with 401 Unauthorized

Your authentication token has probably expired. A token returned by the endpoint [GET] /authenticate is valid for 30 days and must be replaced by a new token then. Use this endpoint to get a new token for your credentials.

Your application should fetch a new token either on a scheduled basis (e.g. every week) or automatically when the 401 status code occurs.

When I restrict my API key to my domain, I get a 401 Unauthorized

To check whether requests come from the configured domain, they must contain at least one of the two headers Referer or Origin. Make sure at least one of those is present in your requests and contains the configured domain.

If you use wildcards, please also note that * matches e.g. and, but not, which does not contain a subdomain.

All or some endpoints return HTTP status 403 Forbidden

Your MapTrip account lacks permissions to use the MapTrip Server API or certain features. If you get the status 403 for all endpoints, you have no permission to use the API. If only Detour, FollowMe or MapTrip Remote are affected, the corresponding permission is missing. Please contact


The status for my geocoding request is 200 Ok, but the array of addresses is empty. What does this mean?

We did not find any addresses for your input. Please check the address and country parameters. If you are sure that these are correct, please contact


How can I calculate the Estimated Time of Arrival (ETA) to a destination?

There is no endpoint for the ETA, but the ETA is a property of the summary of a route. Calculate a route to your destination and be sure to pass the correct departure time in the parameter startTime. The property summary.estimatedTimeOfArrival of the response contains an ISO 8601 string with the ETA in UTC.

How can I check if I can reach a destination with my truck?

When calculating a route, you can set the type of your vehicle to truck to calculate a truck route. In addition, you can pass attributes for your vehicle, e.g. dimensions (width, height, length), weight and whether you are transporting hazardous goods or not (see vehicle dependent route calculation for details).

Please note that a returned route does not necessarily mean that you are allowed to drive there. If problems were detected based on the road data and your vehicle profile, the hasObstacles field of the route has the value true. You will then receive in obstacles a list of all road segments on which problems were detected, including hints and the geometry of the segments (see obstacles along the route for details). Before starting the trip, please carefully ensure that you are allowed to drive there and watch out for traffic regulations.

The status for my route request is 200 Ok, but the array of routes is empty. What does this mean?

We did not find any routes for your input. Please check the request parameters, especially from, to, and waypoints. If you are sure that these are correct, please contact

I try to calculate a (reference) route with waypoints and get the status 400 Bad Request and the message that no valid route was found

This can happen especially when waypoints do not match the map data exactly. For example, the coordinates in GPS logs are often inaccurate. In this case, you should add a radius to the waypoints that is large enough to compensate for these inaccuracies. See route with waypoints.


When I try to fetch the results of an optimization, I get a 404 Not Found error

This can have two causes: Either you have already retrieved the results (the server then discards them and responds to further requests with this ID with a 404) or the ID you pass is incorrect.

Assume your response to [POST] /optimize/stops looks like this:

  "id": "9c772777-231a-4910-a29e-3404f9ea5986",
  "href": "/optimize/stops/9c772777-231a-4910-a29e-3404f9ea5986"

For this response fetch the results with curl -X GET "" -H "accept: application/json" -H "Authorization: Bearer <token>".


When I send a reference route to MapTrip, the message shows up but the route cannot be calculated

This happens when the license option Reference Route is missing for the affected device. First check the license options of the device in your MapTrip Manager account. If this does not help, please contact


How can I set a file to active or an active file to not active?

A Detour file itself has no status, so it cannot be active or inactive. The changes made in a file are taken into account in route calculation if you specify the file via the parameter detourFile:

curl -X GET "" -H "accept: application/json" -H "Authorization: Bearer <token>"

If this parameter is not specified, no changes made by Detour are taken into account for route calculation. The same applies to all other endpoints with the parameter detourFile.

Is it possible to post a complete file at once?

Starting with MapTrip Server API V2.9 there is an endpoint which allows to insert multiple segments at once. This is much faster than adding the segments in a loop and can be used to copy the contents of a file or import segments from an external data source.

See Adding multiple Segments using Batch Mode and Python demo.

When I query a segment after creating it, it has more attributes than I have passed. What are they for?

Those attributes contain information which is important for the Detour Editor. Examples are MapVersion, SegmentType, detourEditor_created, detourEditor_modified and detourEditor_modifiedBy. When editing Detour files you should keep this attributes. This is especially important if you use the endpoint [PUT] /detour/file/{fileid}/segment/{segmentid} to update a segment: First query the current attributes of the segment, then update the attributes you want to change, and call the endpoint with the result.

See Updating Detour Segments.

Is it possible to show my Detour data in a map application?

Yes, you can query the contents of a Detour file with the endpoint [GET] /detour/file/{fileid}/segment/all. The result is an array of segments, each with an array of coordinates and attributes. The coordinates are a polyline of the road segment which can be rendered in your map.

You can use the SegmentType attribute to color code the polylines and, for example, display segments of type Block in red and of type Unblock in green.