Przegląd
Funkcje Biblioteki miejsc oraz Maps JavaScript API umożliwiają Twojej aplikacji wyszukiwanie miejsc (zdefiniowanych w tym interfejsie jako punktów orientacyjnych, geograficznych lokalizacji lub ciekawych miejsc) zawartych w określonym obszarze, takich jak granice mapy lub wokół ustalonego punktu.
Interfejs Places API udostępnia funkcję autouzupełniania, której możesz używać do nadawania aplikacjom pierwszeństwa w polu wyszukiwania Map Google. Gdy użytkownik zacznie wpisywać adres, funkcja autouzupełniania wypełni resztę. Więcej informacji znajdziesz w dokumentacji autouzupełniania.
Pierwsze kroki
Jeśli nie znasz jeszcze interfejsu API JavaScript Map Google lub JavaScriptu, zanim zaczniesz, zalecamy sprawdzenie JavaScriptu i otrzymanie klucza interfejsu API.
Włącz interfejsy API
Zanim zaczniesz korzystać z biblioteki Miejsc w interfejsie Maps JavaScript API, najpierw upewnij się, że interfejs Places API jest włączony w Google Cloud Console w tym samym projekcie, który masz skonfigurowany w 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 Maps JavaScript API, i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Places API.
- Jeśli widzisz na liście 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. W menu po lewej stronie możesz też wybrać Biblioteka.
- Wyszukaj Places API, a następnie wybierz go z listy wyników.
- Kliknij WŁĄCZ. Po zakończeniu tego procesu na liście interfejsów API w panelu pojawi się interfejs Places API.
Wczytuję bibliotekę
Usługa Miejsca to samodzielna biblioteka oddzielona 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 URL-u modułu 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 interfejs Places API do listy ograniczeń interfejsu API klucza interfejsu API
Stosowanie ograniczeń interfejsu API do kluczy ogranicza korzystanie z klucza 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 będą kończyć się niepowodzeniem. Aby ograniczyć użycie klucza interfejsu API do biblioteki miejsc, interfejs Maps JavaScript API:- Otwórz konsolę Google Cloud.
- 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 oraz interfejs Maps JavaScript API i interfejs Places API.
Jeśli na liście nie ma któregoś z interfejsów API, musisz go włączyć.
- Kliknij ZAPISZ.
Limity wykorzystania i zasady
Limity
Biblioteka miejsc ma wspólny limit wykorzystania z interfejsem Places API, jak opisano w dokumentacji limitów korzystania z interfejsu Places API.
Zasady
Korzystanie z Biblioteki miejsc: interfejs Maps JavaScript API musi być zgodny z zasadami opisanymi w interfejsie Places API.
Wyszukiwanie miejsc
Usługa Miejsca umożliwia wykonywanie następujących wyszukiwań:
- 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 geograficzne, które wskazują adresy, obszary polityczne, takie jak miasta czy inne miejsca.
Znajdowanie miejsc
Zapytanie Znajdź miejsca umożliwia wyszukiwanie miejsca za pomocą zapytania tekstowego lub numeru telefonu. Istnieją 2 typy żądania Znajdź miejsce:
Znajdź miejsce na podstawie zapytania
Funkcja Znajdź z zapytania pobiera tekst i zwraca miejsce. 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 następujące parametry:
query
(wymagane) Ciąg tekstowy, na którym można przeprowadzić wyszukiwanie, na przykład „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria instytucji. Inne typy danych wejściowych mogą powodować 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) Co najmniej jedno pole, które określa typy danych z miejsca do zwrócenia.locationBias
(opcjonalnie) współrzędne określające obszar do wyszukania. Oto możliwe przyczyny:- Zbiór współrzędnych szerokości/długości geograficznej wskazanych jako LatLngLiteral lub obiekt LatLng
- Obramowanie prostokątne (2 pary szerokości i długości geograficznej lub obiekt LatLngBound)
- Promień (w metrach) wyśrodkowany na lat/dl.
Musisz też przekazać metodę wywołania zwrotnego do findPlaceFromQuery()
, aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus
.
Poniższy przykład pokazuje połączenie z obiektem findPlaceFromQuery()
, wyszukując hasło „Muzeum Sztuki Współczesnej Australia” z polami 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 wysłać żądanie Znajdź miejsce z numeru telefonu, wywołaj metodę PlacesService
findPlaceFromPhoneNumber()
, która przyjmuje te parametry:
phoneNumber
(wymagany) numer telefonu w formacie E.164.fields
(wymagane) Co najmniej jedno pole, które określa typy danych z miejsca do zwrócenia.locationBias
(opcjonalnie) współrzędne określające obszar do wyszukiwania. Oto możliwe przyczyny:- Zbiór współrzędnych szerokości/długości geograficznej wskazanych jako LatLngLiteral lub obiekt LatLng
- Granice prostokątne (cztery punkty szerokości/długości geograficznej lub obiekt LatLngBound)
- Promień (w metrach) wyśrodkowany na lat/dl.
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 miejsca do zwrócenia.
Przykład: fields: ['formatted_address', 'opening_hours', 'geometry']
.
Aby określić wartości zespolone, użyj kropki. Przykład: opening_hours.weekday_text
.
Pola odpowiadają wynikom wyszukiwania miejsc i są podzielone na 3 kategorie płatności: podstawowe, kontakt i atmosferę. Podstawowe pola są rozliczane według stawki podstawowej i nie pobierają 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 zażądano.
Podstawowe
Kategoria podstawowa obejmuje następujące 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, interfejs Maps JavaScript API. Aby uzyskać wyniki
opening_hours
, użyj żądania szczegółów miejsca.
Atmosfera
Kategoria atmosfery obejmuje następujące pola:price_level
, rating
, user_ratings_total
Każda z metod findPlaceFromQuery()
i findPlaceFromPhoneNumber()
ma ten sam zestaw pól i może zwracać te same pola w swoich odpowiedziach.
Ustawianie odchylenia lokalizacji (metody Znajdź miejsce)
Używaj parametru locationBias
, aby uzyskać w określonym obszarze wyniki dotyczące Znajdź miejsce. locationBias
możesz ustawić na te sposoby:
Odchylenie wyników w określonym obszarze:
locationBias: {lat: 37.402105, lng: -122.081974}
Zdefiniuj prostokątny obszar na potrzeby wyszukiwania:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Możesz też użyć elementu LatLngBounds.
Zdefiniuj promień na wyszukiwanie (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 umożliwia wyszukiwanie miejsc na określonym obszarze według słowa kluczowego lub typu. Wyszukiwanie w pobliżu musi zawsze uwzględniać lokalizację, którą można określić na jeden z 2 sposobów:
-
LatLngBounds
. - Okrągły obszar zdefiniowany jako połączenie właściwości
location
(wskazujący środek okręgu jako obiektLatLng
) i promień wyrażony w metrach.
Wyszukiwanie w pobliżu jest inicjowane w wywołaniu metody nearbySearch()
metody
PlacesService
, która zwraca tablicę obiektów
PlaceResult
. Uwaga: 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:
- Jeden z tych sposobów:
bounds
, który musi być obiektemgoogle.maps.LatLngBounds
definiującym prostokątny obszar wyszukiwania;location
iradius
; pierwszy pobiera obiektgoogle.maps.LatLng
, a drugi – prostą liczbę całkowitą, reprezentując promień koła w metrach. Maksymalny dozwolony promień to 50 000 metrów. Pamiętaj, że gdyrankBy
ma wartość Odległość, musisz określićlocation
, ale nie możesz określićradius
lubbounds
.
keyword
(opcjonalnie) – hasło, które ma zostać dopasowane do wszystkich dostępnych pól, w tym do nazwy, typu i adresu, a także opinii klientów i innych treści należących do osób trzecich.minPriceLevel
imaxPriceLevel
(opcjonalne) – ogranicza wyniki tylko do tych miejsc w określonym zakresie. Prawidłowe wartości: od 0 (najtańsza) do 4 (najdroższa).name
– wycofane. Odpowiednik:keyword
. Wartości w tym polu są łączone z wartościami w polukeyword
i przekazywane w ramach tego samego ciągu wyszukiwania.openNow
(opcjonalny) – wartość logiczna wskazująca, że w momencie wysyłania zapytania usługa Miejsca powinna zwracać tylko te miejsca, które są otwarte. Miejsca, które nie określają godzin otwarcia w bazie danych Miejsc Google, nie będą uwzględniane, jeśli zapytanie zwróci ten parametr. UstawienieopenNow
nafalse
nie ma żadnego efektu.rankBy
(opcjonalnie) – 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 znaczenia. Ranking będzie faworyzować miejsca w określonym promieniu wokół adresów w pobliżu, ale mniej popularne. Na widoczność miejsca mogą mieć wpływ ranking miejsca 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 powoduje sortowanie wyników w kolejności rosnącej według odległości określonej przez wartośćlocation
(wymagane). Pamiętaj, że nie możesz określić właściwości niestandardowychbounds
aniradius
, jeśli podaszRankBy.DISTANCE
. Jeśli określisz właściwośćRankBy.DISTANCE
, wymagana jest co najmniej jedna 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 następujące po pierwszym wpisie będą ignorowane). 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”. Odpowiada ona za listą miejsc pasujących do ciągu tekstowego i ustawionych wartości odchylenia lokalizacji. Odpowiedź będzie zawierać listę miejsc. Aby uzyskać więcej informacji o dowolnym miejscu w odpowiedzi, możesz wysłać prośbę o miejsce.
Wyszukiwanie tekstu jest inicjowane przez wywołanie metody PlacesService
textSearch()
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Ta metoda pobiera żądanie z tymi polami:
query
(wymagany) Ciąg tekstowy, na którym można przeprowadzić wyszukiwanie, na przykład „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria instytucji. Inne typy danych wejściowych mogą powodować błędy i nie gwarantują, że wyniki będą prawidłowe. Usługa Miejsca zwraca wyniki pasujące do tego ciągu i porządkuje wyniki na podstawie ich trafności. Ten parametr staje się opcjonalny, jeśli w żądaniu wyszukiwania używany jest też parametrtype
.- Opcjonalnie:
openNow
– 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 określają godzin otwarcia w bazie danych Miejsc Google, nie będą uwzględniane, jeśli zapytanie zwróci ten parametr. UstawienieopenNow
nafalse
nie ma żadnego efektu.minPriceLevel
imaxPriceLevel
– ogranicza wyniki tylko do tych miejsc w określonym poziomie cenowym. Akceptowane są wartości z zakresu od 0 (najtańszy) do 4 (najdroższy).- Jeden z tych sposobów:
bounds
– obiektgoogle.maps.LatLngBounds
definiujący prostokąt, w którym ma nastąpić wyszukiwanie; lublocation
iradius
– możesz odchylić wyniki dla określonego kręgu, przekazując parametrylocation
iradius
. Dzięki temu usługa Miejsca woli preferować wyświetlanie wyników w tym okręgu. Wyniki spoza określonego obszaru mogą nadal być wyświetlane. Lokalizacja przyjmuje obiektgoogle.maps.LatLng
, a promień wyznacza prostą liczbę całkowitą, reprezentującą promień koła w metrach. Maksymalny dozwolony promień 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 następujące po pierwszym wpisie będą ignorowane). 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 wyszukiwania
Kody stanu
Obiekt odpowiedzi PlacesServiceStatus
zawiera stan żądania i może zawierać informacje ułatwiające debugowanie, dzięki którym możesz ustalić, dlaczego nie udało się wysłać prośby o miejsce. 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
: na stronie nie wolno korzystać z usługi PlacesService.UNKNOWN_ERROR
: nie udało się przetworzyć żądania Miejsca usługi z powodu błędu serwera. Prośba może się udać, jeśli spróbujesz ponownie.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:
- Wskaźnik
business_status
wskazuje stan operacyjny miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
nie jest zwracany. formatted_address
to ciąg znaków zawierający adres miejsca czytelny dla człowieka. Właściwośćformatted_address
jest zwracana tylko w przypadku wyszukiwarki 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 jednego komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z następujących elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).
Nie analizuj automatycznie sformatowanego adresu. Zamiast nich należy używać poszczególnych komponentów adresu, które oprócz odpowiedzi na pole formatowania zawierają odpowiedź interfejsu API.
geometry
: informacje geometryczne dotyczące miejsca. na przykład:location
podaje szerokość i długość geograficzną miejsca.viewport
określa preferowany widoczny obszar na mapie, gdy wyświetlasz to miejsce.
permanently_closed
(wycofany) 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 operacyjny firm.plus_code
(patrz Otwórz kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji uzyskane na podstawie współrzędnych geograficznych: Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie istnieją (gdy budynki nie są numerowane lub nie mają nazw ulic).Kod plus jest sformatowany jako kod globalny i kod złożony:
global_code
to 4-cyfrowy 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 tej treści programowo.
html_attributions
: tablica atrybucji, która powinna być wyświetlana podczas wyświetlania wyników wyszukiwania. Każdy wpis w tablicy zawiera tekst HTML pojedynczego atrybucji. 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 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 obecnie otwarte (Wycofane w bibliotece interfejsu Places API lub Maps JavaScript API; zamiast tego użyjutc_offset_minutes
).
place_id
to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w żądaniu szczegółów miejsca. Dowiedz się więcej o dodawaniu odwołań do miejsc z identyfikatorem miejsca.- Ocena
rating
tego miejsca na podstawie zagregowanych opinii użytkowników to od 0, 0 do 5, 0. types
Tablica typów tego miejsca (np.["political", "locality"]
lub["restaurant", "lodging"]
. Tablica może zawierać wiele wartości lub być pusta. Nowe wartości można wprowadzać bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.vicinity
: uproszczony adres miejsca, w tym nazwa ulicy, numer domu i miejscowość, ale nie prowincja/stan, kod pocztowy ani kraj. Na przykład biuro Google w Sydney ma wartośćvicinity
5/48 Pirrama Road, Pyrmont
.
Dostęp do dodatkowych wyników
Domyślnie każde wyszukiwanie miejsc zwraca do 20 wyników na zapytanie. Każde wyszukiwanie może jednak zwrócić maksymalnie 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
właściwość logiczna, która wskazuje, czy są dostępne dalsze wyniki.true
, gdy dostępna jest dodatkowa strona wyników.nextPage()
– funkcja, która zwróci następny zbiór wyników. Po wykonaniu wyszukiwania musisz odczekać 2 sekundy, zanim będzie dostępna kolejna strona wyników.
Aby wyświetlić następny zestaw wyników, zadzwoń do nextPage
.
Każda kolejna strona wyników musi być wyświetlona przed wyświetleniem następnej. Każde wyszukiwanie liczy się jako jedno żądanie przekraczające limity wykorzystania.
Przykład poniżej pokazuje, jak zmienić funkcję wywołania zwrotnego, aby przechwycić obiekt PlaceSearchPagination
w sposób umożliwiający wysłanie wielu żą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 jego identyfikator miejsca może zostać użyty do wysłania prośby o dodatkowe informacje o danym miejscu, takie jak jego pełny adres, numer telefonu, oceny i opinie użytkowników.
Prośby o dodanie szczegółów miejsca
Szczegóły miejsca są wysyłane z wywołaniem metody getDetails()
usługi.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Ta metoda pobiera żądanie zawierające placeId
miejsca docelowego i pola, które wskazują typy danych Miejsc do zwrócenia. Dowiedz się więcej o dodawaniu odwołań do miejsc z identyfikatorem miejsca.
Przyjmuje też metodę wywołania zwrotnego, który 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ę ciągów (nazwy pól).
Użyj parametru fields
, aby określić tablicę typów danych miejsca do zwrócenia.
Przykład: fields: ['address_components', 'opening_hours', 'geometry']
.
Aby określić wartości zespolone, użyj kropki. Przykład: opening_hours.weekday_text
.
Pola odpowiadają wynikom Szczegóły miejsca i są podzielone na 3 kategorie płatności: Podstawowe, Kontakt i atmosfera. W przypadku pól podstawowych naliczane są opłaty podstawowe, za które nie są 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 następujące pola:
address_components
, 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
({19/JavaScript Miejsca}22,
utc_offset_minutes
vicinity
Kontakt
Kategoria „Dane kontaktowe” obejmuje te pola:
formatted_phone_number
, international_phone_number
,
opening_hours
, website
Atmosfera
Kategoria atmosfery obejmuje następujące pola:
price_level
, rating
, reviews
,
user_ratings_total
Dowiedz się więcej o polach miejsc. Więcej informacji o naliczaniu opłat za żądania danych o miejscach znajdziesz w artykule Użycie i rozliczenia.
Odpowiedzi na temat szczegółów miejsca
Kody stanu
Obiekt odpowiedzi PlacesServiceStatus
zawiera stan żądania i może zawierać dane debugowania, które pomogą Ci ustalić, dlaczego żądanie szczegółów miejsca się nie powiodło. 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
Nie można znaleźć wskazanej lokalizacji w bazie danych Miejsc.REQUEST_DENIED
: na stronie nie wolno korzystać z usługi PlacesService.UNKNOWN_ERROR
: nie udało się przetworzyć żądania Miejsca usługi z powodu błędu serwera. Prośba może się udać, jeśli spróbujesz ponownie.ZERO_RESULTS
: nie znaleziono wyników dla tego żądania.
Wyniki wyszukiwania szczegółów miejsca
Udane wywołanie getDetails()
zwraca obiekt
PlaceResult
z tymi właściwościami:
address_components
: tablica zawierająca osobne komponenty związane z tym adresem.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ępna). Na przykład komponent adresu w stanie Alaska może zawierać wartościlong_name
„Alaska” ishort_name
„AK” korzystające z dwuliterowego skrótu kodu pocztowego.
Zapamiętaj te fakty na temat tablicy
address_components[]
:- Tablica komponentów adresu może zawierać więcej komponentów niż element
formatted_address
. - Tablica nie musi obejmować wszystkich jednostek politycznych zawierających adres oprócz tych uwzględnionych w polu
formatted_address
. Aby pobrać wszystkie elementy polityczne zawierające konkretny adres, użyj odwrotnego geokodowania. W tym żądaniu podaj szerokość i długość geograficzną adresu. - Format odpowiedzi nie może być taki sam między żądaniami. W szczególności liczba obiektów
address_components
różni się w zależności od żądanego adresu i może się zmienić z upływem czasu. Komponent może zmieniać pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować konkretnego komponentu.
- Wskaźnik
business_status
wskazuje stan operacyjny miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
nie jest zwracany. 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 jednego komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z następujących elementów: „111” (numer domu), „8th Avenue” (trasa), „Nowy Jork” (miasto) i „NY” (stan USA).
Nie analizuj automatycznie sformatowanego adresu. Zamiast nich należy używać poszczególnych komponentów adresu, które oprócz odpowiedzi na pole formatowania zawierają odpowiedź interfejsu API.
formatted_phone_number
: numer telefonu w danym miejscu zgodny z konwencją regionalną.geometry
: informacje geometryczne dotyczące miejsca. na przykład:location
podaje szerokość i długość geograficzną miejsca.viewport
określa preferowany widoczny obszar na mapie, gdy wyświetlasz to miejsce.
permanently_closed
(wycofany) 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 operacyjny firm.plus_code
(patrz Otwórz kod lokalizacji i kody Plus Code) to zakodowane odniesienie do lokalizacji uzyskane na podstawie współrzędnych geograficznych: Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie istnieją (gdy budynki nie są numerowane lub nie mają nazw ulic).Kod plus jest sformatowany jako kod globalny i kod złożony:
global_code
to 4-cyfrowy 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 tej treści programowo.
html_attributions
: tekst atrybucji, który będzie wyświetlany dla tego wyniku miejsca.icon
: adres URL zasobu graficznego, którego można używać do reprezentowania typu tego 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 przypadku Google w Australii to+61 2 9374 4000
.name
: nazwa miejsca.utc_offset
Wycofano w bibliotece interfejsu Miejsc Google (interfejs JavaScript JavaScript API). Zamiast niej używaj polautc_offset_minutes
.utc_offset_minutes
podaje liczbę minut wskazującą, jaka strefa czasowa miejsca jest przesunięcie względem czasu UTC. Na przykład w przypadku miejsc w Australii w czasie letnim jest to 660 (+11 godzin od czasu UTC), a w przypadku miejsc w Kalifornii poza czasem letnim wynosi ona -480 (-8 godzin od UTC).opening_hours
zawiera te informacje:open_now
(Wycofano w bibliotece miejsca i w interfejsie Maps JavaScript API; użyj zamiast tego funkcji opening_hours.isOpen(). Obejrzyj ten film, aby dowiedzieć się, jak używać właściwościisOpen
ze szczegółami miejsca). to wartość logiczna wskazująca, czy miejsce jest obecnie otwarte.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 dnia i godziny opisujące, kiedy dane miejsce jest otwierane: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 ggmm 24-godzinnym (wartości należą do zakresu 0000–2359). Danetime
będą raportowane według strefy czasowej miejsca.
close
może zawierać 2 obiekty dnia i godziny opisujące, kiedy miejsce jest zamykane. Uwaga: jeśli miejsce jest zawsze otwarte, w odpowiedzi nie będzie sekcjiclose
. Aplikacje mogą opierać się na zawsze otwartym procesie reprezentującym okresopen
zawierającyday
z wartością 0 itime
z wartością 0000, bezclose
.
weekday_text
to seria 7 ciągów reprezentujących godziny otwarcia w poszczególnych dniach tygodnia. Jeśli w żądaniu szczegółów miejsca podano parametrlanguage
, usługa Miejsca odpowiednio sformatuje i zlokalizuje godziny otwarcia w danym języku. Kolejność elementów w tej tablicy zależy od parametrulanguage
. Niektóre języki zaczynają się w poniedziałek, a inne w niedzielę.
permanently_closed
(wycofany) 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 operacyjny firm.photos[]
: tablicaPlacePhoto
obiektów. Aby uzyskać zdjęcie za pomocą metodygetUrl()
, możesz użyćPlacePhoto
. 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 informacji, 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 miejscu za pomocą żądania szczegółów miejsca. Dowiedz się więcej o dodawaniu odwołań 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 elementów:aspects[]
zawiera tablicę obiektówPlaceAspectRating
, z których każdy zawiera ocenę pojedynczego atrybutu instytucji. Pierwszy obiekt w tablicy jest uważany za główny aspekt. KażdyPlaceAspectRating
jest zdefiniowany jako:type
nazwa ocenianego aspektu. Obsługiwane typy:appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
iservice
.rating
ocena użytkownika w przypadku tego konkretnego aspektu (od 0 do 3).
author_name
– imię i nazwisko użytkownika, który przesłał opinię. Anonimowe opinie są przypisywane do „Użytkownika Google”. Gdy ustawisz 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 tag dodatkowy wskazujący kraj lub region. Na przykład wszystkie opinie w języku angielskim są oznaczone jako „en”, a nie „en-AU” lub „en-UK” itd.rating
ogólna ocena użytkownika dla tego miejsca. Jest to liczba całkowita z zakresu od 1 do 5.text
opinia użytkownika. Podczas 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"]
. Tablica może zawierać wiele wartości lub być pusta. Nowe wartości można wprowadzać bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.url
: adres URL oficjalnej strony Google dla tego miejsca. To jest strona Google, która zawiera najlepsze dostępne informacje o miejscu. Aplikacje muszą umieścić link do tej strony lub umieścić ją na dowolnym ekranie, na którym wyświetlają się szczegółowe wyniki dotyczące tego miejsca.vicinity
: uproszczony adres miejsca, w tym nazwa ulicy, numer domu i miejscowość, ale nie prowincja/stan, kod pocztowy ani kraj. Na przykład biuro Google w Sydney ma wartośćvicinity
5/48 Pirrama Road, Pyrmont
. Właściwośćvicinity
jest zwracana tylko w przypadku wyszukiwania w pobliżu.website
podaje wiarygodną stronę tego miejsca, np. stronę główną firmy.
Uwaga: w przypadku niektórych lokalizacji oceny wielowymiarowe mogą być niedostępne. Jeśli jest zbyt mało opinii, odpowiedź szczegółowa będzie zawierać ocenę starszą w skali od 0,0 do 5,0 (jeśli jest dostępna) lub nie będzie w ogóle zawierać oceny.
Odwoływanie się do miejsca za pomocą identyfikatora miejsca
Identyfikator miejsca to unikalne odwołanie do miejsca na mapie Google. Identyfikatory miejsc są dostępne dla większości lokalizacji, w tym firm, punktów orientacyjnych, parków i skrzyżowań.
Aby użyć w swojej aplikacji identyfikatora miejsca, musisz najpierw go wyszukać. Znajdziesz go w PlaceResult
zapytania o miejsce lub szczegółów.
Możesz go użyć, by wyszukać Szczegóły miejsca.
Identyfikatory miejsc są zwolnione z ograniczeń przechowywania w pamięci podręcznej opisanych w Sekcji 3.2.3(a) Warunków korzystania z Google Maps Platform. Dlatego możesz przechowywać wartości identyfikatorów miejsc na później. Sprawdzone metody przechowywania identyfikatorów miejsc znajdziesz w artykule Omówienie 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 Zdjęcia miejsca umożliwia dodawanie do witryny wysokiej jakości treści fotograficznych. Usługa ta zapewnia dostęp do milionów zdjęć przechowywanych w bazie danych Miejsc Google i Google+. Gdy otrzymasz informacje o miejscach na podstawie prośby o dane miejsca, zwracane będą odwołania do odpowiednich treści fotograficznych. Zapytania dotyczące wyszukiwania w pobliżu i wyszukiwania tekstu zwracają też jedno odwołanie do zdjęcia miejsca (jeśli dotyczy). Za pomocą usługi zdjęć możesz uzyskać dostęp do wymienionych zdjęć i zmienić rozmiar zdjęcia, tak aby dopasować go do aplikacji.
Tablica obiektów PlacePhoto
zostanie zwrócona jako część obiektu PlaceResult
w przypadku każdego żądania getDetails()
, textSearch()
lub nearbySearch()
wysłanego do PlacesService
.
Uwaga: liczba zwróconych zdjęć może się różnić w zależności od prośby.
- Wyszukiwanie w pobliżu lub wyszukiwanie tekstowe zwróci maksymalnie 1 obiekt
PlacePhoto
. - Żądanie Szczegóły zwróci maksymalnie 10 obiektów
PlacePhoto
.
Możesz poprosić o adres URL powiązanego obrazu, wywołując metodę PlacePhoto.getUrl()
i przesyłając prawidłowy obiekt PhotoOptions
. Obiekt PhotoOptions
umożliwia określenie maksymalnej dozwolonej wysokości i szerokości obrazu. Jeśli podasz zarówno wartość maxHeight
, jak i maxWidth
, usługa fotograficzna dostosuje rozmiar obrazu do mniejszych rozmiarów, zachowując oryginalny współczynnik proporcji.
Ten fragment kodu akceptuje obiekt Place i dodaje do mapy znacznik, 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 zdjęć użytkowników. W większości przypadków tych zdjęć można użyć bez oznaczenia lub jako część obrazu dodać wymagane oznaczenie. Jeśli jednak zwrócony element photo
zawiera wartość w polu html_attributions
, musisz podać dodatkową atrybucję w aplikacji wszędzie tam, gdzie wyświetlasz obraz.