Maps Static API 사용 시 권장사항

Google Maps Platform 정적 웹 API는 웹페이지에 직접 삽입할 수 있는 이미지를 생성하는 Google 서비스의 HTTP 인터페이스 모음입니다.

이 가이드에서는 이미지 요청을 설정하고 서비스 응답을 처리하는 데 유용한 몇 가지 일반적인 사례를 설명합니다. Maps Static API의 전체 문서는 개발자 가이드를 참고하세요.

Static Web API란 무엇인가요?

Google Maps Platform 정적 웹 API를 사용하면 JavaScript 또는 동적 페이지 로드 없이도 웹페이지에 Google 지도 이미지를 삽입할 수 있습니다. 정적 웹 API는 표준 HTTPS 요청을 사용하여 전송되는 URL 매개변수를 기반으로 이미지를 만듭니다.

일반적인 Maps Static API 요청의 형식은 일반적으로 다음과 같습니다.

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

참고: 모든 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 사용
영숫자 CANNOT TRANSLATE 텍스트 문자열, 스킴 사용(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을 길게 만드는 매개변수가 포함된 서비스도 있습니다.