Page Summary

outlined_flag

• Google Maps Platform static web APIs allow embedding Google Maps images on web pages without JavaScript or dynamic loading.

• These APIs generate images based on URL parameters sent via HTTPS requests.

• All static web API requests require authentication with credentials.

• URLs for the static web APIs must be properly encoded, handling special characters and spaces.

• The total length of a URL for these APIs is limited to 16384 characters.

The Google Maps Platform static web APIs are a collection of HTTP interfaces to Googleservices that generate images that you can embed directly on your web page.

This guide describes some common practices useful for setting up yourimage requests and processing service responses. Refer to thedeveloper’s guidefor full documentation of the Maps Static API.

What is a Static Web API?

A typical Maps Static API request is generally of thefollowing form:

https://www.googleapis.com/staticmap/z/x/y?parameters

Note: All Maps Static API applications require authentication.Get more information onauthentication credentials.

SSL/TLS Access

HTTPS is required for all Google Maps Platform requests that use API keys or contain userdata. Requests made over HTTP that contain sensitive data may be rejected.

Building a valid URL

You may think that a "valid" URL is self-evident, butthat's not quite the case. A URL entered within an address bar in abrowser, for example, may contain special characters (e.g."上海+中國"); the browser needs to internally translatethose characters into a different encoding before transmission.By the same token, any code that generates or accepts UTF-8 inputmight treat URLs with UTF-8 characters as "valid", but would also needto translate those characters before sending them out to a web server.This process is calledURL-encoding orpercent-encoding.

We need to translate special characters becauseall URLs need to conform to the syntax specified by theUniformResource Identifier (URI) specification. In effect, this means that URLsmust contain only a special subset of ASCII characters: the familiaralphanumeric symbols, and some reserved characters for use as controlcharacters within URLs. This table summarizes these characters:

When building a valid URL, you must ensure that it contains only those characters shown in the table. Conforming a URL to use this set of characters generally leads to two issues, one of omission and one of substitution:

• Characters that you wish to handle exist outside of the above set. For example, characters in foreign languages such as上海+中國 need to be encoded using the above characters. By popular convention, spaces (which are not allowed within URLs) are often represented using the plus'+' character as well.
• Characters exist within the above set as reserved characters, but need to be used literally. For example,? is used within URLs to indicate the beginning of the query string; if you wish to use the string "? and the Mysterions," you'd need to encode the'?' character.

All characters to be URL-encoded are encodedusing a'%' character and a two-character hexvalue corresponding to their UTF-8 character. For example,上海+中國 in UTF-8 would be URL-encoded as%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Thestring? and the Mysterians would be URL-encoded as%3F+and+the+Mysterians or%3F%20and%20the%20Mysterians.

Common characters that need encoding

Some common characters that must be encoded are:

Converting a URL that you receive from user input is sometimestricky. For example, a user may enter an address as "5th&Main St."Generally, you should construct your URL from its parts, treatingany user input as literal characters.

Additionally, URLs are limited to 16384 characters for all Google Maps Platform web servicesand static web APIs. For most services, this character limit will seldom be approached. However,note that certain services have several parameters that may result in long URLs.