지오코딩 시 할당량 사용 최적화

지오코딩은 주소 ('1600 Amphitheatre Parkway, Mountain View, CA')를 마커나 지도를 배치하는 데 사용할 수 있는 지리 좌표(37.423021, -122.083739)로 변환하는 과정입니다. Google Maps Platform API는 지오코딩에 대한 두 가지 접근 방식을 제공합니다.

  • 클라이언트 측 지오코딩: 브라우저에서 실행되며, 일반적으로 사용자 작업에 대한 응답으로 실행됩니다. Maps JavaScript API는 요청을 실행하는 클래스를 제공합니다. 이 접근 방식은 Maps JavaScript API 문서에 설명되어 있습니다.
  • HTTP 서버 측 지오코딩: 서버에서 Google 서버에 지오코드를 직접 쿼리할 수 있습니다. Geocoding API는 이 기능을 제공하는 웹 서비스입니다. 일반적으로 이 서비스는 서버 측에서 실행되는 다른 코드와 통합됩니다. 서버 측 지오코딩은 Geocoding API 참고 리소스에 설명되어 있습니다.

클라이언트 측 지오코딩과 서버 측 지오코딩의 예시

다음은 주소를 가져와 지오코딩하고 지도의 중심을 해당 위치로 이동한 다음 지도 마커를 추가하는 클라이언트 측 지오코딩의 샘플입니다.

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

더 많은 예는 Maps JavaScript API 참고 리소스를 참고하세요.

다음은 Python을 사용하여 Geocoding API v4에서 서버 측 지오코딩 요청을 실행하는 예입니다.

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

이는 다음과 같은 콘텐츠를 포함하는 JSON 객체를 생성합니다.

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

더 많은 예시는 Geocoding API v4 개요 및 주소 지오코딩 가이드를 참고하세요.

할당량 및 비용 고려사항

이 문서에 설명된 전략은 지오코딩 비용, 할당량, 비율 제한에 따라 결정됩니다.

비용

지오코딩 요청에는 일일 할당량 (QPD) 한도가 사용되지 않습니다. 대신 브라우저를 통한 클라이언트 측 요청이든 Geocoding API 웹 서비스를 통한 서버 측 요청이든 각 지오코딩 요청은 요청당 가격으로 청구됩니다. 사용 비용을 관리하려면 사용량 한도 및 할당량 관리를 고려하세요.

비율 제한

지오코딩 서비스는 클라이언트 측 쿼리와 서버 측 쿼리의 합계로 계산되는 3,000QPM (분당 쿼리 수)으로 비율이 제한됩니다.

모바일 앱에서와 같이 주기적인 간격으로 클라이언트 측 지오코딩 요청을 실행하는 경우 모든 사용자가 동시에 요청을 하면 (예: 매분 같은 초에 모두 요청) 요청에서 오류가 반환될 수 있습니다. 이를 피하려면 다음 중 하나를 고려합니다.

  • 요청에 랜덤 간격(지터)을 적용합니다. 전체 사용자층에서 요청이 무작위로 이루어지도록 합니다.
  • Android용으로 개발하는 경우 부정확한 반복 알람을 사용합니다.
  • Android용으로 개발하는 경우 적절한 위치 전략을 선택합니다.

캐싱

캐싱에 관한 Geocoding API 정책을 참고하세요.

v4의 서버 측 아키텍처와 클라이언트 측 아키텍처 비교

Geocoding API v4(SearchDestinations, GeocodeAddress, GeocodeLocation, GeocodePlace 포함)는 서버 간 API로 설계되었습니다. 백엔드 서버에서 v4 엔드포인트를 호출하면 다음과 같은 중요한 이점이 있습니다.

  • 세부 지역 도착 인텔리전스: SearchDestinations 메서드 (POST /v4/geocode/destinations)는 서버 측 REST 또는 gRPC 요청을 통해서만 사용할 수 있으며, 클라이언트 측 브라우저 지오코더에서는 사용할 수 없는 건물 입구, 경로 지정 가능한 내비게이션 지점, 건물 윤곽선, 주변 명소를 반환합니다.
  • 향상된 API 보안: 서버 측 호출은 클라이언트 브라우저에서 API 키와 OAuth 토큰이 노출되지 않도록 보호합니다. API 보안을 참조하세요.
  • 응답 필드 마스크: 서버 측 v4 엔드포인트는 필드 마스크를 지원하므로 애플리케이션에 필요한 필드만 요청하여 페이로드 크기와 지연 시간을 최소화할 수 있습니다.

클라이언트 측 브라우저 조회를 사용해야 하는 경우

실시간 키 입력에 응답하는 대화형 브라우저 애플리케이션의 경우 클라이언트 측 Place Autocomplete (사용자 입력의 모호성을 해소하고 장소 ID를 가져오기 위함)를 SearchDestinations 또는 GeocodePlace에 대한 백엔드 호출과 결합하여 세부 지역의 세부정보 또는 좌표를 안전하게 가져오는 것이 좋습니다.