You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Static Maps API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Static Maps API
  3. Create appropriate keys
Continue

Error Messages

The Google Static Maps API may issue an error or warning when something goes wrong.

Invalid requests

In the case of an invalid request, the Google Static Maps API returns an HTTP 4xx status code and a message describing the problem. Below are examples of such error conditions. Note: This is not a complete list of the possible errors. Please check the actual error code and message returned by the API for details of specific problems.

Example of error condition Status code
The request includes an invalid parameter, or a required parameter is missing. For example, the size parameter is not within the expected range of numeric values, or is missing from the request. 400 BAD REQUEST
The API key included in the request is invalid. 403 FORBIDDEN

Errors that prevent a map from being displayed

If the request is valid, but another error occurs that prevents the map from being displayed, the Google Static Maps API returns either text or an error image instead of the map, depending on the error. An example of such an error condition is when the application exceeds its usage limits.

Error image displayed instead of a map
Figure: An error image displayed instead of a map

Errors related to usage limits

If your use of the Static Maps API exceeds the daily usage limits, the page displays an error image instead of a map, with a link indicating the type of error. For example “g.co/staticmaperror/key”.

Usage limits errors and solutions
Usage limits error: exceeded free daily map loads limit You are using the Static Maps API without an API key, and you have exceeded the free daily map loads limit. To resolve, you must:
  1. Get an API key
  2. Enable billing
  3. Sign your URL
Usage limits error: using API without an API key

You are using the Static Maps API without an API key, and have exceeded the 50 queries-per-second limit for keyless usage.

To resolve, you must get an API key.

Usage limits error: exceeded maximum daily map loads limit You have exceeded the maximum daily map loads limit for the Static Maps API. This error can occur under one of two conditions:
  1. You have exceeded the free daily map loads limit but you have not enabled billing. To resolve, enable billing and sign your URL.

    - or-

  2. You have enabled billing, and you have exceeded the maximum billable daily map loads limit. To resolve, consider purchasing a Premium Plan.
Usage limits error: billable requests URLs are missing the digital signature You have exceeded the free daily map loads limit and are now in a billable scenario. If you have already enabled billing to increase your daily quota, you will get this error if you have not signed your URL. All billable requests must use a digital signature. To resolve,
  1. Enable billing
  2. Sign your URL

Warnings

For some error conditions, the API returns a map but some information may be missing from the map. When this happens, two conditions occur to inform you of the warning.

  • One, the map displays, but with a yellow error bar superimposed over top of the map with the text "Map error: g.co/staticmaperror".
  • Two, the API returns a warning in the form of an HTTP header named X-Staticmap-API-Warning.

For example, the following URL contains an unexpected value in the markers parameter:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

The API returns a map, but displays a yellow error bar superimposed over the image with "Map error: g.co/staticmaperror":

Map displays, but with Map error: g.co/staticmaperror

The API also returns the following HTTP header:

X-Staticmap-API-Warning:Error geocoding: marker 1

The following table describes the warnings that the API may issue as HTTP headers:

Warnings in X-Staticmap-API-Warning headers
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* An error occurred while attempting to geocode the request. There are many variants of this message, depending on the element where geocoding failed (center, marker, visible, or path) and the number of elements that failed. One example of this warning is X-Staticmap-API-Warning:Error geocoding: marker 1, as shown in the above example.
Too many geocoded markers requested (max is 15). The request specifies more than the allowed maximum number of markers with a human readable address. The maximum is 15. Note that this limit applies only to markers specified as a human-readable address that requires geocoding. It does not apply to markers specified with latitude/longitude coordinates.
Too many geocoded polyline vertices requested (max is 15). The request specifies more than the allowed maximum number of polylines with a human readable address. The maximum is 15. Note that this limit applies only to polylines with vertices specified as human-readable addresses that require geocoding. It does not apply to polylines specified with latitude/longitude coordinates.

You can see the HTTP header warnings in the Chrome DevTools Console, the Firefox Web Console, or other equivalent tools in your browser.

Send feedback about...

Google Static Maps API
Need help? Visit our support page.