[null,null,["最后更新时间 (UTC)：2025-08-31。"],[[["\u003cp\u003eGoogle Maps Platform static web APIs allow embedding Google Maps images on web pages without JavaScript or dynamic loading.\u003c/p\u003e\n"],["\u003cp\u003eThese APIs generate images based on URL parameters sent via HTTPS requests.\u003c/p\u003e\n"],["\u003cp\u003eAll static web API requests require authentication with credentials.\u003c/p\u003e\n"],["\u003cp\u003eURLs for the static web APIs must be properly encoded, handling special characters and spaces.\u003c/p\u003e\n"],["\u003cp\u003eThe total length of a URL for these APIs is limited to 16384 characters.\u003c/p\u003e\n"]]],[],null,["# Best Practices Using Maps Static API\n\nThe Google Maps Platform static web APIs are a collection of HTTP interfaces to Google\nservices that generate images that you can embed directly on your web page.\n\nThis guide describes some common practices useful for setting up your\n\nimage\n\n\nrequests and processing service responses. Refer to the [developer's guide](/maps/documentation/maps-static/overview)\nfor full documentation of the Maps Static API.\n\nWhat is a Static Web API?\n-------------------------\n\nThe Google Maps Platform static web APIs let you embed a Google Maps image in your web page without requiring JavaScript or any dynamic page loading. The static web APIs create an image based on URL parameters that are sent using a standard HTTPS request.\n\nA typical Maps Static API request is generally of the\nfollowing form: \n\n```json\n https://www.googleapis.com/staticmap/\u003cvar translate=\"no\"\u003ez\u003c/var\u003e/\u003cvar translate=\"no\"\u003ex\u003c/var\u003e/\u003cvar translate=\"no\"\u003ey\u003c/var\u003e?\u003cvar translate=\"no\"\u003eparameters\u003c/var\u003e\n```\n\n**Note** : All Maps Static API applications require authentication.\nGet more information on [authentication credentials](/maps/documentation/maps-static/get-api-key).\n\nSSL/TLS Access\n--------------\n\nHTTPS is required for all Google Maps Platform requests that use API keys or contain user\ndata. Requests made over HTTP that contain sensitive data may be rejected.\n\nBuilding a valid URL\n--------------------\n\nYou may think that a \"valid\" URL is self-evident, but\nthat's not quite the case. A URL entered within an address bar in a\nbrowser, for example, may contain special characters (e.g.\n`\"上海+中國\"`); the browser needs to internally translate\nthose characters into a different encoding before transmission.\nBy the same token, any code that generates or accepts UTF-8 input\nmight treat URLs with UTF-8 characters as \"valid\", but would also need\nto translate those characters before sending them out to a web server.\nThis process is called [URL-encoding](https://en.wikipedia.org/wiki/Query_string#URL_encoding) or [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding).\n| **Caution** : Browsers and/or services may automatically URL-encode a request URI before sending. On APIs that use cryptographic request signing, this can potentially invalidate the signature, if URL-encoding alters the request after signing. To avoid this issue, *always* URL-encode your query string **before** signing the request.\n\n### Special characters\n\nWe need to translate special characters because\nall URLs need to conform to the syntax specified by the\n[Uniform\nResource Identifier (URI)](http://tools.ietf.org/html/rfc3986) specification. In effect, this means that URLs\nmust contain only a special subset of ASCII characters: the familiar\nalphanumeric symbols, and some reserved characters for use as control\ncharacters within URLs. This table summarizes these characters:\nSummary of Valid URL Characters\n\n| Set | characters | URL usage |\n|--------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|\n| Alphanumeric | a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 | Text strings, scheme usage (`http`), port (`8080`), etc. |\n| Unreserved | - _ . \\~ | Text strings |\n| Reserved | ! \\* ' ( ) ; : @ \\& = + $ , / ? % # \\[ \\] | Control characters and/or Text Strings |\n\nWhen building a valid URL, you must ensure that it contains only those characters shown in the\ntable. Conforming a URL to use this set of characters generally\nleads to two issues, one of omission and one of substitution:\n\n- 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.\n- 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.\n\nAll characters to be URL-encoded are encoded\nusing a `'%'` character and a two-character hex\nvalue corresponding to their UTF-8 character. For example,\n`上海+中國` in UTF-8 would be URL-encoded as\n`%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B`. The\nstring `? and the Mysterians` would be URL-encoded as\n`%3F+and+the+Mysterians` or `%3F%20and%20the%20Mysterians`.\n\n### Common characters that need encoding\n\nSome common characters that must be encoded are:\n\n| Unsafe character | Encoded value |\n|------------------|---------------|\n| Space | `%20` |\n| \" | `%22` |\n| \\\u003c | `%3C` |\n| \\\u003e | `%3E` |\n| # | `%23` |\n| % | `%25` |\n| \\| | `%7C` |\n\nConverting a URL that you receive from user input is sometimes\ntricky. For example, a user may enter an address as \"5th\\&Main St.\"\nGenerally, you should construct your URL from its parts, treating\nany user input as literal characters.\n\nAdditionally, URLs are limited to 16384 characters for all Google Maps Platform web services\nand static web APIs. For most services, this character limit will seldom be approached. However,\nnote that certain services have several parameters that may result in long URLs."]]
