biblioteka Miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

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:

  1. Otwórz Google Cloud Console.
  2. Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Places API.
  4. 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:
    1. 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.
    2. Wyszukaj Places API, a następnie wybierz go z listy wyników.
    3. 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:
  1. Otwórz konsolę Google Cloud.
  2. Kliknij menu projektu i wybierz projekt zawierający klucz interfejsu API, który chcesz zabezpieczyć.
  3. Kliknij przycisk menu i wybierz Google Maps Platform > Dane logowania.
  4. Na stronie Dane logowania kliknij nazwę klucza interfejsu API, który chcesz zabezpieczyć.
  5. 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ć.
  6. 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ń:

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 obiekt LatLng) 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ć obiektem google.maps.LatLngBounds definiującym prostokątny obszar wyszukiwania;
    • location i radius; pierwszy pobiera obiekt google.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 gdy rankBy ma wartość Odległość, musisz określić location, ale nie możesz określić radius lub bounds.
  • 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 i maxPriceLevel (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 polu keyword 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. Ustawienie openNow na false 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ślono google.maps.places.RankBy.PROMINENCE, wymagany jest parametr radius.
    • 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 niestandardowych bounds ani radius, jeśli podasz RankBy.DISTANCE. Jeśli określisz właściwość RankBy.DISTANCE, wymagana jest co najmniej jedna z tych właściwości: keyword, name lub type.
  • 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]);
    }
  }
}

Zobacz przykład

Żą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ż parametr type.
  • 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. Ustawienie openNow na false nie ma żadnego efektu.
    • minPriceLevel i maxPriceLevel – 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 – obiekt google.maps.LatLngBounds definiujący prostokąt, w którym ma nastąpić wyszukiwanie; lub
      • location i radius – możesz odchylić wyniki dla określonego kręgu, przekazując parametry location i radius. 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 obiekt google.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
    Jeśli dane nie istnieją, 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ści permanently_closed. Zamiast tego użyj business_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.
    Zwykle zwracane są zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległej lokalizacji (np. w oceanie lub na pustyni), może zostać zwrócony tylko kod globalny.
  • 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 obiekty PlaceResult 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żyj utc_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;
index.ts

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;
index.js
Zobacz przykład

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

Zobacz przykład

Pola (szczegóły miejsca)

Parametr fields 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_minutesvicinity

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ści long_name „Alaska” i short_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
    Jeśli dane nie istnieją, 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ści permanently_closed. Zamiast tego użyj business_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.
    Zwykle zwracane są zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległej lokalizacji (np. w oceanie lub na pustyni), może zostać zwrócony tylko kod globalny.
  • 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ład international_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 pola utc_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ści isOpen 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). Dane time 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 sekcji close. Aplikacje mogą opierać się na zawsze otwartym procesie reprezentującym okres open zawierający day z wartością 0 i time z wartością 0000, bez close.
    • 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 parametr language, usługa Miejsca odpowiednio sformatuje i zlokalizuje godziny otwarcia w danym języku. Kolejność elementów w tej tablicy zależy od parametru language. 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ści permanently_closed. Zamiast tego użyj business_status, aby sprawdzić stan operacyjny firm.
  • photos[]: tablica PlacePhoto obiektów. Aby uzyskać zdjęcie za pomocą metody getUrl(), 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ów PlaceAspectRating, z których każdy zawiera ocenę pojedynczego atrybutu instytucji. Pierwszy obiekt w tablicy jest uważany za główny aspekt. Każdy PlaceAspectRating jest zdefiniowany jako:
      • type nazwa ocenianego aspektu. Obsługiwane typy: appeal, atmosphere, decor, facilities, food, overall, quality i service.
      • 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.