Troubleshooting

Errors

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status.

The response contains an object with a single error object with the following keys:

  • code: This is the same as the HTTP status of the response.
  • message: A short description of the error.
  • status: A status code indicating the nature of the error.

For example, sending an invalid placeId parameter will return the following error:

{
  "error": {
    "code": 400,
    "message": "\"placeId\" value is malformed: \"aChIJqaknMTeuEmsRUYCD5Wd9ARM\"",
    "status": "INVALID_ARGUMENT"
  }
}

Possible errors include:

Code Status Message Troubleshooting
400 INVALID_ARGUMENT The key you provided is invalid. Your API key is not valid or was not included in the request. Please ensure that you've included the entire key, and that you've enabled the API for this key.
400 INVALID_ARGUMENT "\"path\" parameter contains an invalid value: ☃" Your request contained invalid arguments. The most likely causes of this error are:
  • A problem with your path parameter.
    Please ensure you have at least 1, and fewer than 100 points. Each point should be a pair of numbers separated by a comma, such as: 48.409114,-123.369158. Points should be separated by a pipe: '|'.
  • Your request included an invalid placeId.
  • Your request included both placeIds and a path. Only one of these parameters may be specified for each request.

This error will not be returned if a placeId is passed for a road which no longer exists, or for a place which is not a road.
403 PERMISSION_DENIED Unregistered request was blocked. Please sign up using Google Developers Console. The request was denied for one or more of the following reasons:
  • The API key is missing or invalid.
  • Billing has not been enabled on your account.
  • A self-imposed usage cap has been exceeded.
  • The provided method of payment is no longer valid (for example, a credit card has expired).

In order to use Google Maps Platform products, billing must be enabled on your account, and all requests must include a valid API key. To fix this, take the following steps:
404 NOT_FOUND HTTPS is required for this service. Ensure that you are sending requests to https://roads.googleapis.com/ and not http://roads.googleapis.com/.
429 RESOURCE_EXHAUSTED The request was throttled due to project request limits being reached. You have exceeded the request limit that you configured in the Google Cloud Platform Console. This limit is typically set as requests per day, requests per 100 seconds, and requests per 100 seconds per user. This limit should be configured to prevent a single or small group of users from exhausting your daily quota, while still allowing reasonable access to all users. See Capping API Usage to configure these limits.

Exponential backoff

When requests fail, you should ensure that you retry requests with exponential backoff. For example, if a request fails once, retry after a second, if it fails again, retry after two seconds, then four seconds, and so on. This ensures that broken requests or wide scale failures do not flood Google’s servers, as many clients try to retry requests very quickly.

Troubleshooting FAQ

Implementation issues

At which frequency should I sample my vehicle location?
Every 1-10 seconds is recommended for high quality snap-to-road results.
Is there a limit on the number of points I can send per query?
Yes, a query can have at most 100 points.
What level of precision should I use to store my snapped latitude/longitude pairs?
To ensure that snapped paths follow the roads at all zoom levels, even at maximum zoom level, you should store your snapped latitude/longitude pairs at 7 decimal places of precision.
Can I use encoded polylines to display snapped paths?
Encoded polylines are only specified to a precision of 5 decimal places, which results in an error of approximately 2 meters. Encoded polylines are thus not suitable if you want your snapped paths to follow the road at high zoom levels.

Common issues

Some points aren’t being snapped, or I have gaps in snapped paths. How can I correct this?
  • If you are sampling your points at timed intervals, ensure your points are sampled at shorter intervals (every 1-10 seconds). If a longer interval is used (for example 60 seconds), the snap-to-road algorithm may not be able to determine roads traveled with sufficient accuracy.
  • If you are manually clicking on a map to create points, it's very easy to create paths with few points or sparse points that the snapping algorithm doesn't handle well. The snapping algorithm works best for points that are close together. Try the Snap to Roads demo or use the Roads inspector to test your paths.
Why are my snapped paths are jagged or slightly off from the road when I zoom in?
  • Are you truncating the precision of the snapped latitude/longitude pairs prior to displaying them? Storing snapped latitude/longitude pairs at a precision of less than 7 decimal points causes precision errors when the snapped path is displayed on the map.
  • Are you using encoded polylines? Encoded polylines truncate latitude/longitude pairs to 5 decimal places, which introduces an error of several meters, resulting in lines that are jagged or slightly off from the road at high zoom levels.

If neither of the above is the case, the map tiles may have been updated recently, causing them to become out of sync with the road index used for snapping. If only a few of your queries are affected this is likely to be the cause. Since Google Maps is updated regularly, this may happen occasionally, and can occur more often if you regularly look at old paths on a map (for example, paths that were snapped several weeks ago). For optimal visualization, you should re-snap old paths just before showing them on a map, in order to minimize the inconsistencies between the map tiles and the road index used for snapping.

What could cause the speed limit for road X to display incorrectly?
Speed limits come from several sources that vary in accuracy and coverage. If you find a pattern, for example speed limits for a particular road type or in a particular area being consistently wrong, please take the following steps to let us know:
  1. Open Google Maps on your desktop computer OR the Google Maps app for Android.
  2. Open the left side menu.
  3. Select Send feedback. Note: you may be prompted to log in.
  4. Select Edit the map.
  5. Select the road segment you want to edit.
  6. Select Next.
  7. In the "Other" field, indicate that the speed limit is wrong for that road.
  8. Select Submit.
You can also report other issues here (for example if the road has the incorrect name, is incorrectly drawn, or is closed, or private).
Why is my snapped path cutting corners instead of following the road?
To correct this issue, check the following:
  • Ensure the interpolate parameter is set to true.
  • Check that your original data points are sampled at close enough intervals (every 1-10 seconds).
Why am I getting lots of road segments returned in the snapped path for a road with no speed limit changes?
When the interpolate parameter is set to true, the snap-to-road query returns a polyline that follows the road around corners, curves, and roundabouts. If the road curves, multiple road segments are returned even if the speed limit does not change, in order to create a polyline that closely follows the road geometry.