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:

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.