Geokodowanie to proces przekształcania adresów (np. adresu ulicy) we współrzędne geograficzne (szerokość i długość geograficzną), których możesz używać do umieszczania znaczników na mapie lub pozycjonowania mapy. Ten dokument ma na celu wyjaśnienie kwestii, które należy wziąć pod uwagę podczas geokodowania adresów. Opisuje, kiedy najlepiej używać interfejsu Geocoding API, a kiedy warto korzystać z usługi Autouzupełnianie miejsc w interfejsie Places API.
Do geokodowania pełnych adresów (np. „48 Pirrama Rd, Pyrmont, NSW, Australia”) używaj interfejsu Geocoding API. Korzystaj z usługi Autouzupełnianie miejsc w interfejsie Places API, gdy geokodujesz niejednoznaczne (niepełne) adresy lub w przypadku aplikacji wrażliwych na opóźnienia, np. podczas odpowiadania na dane wejściowe użytkownika.
Przypadki użycia i rekomendacje dotyczące interfejsów API
| Przypadki użycia i rekomendacje dotyczące interfejsów API | |
|---|---|
| odpowiadać w czasie rzeczywistym na dane wejściowe użytkownika (w tym na niejednoznaczne, niekompletne, nieprawidłowo sformatowane lub błędnie wpisane adresy); | Użyj usługi Autouzupełnianie miejsc interfejsu Places API, aby uzyskać identyfikator miejsca, a następnie interfejsu Geocoding API, aby przekształcić identyfikator miejsca w współrzędne geograficzne. |
| Automatyczne systemy przetwarzające pełne, jednoznaczne adresy pocztowe (np. „48 Pirrama Rd, Pyrmont, NSW, Australia”) | Korzystaj z usługi internetowej Geocoding API. |
| Automatyczne systemy przetwarzające niejednoznaczne zapytania (np. niepełne, nieprawidłowo sformatowane lub błędnie napisane adresy) | Zalecamy, aby systemy automatyczne korzystały z usługi internetowej Geocoding API. Jednak w przypadku systemów automatycznych, które otrzymują dużą liczbę niejednoznacznych, niekompletnych lub błędnie napisanych zapytań pochodzących od użytkowników, warto dodać interaktywny widżet autouzupełniania miejsca, aby umożliwić użytkownikom wybór wyniku i uniknąć błędnego wpisywania adresu. |
| Problemy z opóźnieniami podczas korzystania z interfejsu Directions API (starsza wersja) lub Distance Matrix API (starsza wersja), w przypadku których punkty początkowe, docelowe lub pośrednie są podane jako ciągi znaków adresu. | Zmniejsz opóźnienie geokodowania, używając usługi autouzupełniania miejsc w interfejsie Places API do uzyskiwania identyfikatorów miejsc, a następnie przekazuj te identyfikatory do interfejsu Directions API (starsza wersja) lub Distance Matrix API (starsza wersja). |
Odpowiadanie na dane wejściowe użytkownika
Aplikacje, które reagują w czasie rzeczywistym na działania użytkownika, muszą uwzględniać 2 główne kwestie, które wpływają na wybór interfejsu API:
- Dane wejściowe użytkownika zwykle obejmują wpisywanie adresu stopniowo (np. „ul. Główna 123”), więc możliwość geokodowania niekompletnych, niejednoznacznych adresów jest korzystna, ponieważ pozwala użytkownikowi szybciej uzyskać wynik.
- Aplikacje, które reagują na dane wejściowe użytkownika, są bardzo wrażliwe na opóźnienia.
Te 2 czynniki sprawiają, że usługa Autouzupełnianie miejsc w interfejsie Places API idealnie nadaje się do reagowania na dane wprowadzane przez użytkownika. Usługa autouzupełniania miejsc została zaprojektowana tak, aby zwracać wiele możliwych opcji i umożliwiać użytkownikowi wybór spośród nich. Interfejs Places API można ograniczyć tak, aby wyszukiwał tylko geokody lub adresy, z wyłączeniem firm. Dodatkowo funkcja wyszukiwania autouzupełniania może być ukierunkowana na zwracanie wyników dotyczących konkretnej lokalizacji. Interfejs Places API zwraca identyfikator miejsca, który można przekazać jako w pełni uściśloną lokalizację do usługi internetowej Geocoding API. Ta usługa zwraca następnie pełne dane adresowe i koduje adres geograficznie, podając szerokość i długość geograficzną. Identyfikatory miejsc można też przekazywać do innych interfejsów API, takich jak Directions API (starsza wersja) i Distance Matrix API (starsza wersja) (patrz Zmniejszanie opóźnienia).
Geokodowanie adresów w interfejsie Geocoding API ma znacznie większe opóźnienie, a także daje mniej dokładne wyniki w przypadku niekompletnych lub niejednoznacznych zapytań, dlatego nie jest zalecane w przypadku aplikacji, które muszą odpowiadać w czasie rzeczywistym na dane wejściowe użytkownika.
Więcej informacji o usłudze Autouzupełnianie miejsc znajdziesz w przypadku Android, iOS, JavaScript i Places API.
Systemy automatyczne
Automatyczne systemy przetwarzające pełne, jednoznaczne adresy pocztowe: jednoznaczne zapytania, takie jak pełne ciągi znaków adresu pocztowego (np. „48 Pirrama Rd, Pyrmont, NSW, Australia”), są najlepiej obsługiwane przez usługę internetową Geocoding API. Backend geokodowania adresów zapewnia większy zasięg adresów na całym świecie i jest zoptymalizowany pod kątem wysokiej jakości wyników w przypadku tego typu pełnych, jednoznacznych zapytań.
Przetwarzanie niejednoznacznych zapytań przez automatyczny system: Niejednoznaczne zapytania to te, które zawierają nieprawidłowo sformatowane adresy, niekompletne adresy lub błędy pisowni. W przypadku systemów zautomatyzowanych zalecamy korzystanie z usługi internetowej Geocoding API. Interfejs Geocoding API nie jest jednak przeznaczony do obsługi niejednoznacznych zapytań i w odpowiedzi na nie może zwracać mniej dokładne wyniki lub nie zwracać ich wcale. Jeśli Twój zautomatyzowany system przetwarza dużą liczbę niejednoznacznych zapytań pochodzących z danych wejściowych użytkownika, możesz skorzystać z dodania do aplikacji elementu interaktywnego za pomocą usługi autouzupełniania miejsc w interfejsie Places API, ponieważ została ona zaprojektowana tak, aby zwracać wiele możliwych opcji i umożliwiać użytkownikowi wybór spośród nich. Interfejs Places API zwraca identyfikator miejsca, który można przekazać jako jednoznaczną lokalizację do usługi internetowej Geocoding API. Ta usługa zwraca pełne szczegóły adresu i geokoduje adres do postaci latlng. Więcej informacji o usłudze Autouzupełnianie miejsc znajdziesz w przypadku Android, iOS, JavaScript i Places API.
Zmniejszanie czasu oczekiwania w przypadku interfejsów Directions API (starsza wersja) i Distance Matrix API (starsza wersja)
Gdy punkty początkowe, docelowe lub pośrednie są podane jako ciągi znaków adresu, Directions API (starsza wersja) i Distance Matrix API (starsza wersja) korzystają z tego samego backendu co Geocoding API, aby geokodować te adresy przed obliczeniem wskazówek dojazdu. Znacznie zwiększa to opóźnienie w porównaniu z określaniem tych samych lokalizacji jako współrzędnych geograficznych lub identyfikatorów miejsc.
Jeśli Twoja aplikacja korzysta z interfejsu Directions API (starsza wersja) lub Distance Matrix API (starsza wersja) w sytuacji, w której opóźnienie ma duże znaczenie, np. w odpowiedzi na dane wejściowe użytkownika, a punkty początkowe, docelowe lub pośrednie są początkowo określone jako ciągi znaków adresu, zalecamy zminimalizowanie opóźnienia przez użycie usługi autouzupełniania miejsc w interfejsie Places API do przekształcenia ciągów znaków adresu w identyfikatory miejsc, a następnie przekazanie identyfikatorów miejsc do interfejsu Directions API (starsza wersja) lub Distance Matrix API (starsza wersja). Dowiedz się więcej o usłudze autouzupełniania miejsc na Android, iOS, JavaScript i Places API. Zobacz też przykład autouzupełniania miejsc i wskazówek dojazdu w JavaScript.
Podsumowanie
W zależności od przypadku użycia możesz korzystać z interfejsu Geocoding API samodzielnie lub w połączeniu z usługą autouzupełniania miejsc. Umożliwia to tworzenie aplikacji, które oferują dokładne wyniki geokodowania i krótszy czas oczekiwania.
Zarządzanie błędami i ponownymi próbami
Jeśli otrzymasz odpowiedzi UNKNOWN_ERROR, są one spowodowane błędami przejściowymi i najlepiej jest spróbować ponownie po krótkiej przerwie. Zalecamy korzystanie z
bibliotek klienta usług internetowych Google Maps Platform, które obejmują logikę ponawiania i obsługują uwierzytelnianie w ramach Google Maps Platform Premium Plan.
Klient Java, klient Python, klient Go i klient Node.js do usług Google Maps to biblioteki klienta obsługiwane przez społeczność, które można pobrać i współtworzyć na GitHubie. Znajdziesz tam też instrukcje instalacji i przykładowy kod.
Jeśli w odpowiedzi otrzymasz kod stanu OVER_QUERY_LIMIT, oznacza to, że przekroczono limity wykorzystania interfejsu API. Zalecamy wypróbowanie tych
strategii optymalizacji wykorzystania.