Dear Google Maps Platform Developers,

TL;DR: We are changing the way error codes are reported in our monitoring. If you do not consume Google Cloud Monitoring metrics for Google Maps Platform services, you can ignore this public issue.

What is happening?

To give you more insights into DATA_NOT_AVAILABLE, NOT_FOUND and ZERO_RESULTS responses across the Google Maps Platform service, we are unifying how these types of responses are surfaced through the Google Cloud maps or serviceruntime monitoring metrics across all our APIs.

We are therefore happy to announce a change to the above-mentioned metrics for the following APIs: Directions API, Geocoding API, Maps Elevation API, Maps Static API, Places API, Street View Static API and Time Zone API.

Over the coming weeks, you will start seeing any DATA_NOT_AVAILABLE, NOT_FOUND or ZERO_RESULTS responses you receive on these APIs be reported in the Google Cloud monitoring metrics as grpc_status_code: 5 (NOT_FOUND), response_code: 404, response_code_class: 4xx instead of the unactionable old codes 0 (OK), 200, 2xx. For a full list of status code mappings across our different APIs, please see section Response status and Response code labels mapping in our Google Maps Platform Monitoring article.

Note: For historical reasons, the HTTP status code returned by some Google Maps Platform API queries may differ from the values surfaced through the monitoring metrics.

This change will introduce some new discrepancies between the API protocol and the reported monitoring metrics, but in a way that improves the internal consistency between metrics from different APIs.

The HTTP status code returned by the APIs will not change to make sure that you won’t need to make any changes in your applications.

The table listed in Response status and Response code labels mapping contains both the codes returned by the API and the corresponding codes used in monitoring.

Current rollout status:

Elevation API: complete
Maps Static API: complete
Street View Static API: complete
Time Zone API: complete
Geocoding API: complete
Directions API: complete
Places API: complete

You can further track the progress of the rollout by starring this public issue.

What do I need to do?

You don't need to do anything, but you can set up monitoring and alerting based on these codes.

Note: It is completely normal to have a certain baseline of grpc_status_code: 5 (NOT_FOUND), response_code: 404 results in your monitoring metrics.

For example, querying for non-existent addresses, expired Place IDs, Street View Panorama IDs, or attempting to route between different continents, are all expected to result in a 404 response.

You can go to the Metrics Explorer and Alerting sections under Monitoring, in the Google Cloud Console to experiment with the metrics. A simple example can be found here.

Tips

First monitor your metrics so you know what is the typical baseline-ratio of 5 (NOT_FOUND), 404 results for your application.
You may also experiment with rate-of-change alerts, setting thresholds for how fast the ratio of 5 (NOT_FOUND), 404 responses changes over time.

Examples

To get you started, here are a couple sample MQL queries to set up your monitoring graphs and alerts.

Example MQL graph for displaying breaking down your Google Map Platform request count by HTTP response code:

fetch maps.googleapis.com/Api
| metric 'maps.googleapis.com/service/request_count'
| align rate(1m)
| every 1m
| group_by [metric.response_code, metric.response_code_class, resource.service],
   [value_request_count_aggregate: aggregate(value.request_count)]

Relevant documentation:
https://cloud.google.com/monitoring/mql/examples#qlx-groupby-aggr

Example MQL graph for calculating the `404` ratio:

fetch maps.googleapis.com/Api
| metric 'maps.googleapis.com/service/request_count'
| filter_ratio_by [resource.service, resource.method, resource.location], metric.response_code == '404'

Relevant documentation:
https://cloud.google.com/monitoring/mql/examples#qlx-filter-ratio

Example MQL alert triggered when the ratio of 404 errors is over the baseline of 60% over a 30-minute sliding window:

fetch maps.googleapis.com/Api
| metric 'maps.googleapis.com/service/request_count'
| group_by [resource.service, resource.method, resource.location, metric.response_code], sliding(30m), sum(val())
| every 1m
| filter_ratio_by [resource.service, resource.method, resource.location], metric.response_code == '404'
| condition val() >= 0.6 '1'

Relevant documentation:
https://cloud.google.com/monitoring/mql/reference#condition-tabop

Example MQL alert triggered when the ratio of 404s computed over a 30-minute sliding window increases by 20% compared to one hour earlier

fetch maps.googleapis.com/Api
| metric 'maps.googleapis.com/service/request_count'
| group_by [resource.service, resource.method, resource.location], sliding(30m), sum(if(metric.response_code == '404', val(), 0)) / sum(val())
| every 1m
| { ident ; time_shift 1h }
| join | sub
| condition val() >= 0.2 '1'

Relevant documentation:
https://cloud.google.com/monitoring/mql/examples#qlx-ratios-over-time
https://cloud.google.com/monitoring/mql/examples#qlx-group-ratio

Further resources

For more information about how to use Google Cloud Monitoring with your Maps Platform usage, we recommend reading the following pages from our public documentation:
https://developers.google.com/maps/reporting-and-monitoring/overview
https://developers.google.com/maps/reporting-and-monitoring/monitoring
https://cloud.google.com/monitoring/api/metrics_gcp#gcp-maps
https://cloud.google.com/monitoring/mql
https://cloud.google.com/monitoring/mql/examples
https://cloud.google.com/monitoring/mql/reference

We’re here to help

If you have any questions please contact Google Maps Platform Support.

Note: A small fraction of our customers on Geocoding API, Directions API and Places API may start to see a significant percentage of their requests being reported as 404s. This is not an automatic signal of any Google Maps Platform issue, (see the notes above about determining the baseline-ratio for 404 responses in your application).

Especially if your 404 ratio remains exceedingly high and fairly stable over an extended period of time, it is likely a symptom of some kind of systemic issue in your application logic or the data you pass to the Google Maps Platform APIs. Therefore, before reaching out to support, we kindly ask you to do the following

Determine what your historical 404 baseline-ratio is.

Collect samples of requests that result in ZERO_RESULTS, NOT_FOUND and DATA_NOT_AVAILABLE responses, and validate that the queries look semantically correct for the API in question: e.g., addresses are correctly formatted for your country, location coordinates are on land, or Directions API requests have origins and destinations that are physically reachable by the supported travel modes.

If the queries look correct, and the ratio or 404s has increased drastically, don't hesitate to reach out to support with the examples you collected.

Thanks for choosing Google Maps Platform!

– The Google Maps Platform Team