Optymalizacja wykorzystania limitu podczas geokodowania

Geokodowanie to proces przekształcania adresów („1600 Amphitheatre Parkway, Mountain View, CA”) we współrzędne geograficzne (37.423021, -122.083739), których można używać do umieszczania znaczników lub pozycjonowania mapy. Interfejsy API Google Maps Platform udostępniają 2 metody geokodowania:

  • Geokodowanie po stronie klienta, które jest wykonywane w przeglądarce, zwykle w odpowiedzi na działanie użytkownika. Interfejs Maps JavaScript API udostępnia klasy, które wysyłają żądania za Ciebie. To podejście jest opisane w dokumentacji Maps JavaScript API.
  • Geokodowanie HTTP po stronie serwera, które umożliwia serwerowi bezpośrednie wysyłanie do serwerów Google zapytań o kody geograficzne. Geocoding API to usługa internetowa, która zapewnia tę funkcję. Zazwyczaj tę usługę integruje się z innym kodem, który działa po stronie serwera. Geokodowanie po stronie serwera jest opisane w dokumentacji interfejsu Geocoding API.

Przykłady geokodowania po stronie klienta i po stronie serwera

Oto przykład geokodowania po stronie klienta, które pobiera adres, geokoduje go, przesuwa środek mapy do tej lokalizacji i dodaje tam znacznik mapy:

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
    });
  }
});

Więcej przykładów znajdziesz w dokumentacji Maps JavaScript API.

Oto przykład użycia Pythona do wysłania żądania geokodowania po stronie serwera w Geocoding API w wersji 4:

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"))

Spowoduje to utworzenie obiektu JSON o następującej zawartości:

{
  "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"
      ]
    }
  ]
}

Więcej przykładów znajdziesz w omówieniu interfejsu Geocoding API w wersji 4 i w przewodniku po geokodowaniu adresu.

Kwestie związane z limitami i kosztami

Strategie opisane w tym dokumencie są oparte na kosztach, limitach i ograniczeniach liczby żądań geokodowania.

Koszt

W przypadku żądań geokodowania nie obowiązują limity dziennego wykorzystania (QPD). Zamiast tego każde żądanie geokodowania, niezależnie od tego, czy jest wysyłane po stronie klienta przez przeglądarkę, czy po stronie serwera przez usługę internetową Geocoding API, jest rozliczane według ceny za żądanie. Aby kontrolować koszty korzystania z usługi, rozważ zarządzanie limitami wykorzystania i limitami.

Ograniczenia liczby żądań

Usługa geokodowania jest ograniczona do 3000 zapytań na minutę, co jest obliczane jako suma zapytań po stronie klienta i serwera.

Jeśli żądania geokodowania po stronie klienta są wysyłane w regularnych odstępach czasu, np. w aplikacji mobilnej, mogą zwracać błędy, gdy wszyscy użytkownicy wysyłają żądania w tym samym czasie (np. w tej samej sekundzie każdej minuty). Aby tego uniknąć, rozważ jedną z tych opcji:

  • Wprowadź losowe odstępy między żądaniami (jitter). Upewnij się, że prośby są wysyłane losowo do całej bazy użytkowników.
  • Jeśli tworzysz aplikację na Androida, użyj niedokładnego alarmu powtarzanego.
  • Jeśli tworzysz aplikację na Androida, wybierz odpowiednią strategię lokalizacji.

Buforowanie

Informacje o buforowaniu znajdziesz w  zasadach dotyczących interfejsu Geocoding API.

Architektura po stronie serwera a architektura po stronie klienta w v4

Interfejs Geocoding API w wersji 4 (w tym SearchDestinations, GeocodeAddress, GeocodeLocation i GeocodePlace) został zaprojektowany jako interfejs API typu serwer-serwer. Wywoływanie punktów końcowych w wersji 4 z serwera backendu zapewnia istotne korzyści:

  • Hiperlokalne informacje o przybyciu: metoda SearchDestinations (POST /v4/geocode/destinations) jest dostępna wyłącznie w przypadku żądań REST lub gRPC po stronie serwera i zwraca wejścia do budynków, punkty nawigacyjne, kontury budynków i pobliskie punkty orientacyjne, które nie są dostępne w geokoderach przeglądarki po stronie klienta.
  • Ulepszone zabezpieczenia interfejsu API: wywołania po stronie serwera chronią klucze interfejsu API i tokeny OAuth przed ujawnieniem w przeglądarkach klientów. Zobacz Bezpieczeństwo interfejsów API.
  • Maski pól odpowiedzi: punkty końcowe v4 po stronie serwera obsługują maski pól, co pozwala żądać tylko tych pól, których wymaga aplikacja, aby zminimalizować rozmiar ładunku i opóźnienie.

Kiedy używać wyszukiwania w przeglądarce po stronie klienta

W przypadku interaktywnych aplikacji przeglądarkowych, które reagują na naciśnięcia klawiszy, rozważ połączenie autouzupełniania miejsc po stronie klienta (aby uściślić dane wejściowe użytkownika i uzyskać identyfikator miejsca) z wywołaniem backendu do SearchDestinations lub GeocodePlace, aby bezpiecznie pobierać szczegóły lub współrzędne hiperlokalne.