Omówienie
Funkcje w bibliotece Places API oraz Maps JavaScript API umożliwiają aplikacji wyszukiwanie miejsc (zdefiniowanych w tym interfejsie jako miejsc, lokalizacji geograficznych lub znanych miejsc) zawartych w określonym obszarze, np. granicach mapy lub wokół stałego punktu.
W interfejsie Places API jest dostępna funkcja autouzupełniania, dzięki której aplikacje mogą z wyprzedzeniem wyszukiwać w polu wyszukiwania Map Google. Gdy użytkownik zacznie wpisywać adres, autouzupełnianie wypełni resztę. Więcej informacji znajdziesz w dokumentacji autouzupełniania.
Pierwsze kroki
Jeśli nie znasz jeszcze interfejsu API JavaScript Map Google lub go nie zalecamy, zanim zaczniesz, zapoznaj się z kodem JavaScript i pobierz klucz interfejsu API.
Włącz interfejsy API
Zanim użyjesz biblioteki Miejsc w interfejsie Maps JavaScript API, sprawdź, czy interfejs Places API jest włączony w Google Cloud Console w tym samym projekcie, który został skonfigurowany dla Maps JavaScript API.
Aby wyświetlić listę włączonych interfejsów API:
- Otwórz Google Cloud Console.
- Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu API JavaScript Map Google, a następnie kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Places API.
- Jeśli na liście widzisz interfejs Places API, jest on już włączony. Jeśli interfejsu API nie ma na liście, włącz go:
- U góry strony wybierz WŁĄCZ INTERFEJSY API I USŁUGI, aby wyświetlić kartę Biblioteka. Możesz też wybrać w menu po lewej stronie Bibliotekę.
- Wyszukaj Places API, a następnie wybierz go z listy wyników.
- Wybierz WŁĄCZ. Gdy proces dobiegnie końca, interfejs API Miejsc Google pojawi się na liście interfejsów API w panelu.
Wczytuję bibliotekę
Usługa Miejsca to samodzielna biblioteka niezależna od głównego kodu interfejsu API JavaScript Map Google. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać go za pomocą parametru libraries
w adresie URL rozruchowego interfejsu API Map Google:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>
Więcej informacji znajdziesz w artykule Omówienie bibliotek.
Dodaj Miejsca interfejsu API do listy ograniczeń interfejsu API klucza interfejsu API
Stosowanie ograniczeń interfejsu API do kluczy ogranicza używanie interfejsu API do co najmniej jednego interfejsu API lub pakietów SDK. Żądania do interfejsu API lub pakietu SDK powiązane z kluczem interfejsu API będą przetwarzane. Żądania do interfejsu API lub pakietu SDK niepowiązane z kluczem interfejsu API zakończą się niepowodzeniem. Aby ograniczyć użycie klucza interfejsu API do korzystania z biblioteki miejsc, Maps JavaScript API:- Otwórz Google Cloud Console.
- Kliknij menu projektu i wybierz projekt zawierający klucz interfejsu API, który chcesz zabezpieczyć.
- Kliknij przycisk menu
i wybierz Google Maps Platform > Dane logowania.
- Na stronie Dane logowania kliknij nazwę klucza interfejsu API, który chcesz zabezpieczyć.
- Na stronie Ogranicz klucz interfejsu API i zmień jego nazwę ustaw ograniczenia:
- Ograniczenia interfejsów API
- Wybierz Ogranicz klucz.
- Kliknij Wybierz interfejsy API, a następnie interfejs Maps JavaScript API i Places API.
Jeśli jednego z tych interfejsów API nie ma na liście, musisz go włączyć.
- Kliknij ZAPISZ.
Limity i zasady użytkowania
Limity
Interfejs Library API, w tym interfejs API JavaScript, zawiera limit wykorzystania dla interfejsu Places API zgodnie z opisem w dokumentacji limitów korzystania z interfejsu Places API.
Zasady
Korzystanie z biblioteki Miejsc oraz interfejsu API JavaScript Map musi być zgodne z zasadami opisanymi w interfejsie Places API.
Wyszukiwanie miejsc
W usłudze Miejsca można wykonywać następujące rodzaje wyszukiwań:
- Funkcja Znajdź miejsce z zapytania zwraca miejsce na podstawie zapytania tekstowego (np. nazwy lub adresu miejsca).
- Znajdź miejsce z numeru telefonu zwraca miejsce na podstawie numeru telefonu.
- Wyszukiwanie w pobliżu zwraca listę miejsc w pobliżu na podstawie lokalizacji użytkownika.
- Wyszukiwanie tekstowe zwraca listę miejsc w pobliżu na podstawie wyszukiwanego hasła, np. „Pizza”.
- Prośby o szczegóły miejsca zwracają bardziej szczegółowe informacje o konkretnym miejscu, w tym opinie użytkowników.
Zwracane informacje mogą obejmować instytucje, takie jak restauracje, sklepy i biura, a także wyniki dotyczące „kodu geograficznego” wskazujące adresy, obszary polityczne, takie jak miasta czy miasta, oraz inne ciekawe miejsca.
Znajdowanie próśb o udostępnienie miejsca
Żądanie Znajdź miejsce umożliwia wyszukiwanie miejsca za pomocą zapytania tekstowego lub numeru telefonu. Istnieją 2 typy żądania Znajdź miejsce:
Znajdź miejsce na podstawie zapytania
Funkcja Znajdź miejsce na podstawie zapytania pobiera dane tekstowe i zwraca je. Dane wejściowe mogą być dowolnymi danymi miejsca, takimi jak nazwa lub adres firmy. Aby utworzyć żądanie Znajdź z zapytania, wywołaj metodę PlacesService
findPlaceFromQuery()
, która przyjmuje te parametry:
query
(wymagane) Ciąg tekstowy, na którym należy wyszukać hasło, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria instytucji. Inne typy danych wejściowych mogą generować błędy i nie gwarantują, że wyniki będą poprawne. Interfejs Places API zwraca wyniki pasujące do tego ciągu i porządkuje wyniki na podstawie ich trafności.fields
(wymagane) Jeden lub więcej pól określających typy danych Miejsc, które mają zostać zwrócone.locationBias
(opcjonalnie) współrzędne obszaru, który ma zostać wyszukany. Oto możliwe przyczyny:- Zbiór współrzędnych szerokości i długości geograficznej określonych jako LatLngLiteral lub obiekt LatLng
- Granice prostokątów (2 pary szerokości i długości lub obiekty LatLngBound).
- Promień (w metrach) wokół niego
Musisz też przekazać metodę wywołania zwrotnego do findPlaceFromQuery()
, aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus
.
Przykład poniżej pokazuje wywołanie w wynikach wyszukiwania findPlaceFromQuery()
w wynikach wyszukiwania „Muzeum Sztuki Współczesnej w Australii” oraz pól name
i geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }Zobacz przykład
Znajdź miejsce na podstawie numeru telefonu
Funkcja Znajdź miejsce z numeru telefonu pobiera numer telefonu i zwraca miejsce. Aby utworzyć żądanie Znajdź z numeru telefonu, wywołaj metodę PlacesService
findPlaceFromPhoneNumber()
, która przyjmuje te parametry:
phoneNumber
(wymagany) numer telefonu w formacie E.164.fields
(wymagane) Jeden lub więcej pól określających typy danych Miejsc, które mają zostać zwrócone.locationBias
(opcjonalnie) współrzędne określające obszar, który chcesz wyszukać. Oto możliwe przyczyny:- Zbiór współrzędnych szerokości i długości geograficznej określonych jako LatLngLiteral lub obiekt LatLng
- Granice prostokątne (4 punkty szerokości i długości geograficznej lub obiekt LatLngBound)
- Promień (w metrach) wokół niego
Musisz też przekazać metodę wywołania zwrotnego do findPlaceFromPhoneNumber()
, aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus
.
Pola (znajdź metody miejsc)
Użyj parametru fields
, aby określić tablicę typów danych miejsc do zwrócenia.
na przykład: fields: ['formatted_address', 'opening_hours', 'geometry']
.
Przy określaniu wartości złożonych używaj kropki. na przykład: opening_hours.weekday_text
.
Pola odpowiadają wynikom wyszukiwania miejsc i są podzielone na 3 kategorie płatności: Podstawowe, Kontakty i atmosfera. Pola podstawowe są rozliczane według stawki podstawowej i nie powodują naliczenia dodatkowych opłat. Pola kontaktów i atmosfery są rozliczane według wyższej stawki. Więcej informacji znajdziesz w arkuszu opłat. Atrybucja (html_attributions
) jest zawsze zwracana przy każdym wywołaniu, niezależnie od tego, czy pole zostało zażądane.
Podstawowe
Kategoria podstawowa obejmuje te pola:
business_status
, formatted_address
, geometry
,
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(wycofane),
photos
, place_id
, plus_code
, types
Kontakt
Kategoria Kontakt obejmuje następujące pole:opening_hours
(wycofane w bibliotece miejsc, interfejsie Maps JavaScript API. Aby uzyskać wyniki
opening_hours
, użyj żądania szczegółów miejsca.
Atmosfera
Kategoria Atmosfera zawiera te pola:price_level
, rating
, user_ratings_total
Metody findPlaceFromQuery()
i findPlaceFromPhoneNumber()
zawierają ten sam zestaw pól i mogą zwracać te same pola w odpowiednich odpowiedziach.
Ustawianie odchylenia lokalizacji (znajdowanie metod miejsc)
Parametr locationBias
pozwala uzyskać wynik „Find Place” w określonym miejscu. locationBias
możesz ustawić w ten sposób:
Wyniki w konkretnym obszarze:
locationBias: {lat: 37.402105, lng: -122.081974}
Zdefiniuj prostokątny obszar do wyszukania:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Możesz też użyć funkcji LatLngBounds.
Zdefiniuj promień do wyszukiwania (w metrach), wyśrodkowany na określonym obszarze:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
Zapytania dotyczące wyszukiwania w pobliżu
Wyszukiwanie w pobliżu pozwala szukać miejsc na określonym obszarze według słowa kluczowego lub typu. Wyszukiwanie w pobliżu musi zawsze zawierać lokalizację, którą można określić na jeden z dwóch sposobów:
LatLngBounds
.- obszar kolisty określony jako połączenie właściwości
location
(określające środek okręgu jako obiektLatLng
) i promień wyrażony w metrach.
Wyszukiwanie w pobliżu jest wykonywane w wyniku wywołania metody nearbySearch()
obiektu
PlacesService
, która zwraca tablicę obiektów
PlaceResult
. Pamiętaj, że metoda nearbySearch()
zastępuje metodę search()
od wersji 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
Ta metoda pobiera żądanie z tymi polami:
- Wykonaj jedną z tych czynności:
bounds
, który musi być obiektemgoogle.maps.LatLngBounds
definiującym prostokątny obszar wyszukiwania;location
iradius
. Pierwszy z nich przyjmuje obiektgoogle.maps.LatLng
, a drugi to prosta liczba całkowita reprezentująca promień koła w metrach. Maksymalny dozwolony zasięg to 50 000 metrów. Pamiętaj, że gdyrankBy
ma wartość Odległość, musisz określićlocation
, ale nie możesz określićradius
anibounds
.
keyword
(opcjonalnie) – wyszukiwane hasło, które będzie dopasowywane do wszystkich dostępnych pól, w tym do nazw, typów i adresów, a także do opinii klientów i treści innych firm.minPriceLevel
imaxPriceLevel
(opcjonalny) – ogranicza wyniki tylko do tych miejsc w wybranym zakresie. Prawidłowe wartości mieszczą się w zakresie od 0 (najtańszy) do 4 (najdroższy).name
wycofane. Odpowiednik:keyword
. Wartości w tym polu są łączone z wartościami w polukeyword
i przekazywane jako część tego samego ciągu wyszukiwania.openNow
(opcjonalny) – wartość logiczna wskazująca, że usługa Miejsca powinna zwracać tylko te miejsca, które są otwarte w momencie wysyłania zapytania. Miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google, nie zostaną zwrócone, jeśli zapytanie zawiera ten parametr. UstawienieopenNow
nafalse
nie ma żadnego efektu.rankBy
(opcjonalny) – określa kolejność wyświetlania wyników. Możliwe wartości:google.maps.places.RankBy.PROMINENCE
(wartość domyślna). Ta opcja sortuje wyniki według ich ważności. Pozycja w rankingu będzie faworyzowana w miejscach znajdujących się w określonym promieniu niż w pobliskich miejscach, które są mniej widoczne. Na widoczność miejsca w rankingu mają wpływ ranking w indeksie Google, popularność na całym świecie i inne czynniki. Jeśli określonogoogle.maps.places.RankBy.PROMINENCE
, wymagany jest parametrradius
.google.maps.places.RankBy.DISTANCE
. Ta opcja sortuje wyniki rosnąco według odległości od określonego polalocation
(wymagane). Pamiętaj, że jeśli nie podasz właściwościRankBy.DISTANCE
, nie możesz określić właściwościbounds
aniradius
. Jeśli określiszRankBy.DISTANCE
, musisz określić co najmniej jedną z tych właściwości:keyword
,name
lubtype
.
type
– ogranicza wyniki do miejsc pasujących do określonego typu. Można podać tylko 1 typ (jeśli podasz więcej niż 1 typ, wszystkie typy występujące po pierwszym wpisie zostaną zignorowane). Zobacz listę obsługiwanych typów.
Musisz też przekazać metodę wywołania zwrotnego do nearbySearch()
, aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
Żądania wyszukiwania tekstowego
Usługa wyszukiwania tekstowego Miejsc Google to usługa internetowa, która zwraca informacje o zestawie miejsc na podstawie ciągów znaków, na przykład „pizza w Warszawie” lub „sklepy obuwnicze w pobliżu Wrocławia”. Usługa odpowiada na listę miejsc zgodnych z ciągiem tekstowym i wszelkimi ustawionymi odchyleniami lokalizacji. Odpowiedź będzie zawierać listę miejsc. Możesz wysłać prośbę o szczegóły miejsca, aby uzyskać więcej informacji o dowolnym miejscu w odpowiedzi.
Wyszukiwania tekstowe są inicjowane przez wywołanie metody textSearch()
w PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Ta metoda pobiera żądanie z tymi polami:
query
(wymagany) Ciąg tekstowy, w którym można przeprowadzić wyszukiwanie, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria instytucji. Inne typy danych wejściowych mogą generować błędy i nie gwarantują, że wyniki będą poprawne. Usługa Miejsca zwróci wyniki pasujące do tego ciągu i porządkuje wyniki na podstawie ich trafności. Ten parametr staje się opcjonalny, jeśli parametrtype
jest również używany w żądaniu wyszukiwania.- Opcjonalnie:
openNow
– wartość logiczna wskazująca, że usługa Miejsca powinna zwracać tylko te miejsca, które są otwarte w chwili wysyłania zapytania. Miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google, nie zostaną zwrócone, jeśli zapytanie zawiera ten parametr. UstawienieopenNow
nafalse
nie ma żadnego efektu.minPriceLevel
imaxPriceLevel
– ogranicza wyniki tylko do tych miejsc w ramach określonego poziomu cenowego. Prawidłowe wartości mieszczą się w zakresie od 0 (najtańszy) do 4 (najdroższy).- Wykonaj jedną z tych czynności:
bounds
– obiektgoogle.maps.LatLngBounds
definiujący prostokąt, w którym można przeprowadzić wyszukiwanie;location
iradius
– możesz odchylić wyniki dla określonego kręgu, przekazując parametrylocation
iradius
. Dzięki temu usługa Miejsca będzie preferować wyświetlanie wyników w tym kręgu. Wyniki spoza zdefiniowanego obszaru nadal mogą być wyświetlane. Lokalizacja wykorzystuje obiektgoogle.maps.LatLng
, a promień zawiera prostą liczbę całkowitą reprezentującą promień okręgu w metrach. Maksymalny dozwolony zasięg to 50 000 metrów.
type
– ogranicza wyniki do miejsc pasujących do określonego typu. Można podać tylko 1 typ (jeśli podasz więcej niż 1 typ, wszystkie typy występujące po pierwszym wpisie zostaną zignorowane). Zobacz listę obsługiwanych typów.
Musisz też przekazać metodę wywołania zwrotnego do textSearch()
, aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
Odpowiedzi na wyszukiwanie
Kody stanu
Obiekt odpowiedzi PlacesServiceStatus
zawiera stan żądania i może zawierać dane debugowania, które ułatwiają znalezienie przyczyny nieudanego żądania. Możliwe wartości stanu:
INVALID_REQUEST
: to żądanie jest nieprawidłowe.OK
: odpowiedź zawiera prawidłowy wynik.OVER_QUERY_LIMIT
: strona przekroczyła limit żądań.REQUEST_DENIED
: strona nie może używać usługi PlacesService.UNKNOWN_ERROR
: nie można przetworzyć żądania Places Service z powodu błędu serwera. Jeśli spróbujesz ponownie, prośba może się nie powieść.ZERO_RESULTS
: nie znaleziono wyników dla tego żądania.
Wyniki wyszukiwania miejsca
Funkcje findPlace()
, nearbySearch()
i textSearch()
zwracają tablicę obiektów PlaceResult
.
Każdy obiekt PlaceResult
może zawierać te właściwości:
business_status
wskazuje stan operacji dotyczącej miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
nie jest zwracana.formatted_address
to ciąg znaków zawierający adres tego miejsca w postaci zrozumiałej dla człowieka. Właściwośćformatted_address
jest zwracana tylko w przypadku wyszukiwania tekstu.Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, takie jak Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.
Sformatowany adres składa się z co najmniej 1 komponentu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).
Nie przetwarzaj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które oprócz odpowiedzi na sformatowane pole adresu zawierają odpowiedź interfejsu API.
geometry
: informacje o geometrii danego miejsca. Obejmuje to:location
zawiera szerokość i długość geograficzną miejsca.viewport
określa preferowany widoczny obszar na mapie podczas przeglądania tego miejsca.
permanently_closed
(wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe czy tymczasowo (wartośćtrue
). Nie używaj właściwościpermanently_closed
. Zamiast tego użyjbusiness_status
, aby sprawdzić stan biznesowy.plus_code
(patrz Otwarty kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji uzyskane na podstawie szerokości i długości geograficznej, które odpowiada obszarowi: 1/8000. stopnia o 1/8000. stopnia (14 x 14 m przy równiku) lub mniejszym. Kody Plus Code mogą być używane zamiast adresów w miejscach, w których nie istnieją (gdy budynki nie mają numerów lub nie mają nazw).Kod Plus Code ma format globalny i złożony:
global_code
to 4-znakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).compound_code
to co najmniej 6-znakowy kod lokalny z jednoznaczną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
html_attributions
: tablica źródeł informacji, które powinny wyświetlać się podczas wyświetlania wyników wyszukiwania. Każda pozycja w tablicy zawiera tekst HTML pojedynczego przypisania. Uwaga: jest to agregacja wszystkich atrybucji dotyczących całej odpowiedzi wyszukiwania. Wszystkie obiektyPlaceResult
w odpowiedzi zawierają więc identyczne listy atrybucji.icon
zwraca adres URL kolorowej ikony PNG o wymiarach 71 x 71 pikseli.icon_mask_base_uri
zwraca podstawowy adres URL ikony bez koloru po odjęciu rozszerzenia .svg lub .png.icon_background_color
zwraca domyślny kod szesnastkowy koloru dla kategorii miejsca.name
: nazwa miejsca.opening_hours
może zawierać te informacje:open_now
to wartość logiczna wskazująca, czy dane miejsce jest otwarte w obecnym czasie (wycofane w bibliotece Miejsc Google, Maps JavaScript API, użyjutc_offset_minutes
).
place_id
to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby uzyskać informacje o miejscu, przekaż ten identyfikator w żądaniu szczegółów miejsca. Dowiedz się więcej o odwoływaniu się do miejsc z identyfikatorem miejsca.rating
zawiera ocenę miejsca w skali od 0, 0 do 5, 0 na podstawie zagregowanych opinii użytkowników.types
Tablica typów tego miejsca (np.["political", "locality"]
lub["restaurant", "lodging"]
. Ta tablica może zawierać wiele wartości lub być pusta. Nowe wartości mogą być stosowane bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.vicinity
: uproszczony adres miejsca, w tym nazwa ulicy, numer budynku i miejscowość, ale bez prowincji, województwa, kodu pocztowego czy kraju. Na przykład biuro Google w Sydney ma w poluvicinity
wartość5/48 Pirrama Road, Pyrmont
.
Dostęp do dodatkowych wyników
Domyślnie każde wyszukiwanie miejsc zwraca maksymalnie 20 wyników na zapytanie. Każde wyszukiwanie może jednak zwrócić nawet 60 wyników na 3 strony.
Dodatkowe strony są dostępne w obiekcie PlaceSearchPagination
. Aby uzyskać dostęp do dodatkowych stron, musisz zarejestrować obiekt PlaceSearchPagination
za pomocą funkcji wywołania zwrotnego. Obiekt PlaceSearchPagination
jest zdefiniowany jako:
hasNextPage
wartość logiczna wskazująca, czy są dostępne dalsze wyniki.true
, gdy wyświetla się dodatkowa strona wyników.nextPage()
funkcję, która zwróci następny zbiór wyników. Po wykonaniu wyszukiwania musisz odczekać 2 sekundy, zanim będzie dostępna następna strona wyników.
Aby wyświetlić kolejny zestaw wyników, zadzwoń do firmy nextPage
.
Przed wyświetleniem następnej strony wyników musi zostać wyświetlona każda strona wyników. Każde wyszukiwanie jest traktowane jako jedno żądanie przekraczające limity wykorzystania.
Przykład poniżej pokazuje, jak zmienić funkcję wywołania zwrotnego, aby przechwytywać obiekt PlaceSearchPagination
tak, by móc wysyłać wiele żądań wyszukiwania.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap() { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map(document.getElementById("map"), { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", }); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage; const moreButton = document.getElementById("more"); moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, (results, status, pagination) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces(places, map) { const placesList = document.getElementById("places"); for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry.location); }); } } } window.initMap = initMap;
Fragment
Szczegóły miejsc
Oprócz podawania listy miejsc na danym obszarze usługa Miejsca może także zwracać szczegółowe informacje o konkretnym miejscu. Po zwróceniu miejsca w odpowiedzi na jego wyszukiwanie możesz użyć identyfikatora miejsca, aby poprosić o dodatkowe informacje na jego temat, takie jak pełny adres, numer telefonu, oceny, opinie użytkowników itp.
Prośby o szczegóły miejsca
Szczegóły miejsca są przesyłane wraz z wywołaniem metody getDetails()
usługi.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Przyjmuje ona żądanie zawierające placeId
docelowego miejsca oraz pola wskazujące, jakie typy danych Miejsc są zwracane. Dowiedz się więcej o odwoływaniu się do miejsc z identyfikatorem miejsca.
Przyjmuje też metodę wywołania zwrotnego, która musi obsługiwać kod stanu przekazany w odpowiedzi google.maps.places.PlacesServiceStatus
oraz obiekt google.maps.places.PlaceResult
.
var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] }; service = new google.maps.places.PlacesService(map); service.getDetails(request, callback); function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }
Pola (szczegóły miejsca)
Parametrfields
przyjmuje tablicę z ciągami znaków (nazwami pól).
Użyj parametru fields
, aby określić tablicę typów danych miejsc do zwrócenia.
na przykład: fields: ['address_component', 'opening_hours', 'geometry']
.
Przy określaniu wartości złożonych używaj kropki. na przykład: opening_hours.weekday_text
.
Pola odpowiadają wynikom szczegółów miejsca i dzielą się na trzy kategorie płatności: Podstawowe, Kontakty i Atmosfera. Pola podstawowe są rozliczane według stawki podstawowej i nie są za nie naliczane żadne dodatkowe opłaty. Pola kontaktów i atmosfery są rozliczane według wyższej stawki. Więcej informacji znajdziesz w arkuszu opłat. Atrybucja (html_attributions
) jest zawsze zwracana przy każdym wywołaniu, niezależnie od tego, czy została zażądana.
Podstawowe
Kategoria podstawowa obejmuje te pola:
address_component
, adr_address
, business_status
,
formatted_address
, geometry
, icon
,
icon_mask_base_uri
, icon_background_color
,name
,
permanently_closed
(wycofane),
photo
, place_id
, plus_code
, type
,
url
, utc_offset
(wycofane{/2,} Mapy, 2,}
Kontakt
Kategoria Kontakty obejmuje te pola:
formatted_phone_number
, international_phone_number
,
opening_hours
, website
Atmosfera
Kategoria Atmosfera zawiera te pola:
price_level
, rating
, reviews
,
user_ratings_total
Dowiedz się więcej o polach miejsc. Więcej informacji o rozliczeniu żądań danych o miejscach znajdziesz w artykule Użycie i płatności.
Odpowiedzi na temat szczegółów miejsca
Kody stanu
Obiekt odpowiedzi PlacesServiceStatus
zawiera stan żądania i może zawierać dane debugowania, które ułatwiają znalezienie przyczyny nieudanego żądania. Możliwe wartości stanu:
INVALID_REQUEST
: to żądanie jest nieprawidłowe.OK
: odpowiedź zawiera prawidłowy wynik.OVER_QUERY_LIMIT
: strona przekroczyła limit żądań.NOT_FOUND
Podana lokalizacja nie została znaleziona w bazie danych Miejsc.REQUEST_DENIED
: strona nie może używać usługi PlacesService.UNKNOWN_ERROR
: nie można przetworzyć żądania Places Service z powodu błędu serwera. Jeśli spróbujesz ponownie, prośba może się nie powieść.ZERO_RESULTS
: nie znaleziono wyników dla tego żądania.
Wyniki wyszukiwania szczegółów
Udane wywołanie getDetails()
zwraca obiekt PlaceResult
z tymi właściwościami:
address_components
: tablica zawierająca osobne komponenty stosowane do tego adresu.Każdy komponent adresu zawiera zazwyczaj następujące pola:
types[]
to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.long_name
to pełny opis lub nazwa komponentu adresu zwracana przez geokoder.short_name
to skrócona nazwa tekstowa komponentu adresu (jeśli jest dostępny). Na przykład komponent adresu dla stanu Alaska może mieć atrybutylong_name
takie jak „Alaska” ishort_name
„A” przy użyciu dwuliterowego skrótu pocztowego.
Zwróć uwagę na te informacje o tablicy
address_components[]
:- Tablica komponentów adresu może zawierać więcej komponentów niż
formatted_address
. - Tablica nie musi obejmować wszystkich jednostek politycznych zawierających adres, poza tymi wymienionymi w zasadzie
formatted_address
. Aby pobrać wszystkie jednostki polityczne zawierające określony adres, użyj odwrotnego geokodowania, podając w żądaniu parametr szerokość i długość geograficzną adresu. - Format odpowiedzi między różnymi żądaniami nie musi być taki sam. W szczególności liczba obiektów
address_components
różni się w zależności od żądanego adresu i może się zmieniać w czasie dla tego samego adresu. Komponent może zmieniać położenie tablicy. Typ komponentu może się zmienić. W odpowiedzi może brakować określonego komponentu.
business_status
wskazuje stan operacji dotyczącej miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
nie jest zwracana.formatted_address
: czytelny dla człowieka adres tego miejsca.Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, takie jak Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.
Sformatowany adres składa się z co najmniej 1 komponentu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).
Nie przetwarzaj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które oprócz odpowiedzi na sformatowane pole adresu zawierają odpowiedź interfejsu API.
formatted_phone_number
: numer telefonu miejsca zgodny z regionalną konwencją numeru.geometry
: informacje o geometrii danego miejsca. Obejmuje to:location
zawiera szerokość i długość geograficzną miejsca.viewport
określa preferowany widoczny obszar na mapie podczas przeglądania tego miejsca.
permanently_closed
(wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe czy tymczasowo (wartośćtrue
). Nie używaj właściwościpermanently_closed
. Zamiast tego użyjbusiness_status
, aby sprawdzić stan biznesowy.plus_code
(patrz Otwarty kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji uzyskane na podstawie szerokości i długości geograficznej, które odpowiada obszarowi: 1/8000. stopnia o 1/8000. stopnia (14 x 14 m przy równiku) lub mniejszym. Kody Plus Code mogą być używane zamiast adresów w miejscach, w których nie istnieją (gdy budynki nie mają numerów lub nie mają nazw).Kod Plus Code ma format globalny i złożony:
global_code
to 4-znakowy numer kierunkowy i co najmniej 6-znakowy kod lokalny (849VCWC8+R9).compound_code
to co najmniej 6-znakowy kod lokalny z jednoznaczną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
html_attributions
: tekst atrybucji, który ma być wyświetlany dla tego wyniku wyszukiwania.icon
: adres URL zasobu obrazu, którego można użyć do reprezentowania tego typu miejsca.international_phone_number
zawiera numer telefonu tego miejsca w formacie międzynarodowym. Format międzynarodowy zawiera kod kraju i jest poprzedzony znakiem plusa (+). Na przykładinternational_phone_number
w biurze Google w Australii to+61 2 9374 4000
.name
: nazwa miejsca.utc_offset
Wycofano w Bibliotece miejsc oraz Maps JavaScript API. Zamiast niego użyjutc_offset_minutes
.utc_offset_minutes
wskazuje, ile minut w bieżącym miejscu jest przesunięcia od czasu UTC. Na przykład w przypadku miejsc w Australii w okresie letnim będzie to 660 (+11 godzin od czasu UTC), a w przypadku miejsc w Kalifornii poza czasem letnim –440 (-8 godzin od czasu UTC).opening_hours
zawiera te informacje:open_now
(Wycofano w bibliotece Miejsc i interfejsie Maps JavaScript API; zamiast tego użyj opening_hours.isOpen(). Aby dowiedzieć się, jak korzystać ze znacznikówisOpen
w przypadku szczegółów miejsca, obejrzyj ten film). to wartość logiczna wskazująca, czy dane miejsce jest otwarte w danej chwili.periods[]
to szereg okresów otwarcia obejmujących 7 dni, począwszy od niedzieli, w kolejności chronologicznej. Każdy okres obejmuje:open
zawiera 2 obiekty dni i godzin opisujące moment otwarcia miejsca:day
– liczbę od 0 do 6, odpowiadającą dniom tygodnia, począwszy od niedzieli. Na przykład 2 oznacza wtorek.time
może zawierać porę dnia w formacie 24-godzinnym (wartości w zakresie 0000–2359).time
będzie raportowane według strefy czasowej miejsca.
close
może zawierać 2 obiekty dnia i godziny opisujące, kiedy miejsce jest zamknięte. Uwaga: jeśli miejsce jest zawsze otwarte, w odpowiedzi nie będzie sekcjiclose
. Aplikacje mogą polegać na tym, że zawsze otwarte są przedstawiane jako okresopen
zawierającyday
o wartości 0 itime
z wartością 0000, bez znakuclose
.
weekday_text
to tablica 7 ciągów reprezentujących godziny otwarcia w poszczególnych dniach tygodnia. Jeśli w żądaniu Szczegóły miejsca podano parametrlanguage
, usługa Miejsca sformatuje i zlokalizuje godziny otwarcia w tym języku. Kolejność elementów w tej tablicy zależy od parametrulanguage
. Niektóre języki rozpoczynają tydzień w poniedziałek, a w inne niedziele.
permanently_closed
(wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe czy tymczasowo (wartośćtrue
). Nie używaj właściwościpermanently_closed
. Zamiast tego użyjbusiness_status
, aby sprawdzić stan biznesowy.photos[]
: tablicaPlacePhoto
obiektów.PlacePhoto
może posłużyć do uzyskania zdjęcia metodągetUrl()
. Możesz też sprawdzić obiekt pod kątem tych wartości:height
: maksymalna wysokość obrazu w pikselach.width
: maksymalna szerokość obrazu w pikselach.html_attributions
: tekst atrybucji, który ma być wyświetlany z tym zdjęciem miejsca.
place_id
: identyfikator tekstowy, który jednoznacznie identyfikuje miejsce i może służyć do pobierania informacji o nim za pomocą żądania szczegółów miejsca. Dowiedz się więcej o odwoływaniu się do miejsc z identyfikatorem miejsca.rating
: ocena miejsca w skali od 0, 0 do 5, 0 na podstawie zagregowanych opinii użytkowników.reviews
tablica z maksymalnie 5 opiniami. Każda opinia składa się z kilku komponentów:aspects[]
zawiera tablicę obiektówPlaceAspectRating
. Każdy z nich zawiera ocenę pojedynczego atrybutu instytucji. Pierwszy obiekt w tablicy jest uważany za główny aspekt. Każda właściwośćPlaceAspectRating
jest zdefiniowana jako:type
nazwa ocenianego aspektu. Obsługiwane są te typy:appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
iservice
.rating
ocena użytkownika dla tego konkretnego aspektu (od 0 do 3).
author_name
nazwę użytkownika, który przesłał opinię. Anonimowe opinie są przypisywane do „Użytkownika Google”. Jeśli ustawiono parametr języka, wyrażenie „Użytkownik Google” zwróci zlokalizowany tekst.author_url
adres URL profilu Google+ użytkownika, jeśli jest dostępny.language
kod języka IETF wskazujący język używany w opinii użytkownika. To pole zawiera tylko tag języka głównego, a nie dodatkowy tag wskazujący kraj lub region. Na przykład wszystkie opinie w języku angielskim są oznaczone tagiem „en”, a nie „en-AU” lub „en-UK” itd.rating
ogólna ocena tego miejsca przez użytkownika. Jest to liczba całkowita z zakresu od 1 do 5.text
opinia użytkownika. W przypadku sprawdzania lokalizacji w Miejscach Google opinie tekstowe są uznawane za opcjonalne, dlatego to pole może być puste.
types
Tablica typów tego miejsca (np.["political", "locality"]
lub["restaurant", "lodging"]
. Ta tablica może zawierać wiele wartości lub być pusta. Nowe wartości mogą być stosowane bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.url
: adres URL oficjalnej strony Google tego miejsca. To strona należąca do Google, która zawiera najlepsze dostępne informacje o danym miejscu. Aplikacje muszą zawierać link do tej strony lub umieścić ją na dowolnym ekranie, na którym wyświetlają się szczegółowe wyniki dotyczące miejsca.vicinity
: uproszczony adres miejsca, w tym nazwa ulicy, numer budynku i miejscowość, ale bez prowincji, województwa, kodu pocztowego czy kraju. Na przykład biuro Google w Sydney ma w poluvicinity
wartość5/48 Pirrama Road, Pyrmont
. Właściwośćvicinity
jest zwracana tylko w przypadku wyszukiwania w pobliżu.website
wyświetla wiarygodne witryny, takie jak strona główna firmy.
Uwaga: oceny wielowymiarowe mogą nie być dostępne we wszystkich lokalizacjach. Jeśli jest ich zbyt mało, w szczegółach odpowiedzi podana będzie starsza ocena w skali od 0,0 do 5,0 (jeśli jest dostępna) lub też ocena całkowita.
Odwoływanie się do miejsca z jego identyfikatorem
Identyfikator miejsca to unikalne odwołanie do miejsca na Mapach Google. Identyfikatory miejsc są dostępne dla większości lokalizacji, w tym firm, punktów orientacyjnych, parków i skrzyżowań.
Aby używać w swojej aplikacji identyfikatora miejsca, musisz najpierw go wyszukać. Jest on dostępny w sekcji PlaceResult
w wyszukiwarce lub szczegółów lokalizacji.
Możesz go potem użyć, aby wyszukać szczegóły miejsca.
Identyfikatory miejsc są zwolnione z ograniczeniach dotyczących pamięci podręcznej opisanych w Sekcji 3.2.3(a) Warunków korzystania z Google Maps Platform. Dlatego możesz zapisywać wartości identyfikatorów miejsc na później. Sprawdzone metody przechowywania identyfikatorów miejsc znajdziesz w omówieniu identyfikatorów miejsc.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
Zdjęcia miejsca
Funkcja Dodaj zdjęcie do witryny pozwala dodawać do witryny wysokiej jakości treści fotograficzne. Usługa Zdjęcia daje dostęp do milionów zdjęć przechowywanych w bazie danych Miejsc i Google+ Lokalnie. Gdy otrzymasz informacje o miejscu za pomocą prośby o dane miejsca, odniesienia do zdjęć zostaną zwrócone w przypadku odpowiednich treści fotograficznych. Żądania wyszukiwania w pobliżu i wyszukiwania tekstowego zwracają w razie potrzeby również 1 odwołanie do danego miejsca. Dzięki usłudze Zdjęcia możesz uzyskać dostęp do zdjęć, do których odwołuje się plik, i zmienić rozmiar zdjęcia w optymalnym rozmiarze.
Tablica obiektów PlacePhoto
zostanie zwrócona w ramach obiektu PlaceResult
w przypadku każdego żądania getDetails()
, textSearch()
lub nearbySearch()
wysłanego do PlacesService
.
Uwaga: liczba zwróconych zdjęć zależy od danego żądania.
- Wyszukiwanie w pobliżu lub wyszukiwanie tekstowe zwróci co najwyżej 1 obiekt
PlacePhoto
. - Żądanie Szczegóły zwróci maksymalnie 10 obiektów
PlacePhoto
.
Aby poprosić o adres URL powiązanego obrazu, wywołaj metodę PlacePhoto.getUrl()
i przekaż prawidłowy obiekt PhotoOptions
. Obiekt PhotoOptions
pozwala określić maksymalną żądaną wysokość i szerokość obrazu. Jeśli podasz wartość zarówno maxHeight
, jak i maxWidth
, usługa fotograficzna zmniejszy rozmiar obrazu o dwa rozmiary, zachowując oryginalny współczynnik proporcji.
Poniższy fragment kodu akceptuje obiekt miejsca i dodaje znacznik do mapy, jeśli zdjęcie istnieje. Domyślny obraz znacznika jest zastępowany małą wersją zdjęcia.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
Zdjęcia zwracane przez usługę Zdjęcia pochodzą z różnych lokalizacji, w tym od właścicieli firm i ze zdjęć przesłanych przez użytkowników. W większości przypadków tych zdjęć można użyć bez informacji o wykonaniu lub zawierać wymagane podanie źródła. Jeśli jednak zwrócony element photo
zawiera wartość w polu html_attributions
, musisz umieścić dodatkową informację o aplikacji w każdym miejscu, w którym wyświetlasz obraz.