Google Maps Platform 정적 웹 API는 웹페이지에 직접 삽입할 수 있는 이미지를 생성하는 Google 서비스의 HTTP 인터페이스 모음입니다.
이 가이드에서는 이미지 요청을 설정하고 서비스 응답을 처리하는 데 유용한 몇 가지 일반적인 관행을 설명합니다. Maps Static API에 관한 전체 문서는 개발자 가이드를 참고하세요.
정적 웹 API란 무엇인가요?
Google Maps Platform Static Web API를 사용하면 JavaScript 또는 동적 페이지 로드 없이 웹페이지에 Google 지도 이미지를 삽입할 수 있습니다. 정적 웹 API는 표준 HTTPS 요청을 사용하여 전송되는 URL 매개변수를 기반으로 이미지를 만듭니다.
참고: 모든 Maps Static API 애플리케이션에는 인증이 필요합니다.
인증 사용자 인증 정보에 대해 자세히 알아보세요.
SSL/TLS 액세스
API 키를 사용하거나 사용자 데이터를 포함하는 모든 Google Maps Platform 요청에는 HTTPS가 필요합니다. 민감한 정보가 포함된 HTTP를 통한 요청은 거부될 수 있습니다.
올바른 URL 작성
'유효한' URL은 그 자체로 충분할 것 같지만 실제로는 그렇지 않습니다. 예를 들어 브라우저의 주소 표시줄에 입력된 URL은 특수문자(예: "上海+中國")를 포함할 수 있고, 이 경우 브라우저는 이러한 문자를 전송하기 전에 내부적으로 다른 인코딩으로 변환해야 합니다.
마찬가지로 UTF-8 입력을 생성하거나 수락하는 코드는 UTF-8 문자가 있는 URL을 '유효한' 것으로 취급할 수 있지만 그러한 문자를 웹 서버로 보내기 전에 변환해야 합니다.
이 과정을
URL 인코딩 또는 퍼센트 인코딩이라고 합니다.
특수문자
모든 URL은 URI(Uniform Resource Identifier) 사양에서 지정된 구문을 준수해야 하므로 특수문자는 변환해야 합니다. 실제로 URL에는 ASCII 문자 중 일부 특수한 문자(예: 익히 알고 있는 영숫자 기호, URL 내에서 제어 문자로 사용하기 위해 예약된 일부 문자)만 포함되어야 합니다. 다음 표에 이러한 문자가 요약되어 있습니다.
올바른 URL 문자 요약
세트
문자
URL 사용
영숫자
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
텍스트 문자열, 스킴 사용(http), 포트(8080) 등
예약되지 않음
- _ . ~
텍스트 문자열
예약됨
! * ' ( ) ; : @ & = + $ , / ? % # [ ]
제어 문자 또는 텍스트 문자열
유효한 URL을 작성할 때는 표에 표시된 문자만 사용해야 합니다. 이러한 문자 집합을 사용하여 URL을 작성하다 보면 일반적으로 다음과 같이 누락과 대체라는 두 가지 문제가 발생합니다.
처리하려는 문자가 위의 집합에 없는 경우. 예를 들어 上海+中國 등의 외국어 문자는 위의 문자를 사용하여 인코딩해야 합니다. 관례적으로 URL 내에서 허용되지 않는 공백은 더하기 문자('+')를 사용해서 표현하기도 합니다.
예약된 문자로 위 집합에 포함된 문자를 문자 그대로 사용해야 하는 경우.
예를 들어 ?는 URL 내에서 쿼리 문자열의 시작을 나타내는 데 사용되는데, '? and the Mysterions'라는 문자열을 사용하려면 '?' 문자를 인코딩해야 합니다.
URL 인코딩이 필요한 모든 문자는 '%' 문자 및 UTF-8 문자에 해당하는 2자리 16진수 값을 사용하여 인코딩됩니다. 예를 들어 UTF-8 형식의 上海+中國은 %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B로 URL 인코딩됩니다. ? and the Mysterians 문자열은 %3F+and+the+Mysterians 또는 %3F%20and%20the%20Mysterians로 URL 인코딩됩니다.
인코딩이 필요한 일반 문자
일부 일반 문자는 다음과 같이 인코딩되어야 합니다.
안전하지 않은 문자
인코딩된 값
공백
%20
"
%22
<
%3C
>
%3E
#
%23
%
%25
|
%7C
때로는 사용자가 입력한 URL을 수신하여 변환하는 과정이 까다로울 수 있습니다. 예를 들어 사용자가 주소를 '5th&Main St.'로 입력할 수 있습니다.
일반적으로 URL은 해당 부분을 사용하여 구성해야 하므로 모든 사용자 입력은 리터럴 문자로 취급해야 합니다.
또한 URL은 모든 Google Maps Platform 웹 서비스 및 정적 웹 API에서 16, 384자(영문 기준)로 제한됩니다. 대부분의 서비스에서는 이러한 글자 수 제한에 도달하는 일이 거의 없습니다. 그러나 URL을 길게 만드는 매개변수가 포함된 서비스도 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\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."]]
