Map Tiles API 웹 서비스 사용 권장사항

Google Maps Platform 웹 서비스는 지도 애플리케이션에 지리 데이터를 제공하는 Google 서비스의 HTTP 인터페이스 모음입니다.

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

웹 서비스란 무엇인가요?

Google Maps Platform 웹 서비스는 외부 서비스에서 지도 API 데이터를 요청하고 지도 애플리케이션 내에서 데이터를 사용하기 위한 인터페이스입니다. 이러한 서비스는 Google Maps Platform 서비스 약관의 라이선스 제한사항에 따라 지도와 함께 사용하도록 설계되었습니다.

지도 API 웹 서비스는 특정 URL에 대한 HTTP(S) 요청을 사용하여 URL 매개변수 또는 JSON 형식의 POST 데이터를 서비스에 인수로 전달합니다. 일반적으로 이러한 서비스는 애플리케이션에서 파싱 또는 처리하기 위해 응답 본문에 JSON으로 데이터를 반환합니다.

웹 서비스 요청의 예로는 다음과 같은 형식의 스트리트 뷰 메타데이터 요청이 있습니다.

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

참고: 모든 Map Tiles API 애플리케이션에는 인증이 필요합니다. 사용자 인증 정보에 대해 자세히 알아보세요.

SSL/TLS 액세스

HTTPS는 API 키를 사용하거나 사용자 데이터가 포함된 모든 Google Maps Platform 요청에 필요합니다. 민감한 정보가 포함된 HTTP를 통해 전송된 요청은 거부될 수 있습니다.

적절한 Google API 사용

잘못 설계된 API 클라이언트는 인터넷과 Google 서버 모두에서 필요 이상으로 많은 부하를 발생시킬 수 있습니다. 이 섹션에는 API 클라이언트의 모범 사례가 포함되어 있습니다. 다음 권장사항을 따르면 의도치 않은 API 악용으로 인해 애플리케이션이 차단되는 것을 방지할 수 있습니다.

지수 백오프

드물지만 요청을 처리하는 데 문제가 발생할 수 있습니다. 4XX 또는 5XX HTTP 응답 코드를 받거나 TCP 연결이 클라이언트와 Google 서버 사이의 어딘가에서 실패할 수 있습니다. 원래 요청이 실패했을 때 후속 요청도 성공할 수 있으므로 요청을 다시 시도하는 것이 좋습니다. 그러나 Google 서버에 요청을 반복적으로 반복적으로 반복하지 않는 것이 중요합니다. 이러한 반복 동작으로 클라이언트와 Google 간의 네트워크에 과부하가 걸리며 이로 인해 많은 문제가 발생할 수 있습니다.

따라서 시도 사이의 지연 시간을 늘려 재시도하는 것이 훨씬 좋습니다. 일반적으로 지연 시간은 각 시도의 곱셈 배수로 증가하며, 지수 백오프라고 합니다.

예를 들어 Time Zone API에 다음과 같은 요청을 하려는 애플리케이션을 가정해 보겠습니다.

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

다음 Python 예시는 지수 백오프 요청 방법을 보여줍니다.

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

또한 빠른 연속으로 반복된 요청으로 이어지는 애플리케이션 호출 체인의 높은 재시도 코드가 없도록 주의해야 합니다.

동기화된 요청

Google API에 동기화된 많은 요청은 Google 인프라에 대한 분산 서비스 거부 (DDoS) 공격으로 보일 수 있으므로 적절하게 처리됩니다. 이를 피하려면 API 요청이 클라이언트 간에 동기화되지 않도록 해야 합니다.

예를 들어, 현재 시간대의 시간을 표시하는 애플리케이션을 생각해 봅시다. 이 애플리케이션은 표시된 시간을 업데이트할 수 있도록 클라이언트 운영체제에 분 시작 시점에 절전 모드를 해제하는 알람을 설정할 수 있습니다. 애플리케이션은 알람과 관련된 처리의 일환으로 API를 호출해서는 안 됩니다.

고정된 알람에 대한 응답으로 API를 호출하는 것은 좋지 않습니다. API 호출이 시간이 지남에 따라 고르게 분산되지 않고 서로 다른 기기 간에도 분 시작 시점에 동기화되기 때문입니다. 잘못 설계된 애플리케이션은 매분 시작 시점에 정상 수준의 60배에 달하는 트래픽을 발생시킵니다.

이 문제를 해결하려면 두 번째 알람을 임의로 선택한 시간으로 설정하도록 설계하면 됩니다. 이 두 번째 알람이 발생하면 애플리케이션은 필요한 API를 호출하고 결과를 저장합니다. 애플리케이션은 분 시작 시점에 디스플레이를 업데이트하려고 할 때 API를 다시 호출하는 대신 이전에 저장된 결과를 사용합니다. 이 방법을 사용하면 API 호출이 시간이 지남에 따라 고르게 분산됩니다. 또한 API 호출은 디스플레이가 업데이트될 때 렌더링을 지연시키지 않습니다.

분 시작 시간을 제외하고, 타겟팅하지 않는 다른 일반적인 동기화 시간은 시간 시작 시점과 매일 자정에 시작하도록 주의해야 합니다.

응답 처리

이 섹션에서는 웹 서비스 응답에서 이들 값을 동적으로 추출하는 방법에 대해 설명합니다.

Google 지도 웹 서비스는 이해하기 쉬운 응답을 제공하지만, 그다지 사용자 친화적이지 않은 응답을 제공합니다. 쿼리를 수행할 때 데이터 집합을 표시하는 대신 몇 가지 특정 값을 추출하려고 할 수 있습니다. 일반적으로 웹 서비스에서 응답을 파싱하고 관심 있는 값만 추출하는 것이 좋습니다.

사용하는 파싱 스키마는 출력을 JSON으로 반환하는지 여부에 따라 다릅니다. JSON 응답은 이미 자바스크립트 객체 형태이므로 클라이언트의 자바스크립트 자체 내에서 처리될 수 있습니다.