biblioteka Miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Przegląd

Funkcje biblioteki Miejsc w interfejsie Maps JavaScript API umożliwiają aplikacji wyszukiwanie miejsc (zdefiniowanych w tym interfejsie API jako placówki, lokalizacje geograficzne lub ważne punkty orientacyjne) na określonym obszarze, np. w granicach mapy lub wokół stałego punktu.

Interfejs Places API udostępnia funkcję autouzupełniania, dzięki której możesz dodać do swoich aplikacji funkcję wyszukiwania z podpowiedziami, która działa tak samo jak pole wyszukiwania w Mapach 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 interfejsu Maps JavaScript API ani języka JavaScript, przed rozpoczęciem zapoznaj się z informacjami o języku JavaScript i uzyskiwaniu klucza interfejsu API.

Wczytywanie biblioteki

Usługa Places to samodzielna biblioteka, oddzielona od głównego kodu Maps JavaScript API. Aby korzystać z funkcji zawartych w tej bibliotece, musisz najpierw wczytać ją za pomocą parametru libraries w adresie URL wczytywania interfejsu API Map Google:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Więcej informacji znajdziesz w  omówieniu bibliotek.

Dodawanie Places API (starszej wersji) do listy ograniczeń interfejsu API klucza interfejsu API

Zastosowanie ograniczeń interfejsu API do kluczy ogranicza użycie klucza interfejsu API do jednego lub kilku interfejsów API lub pakietów SDK. Przetwarzane są żądania do interfejsu API lub pakietu SDK powiązane z kluczem interfejsu API. Żądania do interfejsu API lub pakietu SDK niepowiązane z kluczem interfejsu API kończą się niepowodzeniem. Aby ograniczyć klucz interfejsu API do użycia z biblioteką miejsc, 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 i wybierz Maps JavaScript API oraz Places API (starsza wersja).
        (Jeśli któregoś z interfejsów API nie ma na liście, musisz go włączyć).
  6. Kliknij ZAPISZ.

Limity wykorzystania i zasady

Limity

Biblioteka Miejsc współdzieli limit wykorzystania z interfejsem Places API, jak opisano w dokumentacji dotyczącej limitów wykorzystania interfejsu Places API.

Zasady

Korzystanie z biblioteki Miejsc w Maps JavaScript API musi być zgodne z zasadami opisanymi w przypadku Places API.

Wyszukiwania miejsc

Usługa Places umożliwia wykonywanie tych rodzajów wyszukiwania:

Zwracane informacje mogą obejmować placówki, takie jak restauracje, sklepy i biura, a także wyniki „kodowania geograficznego”, które wskazują adresy, obszary polityczne, takie jak miasta, i inne ciekawe miejsca.

Żądania Find Place (starsza wersja)

Żądanie Find Place umożliwia wyszukiwanie miejsca za pomocą zapytania tekstowego lub numeru telefonu. Istnieją 2 rodzaje żądań Find Place:

Znajdź miejsce na podstawie zapytania

Usługa Find Place from Query przyjmuje dane wejściowe w postaci tekstu i zwraca miejsce. Dane wejściowe mogą być dowolnymi danymi o miejscu, np. nazwą lub adresem firmy. Aby wysłać żądanie Find Place from Query, wywołaj metodę findPlaceFromQuery() interfejsu PlacesService, która przyjmuje te parametry:

  • query (wymagany) Ciąg tekstowy, który ma zostać wyszukany, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria placówek. Inne typy danych wejściowych mogą powodować błędy i nie gwarantują prawidłowych wyników. Interfejs Places API zwróci potencjalne dopasowania na podstawie tego ciągu znaków i uporządkuje wyniki według ich trafności.
  • fields (wymagane) Co najmniej 1 pole określające typy danych o miejscu, które mają zostać zwrócone.
  • locationBias (opcjonalnie) Współrzędne określające obszar wyszukiwania. Może to być:
    • Zestaw współrzędnych szerokości i długości geograficznej określonych jako LatLngLiteral lub obiekt LatLng.
    • prostokątne granice (2 pary współrzędnych szer./dł. geogr. lub obiekt LatLngBounds),
    • Promień (w metrach) wokół współrzędnych szerokości i długości geograficznej

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 wywołanie findPlaceFromQuery(), które wyszukuje „Museum of Contemporary Art Australia” i uwzględnia pola 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

Znajdowanie miejsca na podstawie numeru telefonu

Funkcja Znajdź miejsce na podstawie numeru telefonu pobiera numer telefonu i zwraca miejsce. Aby wysłać żądanie Find Place from Phone Number, wywołaj metodę findPlaceFromPhoneNumber() interfejsu PlacesService, która przyjmuje te parametry:

  • phoneNumber (wymagany) Numer telefonu w formacie E.164.
  • fields (wymagane) Co najmniej 1 pole określające typy danych o miejscu, które mają zostać zwrócone.
  • locationBias (opcjonalnie) Współrzędne określające obszar wyszukiwania. Może to być:
    • Zestaw współrzędnych szerokości i długości geograficznej określonych jako obiekt LatLngLiteral lub LatLng.
    • prostokątne granice (4 punkty szerokości/długości geograficznej lub obiekt LatLngBounds),
    • Promień (w metrach) wokół współrzędnych szerokości i długości geograficznej

Musisz też przekazać metodę wywołania zwrotnego do findPlaceFromPhoneNumber(), aby obsłużyć obiekt wyników i odpowiedź google.maps.places.PlacesServiceStatus.

Fields (metody Find Place)

Użyj parametru fields, aby określić tablicę typów danych o miejscu, które mają zostać zwrócone. Na przykład: fields: ['formatted_address', 'opening_hours', 'geometry']. Podczas określania wartości złożonych używaj kropki. Przykład: opening_hours.weekday_text.

Pola odpowiadają wynikom wyszukiwania miejsc i są podzielone na 3 kategorie rozliczeniowe: podstawowe, kontaktowe i atmosfera. Pola podstawowe są rozliczane według stawki podstawowej i nie wiążą się z dodatkowymi opłatami. Pola Kontakt i Atmosfera są rozliczane według wyższej stawki. Więcej informacji znajdziesz w cenniku. Atrybucje (html_attributions) są zawsze zwracane przy każdym wywołaniu, niezależnie od tego, czy pole zostało zażądane.

Podstawowe

Kategoria Podstawowe 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 to pole: opening_hours
(wycofane w bibliotece Miejsc, Maps JavaScript API. Użyj żądania informacji o miejscu, aby uzyskać wyniki opening_hours).

Atmosfera

Kategoria Atmosfera obejmuje te pola: price_level, rating, user_ratings_total

Metody findPlaceFromQuery() i findPlaceFromPhoneNumber() przyjmują ten sam zestaw pól i mogą zwracać te same pola w odpowiedziach.

Ustawianie ukierunkowania na lokalizację (metody Find Place)

Użyj parametru locationBias, aby usługa Find Place faworyzowała wyniki z określonego obszaru. Możesz ustawić locationBias na te sposoby:

Filtrowanie wyników pod kątem konkretnego obszaru:

locationBias: {lat: 37.402105, lng: -122.081974}

Zdefiniuj prostokątny obszar wyszukiwania:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Możesz też użyć obiektu LatLngBounds.

Zdefiniuj promień wyszukiwania (w metrach) wokół określonego obszaru:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Żądania 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 obejmować lokalizację, którą można określić na 2 sposoby:

  • LatLngBounds.
  • obszar kołowy zdefiniowany jako połączenie właściwości location, która określa środek koła jako obiekt LatLng, oraz promienia mierzonego w metrach.

Wyszukiwanie miejsc w pobliżu jest inicjowane przez wywołanie metody nearbySearch() obiektu PlacesService, która zwraca tablicę obiektów PlaceResult. Pamiętaj, że od wersji 3.9 metoda nearbySearch() zastępuje metodę search().

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Ta metoda przyjmuje żądanie z tymi polami:

  • Może to być:
    • bounds, który musi być obiektem google.maps.LatLngBounds definiującym prostokątny obszar wyszukiwania. Maksymalna obsługiwana odległość po przekątnej dla obszaru granic wynosi około 100 000 metrów.
    • location i radius. Pierwsza z nich przyjmuje obiekt google.maps.LatLng, a druga – prostą liczbę całkowitą, która reprezentuje promień okręgu w metrach. Maksymalny dozwolony promień to 50 000 metrów. Pamiętaj, że gdy parametr rankBy jest ustawiony na DISTANCE, musisz określić parametr location, ale nie możesz określić parametrów radius ani bounds.
  • keyword (opcjonalny) – hasło, które ma być dopasowane do wszystkich dostępnych pól, w tym m.in. nazwy, typu i adresu, a także opinii klientów i innych treści osób trzecich.
  • minPriceLevel i maxPriceLevel (opcjonalnie) – ogranicza wyniki tylko do miejsc w określonym zakresie. Prawidłowe wartości mieszczą się w zakresie od 0 (najtańsze) do 4 (najdroższe).
  • name Wycofano. Odpowiednik: keyword. Wartości w tym polu są łączone z wartościami w polu keyword i przekazywane jako część tego samego ciągu wyszukiwania.
  • openNow (opcjonalny) – wartość logiczna wskazująca, że usługa Places powinna zwracać tylko te miejsca, które są otwarte w momencie wysłania zapytania. Miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google, nie zostaną zwrócone, jeśli uwzględnisz ten parametr w zapytaniu. Ustawienie openNow na false nie ma żadnego efektu.
  • rankBy (opcjonalny) – określa kolejność, w jakiej wyświetlane są wyniki. Możliwe wartości:
    • google.maps.places.RankBy.PROMINENCE (domyślnie). Ta opcja sortuje wyniki na podstawie ich ważności. Ranking będzie faworyzować znane miejsca w ustawionym promieniu, a nie miejsca w pobliżu, które pasują do zapytania, ale są mniej znane. Na widoczność może wpływać pozycja miejsca w indeksie Google, globalna popularność i inne czynniki. Jeśli określono google.maps.places.RankBy.PROMINENCE, wymagany jest parametr radius.
    • google.maps.places.RankBy.DISTANCE. Ta opcja sortuje wyniki w kolejności rosnącej według odległości od określonego parametru location (wymagane). Pamiętaj, że nie możesz określić niestandardowych wartości bounds ani radius, jeśli podasz RankBy.DISTANCE. Jeśli podasz RankBy.DISTANCE, musisz też podać co najmniej jedną z tych wartości: keyword, name lub type.
  • type – ogranicza wyniki do miejsc pasujących do określonego typu. Można określić tylko jeden typ (jeśli podano więcej niż jeden, wszystkie typy po pierwszym wpisie są 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 tekstu

Usługa wyszukiwania tekstu w Miejscach Google to usługa internetowa, która zwraca informacje o zbiorze miejsc na podstawie ciągu znaków, np. „pizza w Nowym Jorku” lub „sklepy obuwnicze w pobliżu Ottawy”. Usługa odpowiada listą miejsc pasujących do ciągu tekstowego i ustawionych preferencji lokalizacji. Odpowiedź na wyszukiwanie będzie zawierać listę miejsc. Możesz wysłać żądanie informacji o miejscu, aby uzyskać więcej informacji o dowolnym miejscu w odpowiedzi.

Wyszukiwanie tekstowe jest inicjowane przez wywołanie metody textSearch() obiektu PlacesService.

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Ta metoda przyjmuje żądanie z tymi polami:

  • query (wymagany) Ciąg tekstowy, który ma zostać wyszukany, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria placówek. Inne typy danych wejściowych mogą powodować błędy i nie gwarantują prawidłowych wyników. Usługa Places zwróci dopasowania na podstawie tego ciągu znaków i uporządkuje wyniki według 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 Places powinna zwracać tylko te miejsca, które są otwarte w momencie wysłania zapytania. Miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google, nie zostaną zwrócone, jeśli uwzględnisz ten parametr w zapytaniu. Ustawienie zasady openNow na wartość false nie ma żadnego efektu.
    • minPriceLevel i maxPriceLevel – ogranicza wyniki tylko do miejsc w określonym przedziale cenowym. Prawidłowe wartości mieszczą się w zakresie od 0 (najtańsze) do 4 (najdroższe).
    • Może to być:
      • bounds, który musi być obiektem google.maps.LatLngBounds definiującym prostokątny obszar wyszukiwania. Maksymalna obsługiwana odległość po przekątnej dla obszaru granic wynosi około 100 000 metrów.
      • location i radius – możesz faworyzować wyniki z określonego okręgu, przekazując parametry location i radius. Dzięki temu usługa Miejsca będzie preferować wyświetlanie wyników w tym okręgu. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Lokalizacja przyjmuje obiekt google.maps.LatLng, a promień – prostą liczbę całkowitą, która reprezentuje promień okręgu w metrach. Maksymalny dozwolony promień to 50 000 metrów.
    • type – ogranicza wyniki do miejsc pasujących do określonego typu. Można określić tylko jeden typ (jeśli podano więcej niż jeden typ, wszystkie typy po pierwszym wpisie są 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 wyszukiwarki

Kody stanu

Obiekt odpowiedzi PlacesServiceStatus zawiera stan żądania i może zawierać informacje na potrzeby debugowania, które pomogą Ci ustalić, dlaczego żądanie dotyczące miejsca się nie powiodło. Możliwe wartości stanu:

  • INVALID_REQUEST: ta prośba była nieprawidłowa.
  • OK: odpowiedź zawiera prawidłowy wynik.
  • OVER_QUERY_LIMIT: strona internetowa przekroczyła limit żądań.
  • REQUEST_DENIED: strona internetowa nie może używać usługi PlacesService.
  • UNKNOWN_ERROR: nie udało się przetworzyć żądania PlacesService z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.
  • ZERO_RESULTS: nie znaleziono wyników dla tego żądania.

Wyniki wyszukiwania miejsc

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 status działalności miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jeśli nie ma żadnych danych, business_status nie jest zwracany.
  • formatted_address to ciąg tekstowy zawierający zrozumiały dla człowieka adres tego miejsca. Właściwość formatted_address jest zwracana tylko w przypadku wyszukiwania tekstowego.

    Często jest on taki sam jak adres pocztowy. Pamiętaj, że w niektórych krajach, np. w Wielkiej Brytanii, ze względu na ograniczenia licencyjne nie można rozpowszechniać prawdziwych adresów pocztowych.

    Sformatowany adres składa się logicznie z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer domu), „8th Avenue” (ulica), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które odpowiedź interfejsu API zawiera oprócz sformatowanego pola adresu.

  • geometry: informacje o geometrii miejsca. Obejmuje to:
    • location podaje szerokość i długość geograficzną miejsca.
    • viewport określa preferowany widoczny obszar na mapie podczas wyświetlania tego miejsca.
  • permanently_closed (wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe lub tymczasowo (wartość true). Nie używaj permanently_closed. Zamiast tego użyj business_status, aby uzyskać status działalności firm.
  • plus_code (patrz Open Location Code i plus codes) to zakodowane odniesienie do lokalizacji, pochodzące ze współrzędnych szerokości i długości geograficznej, które reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m na 14 m na równiku) lub mniejszy. Plus codes mogą zastępować adresy ulic w miejscach, gdzie ich nie ma (gdzie budynki nie są ponumerowane lub ulice nie mają nazw).

    Plus Code jest sformatowany jako kod globalny i kod złożony:

    • global_code to 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9).
    • compound_code to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
    Zwykle zwracane są zarówno kody globalne, jak i kody złożone. Jeśli jednak wynik znajduje się w odległej lokalizacji (np. na oceanie lub pustyni), może zostać zwrócony tylko kod globalny.
  • html_attributions: tablica atrybucji, które należy wyświetlać podczas wyświetlania wyników wyszukiwania. Każdy wpis w tablicy zawiera tekst HTML pojedynczego atrybutu. Uwaga: jest to agregacja wszystkich atrybucji dla całej odpowiedzi wyszukiwania. Wszystkie obiekty PlaceResult 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, bez rozszerzenia .svg lub .png.
  • icon_background_color zwraca domyślny szesnastkowy kod koloru dla kategorii miejsca.
  • name: nazwa miejsca.
  • opening_hours może zawierać te informacje:
    • open_now to wartość logiczna wskazująca, czy miejsce jest obecnie otwarte (wycofane w bibliotece Miejsc, 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 odwoływaniu się do miejsca za pomocą identyfikatora miejsca.
  • rating zawiera ocenę miejsca od 0, 0 do 5, 0 na podstawie zbiorczych 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ą zostać wprowadzone bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.
  • vicinity: uproszczony adres miejsca, w tym nazwa ulicy, numer domu i miejscowość, ale bez województwa/stanu, kodu pocztowego i kraju. Na przykład biuro Google w Sydney w Australii ma wartość vicinity równą 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ć do 60 wyników podzielonych na 3 strony. Dodatkowe strony są dostępne za pomocą obiektu PlaceSearchPagination. Aby uzyskać dostęp do dodatkowych stron, musisz przechwycić obiekt PlaceSearchPagination za pomocą funkcji wywołania zwrotnego. Obiekt PlaceSearchPagination jest zdefiniowany w ten sposób:

  • hasNextPage – właściwość logiczna, która wskazuje, czy dostępne są kolejne wyniki. true, gdy dostępna jest dodatkowa strona wyników.
  • nextPage() – funkcja, która zwraca następny zestaw wyników. Po przeprowadzeniu wyszukiwania musisz odczekać 2 sekundy, zanim będzie dostępna następna strona wyników.

Aby zobaczyć następny zestaw wyników, wywołaj nextPage. Każda strona wyników musi zostać wyświetlona przed wyświetleniem następnej strony wyników. Pamiętaj, że każde wyszukiwanie jest liczone jako pojedyncze żądanie w ramach limitów wykorzystania.

W przykładzie poniżej pokazujemy, jak zmodyfikować funkcję wywołania zwrotnego, aby przechwytywać obiekt PlaceSearchPagination, co pozwoli Ci 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;
Zobacz przykład

Place Details

Oprócz listy miejsc na danym obszarze usługa Places może też zwracać szczegółowe informacje o konkretnym miejscu. Gdy miejsce zostanie zwrócone w odpowiedzi na wyszukiwanie miejsc, jego identyfikator miejsca może posłużyć do uzyskania dodatkowych informacji o tym miejscu, takich jak pełny adres, numer telefonu, ocena użytkowników i opinie, itp.

Żądania dotyczące informacji o miejscu

Informacje o miejscu są pobierane przez wywołanie metody getDetails() usługi.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Ta metoda przyjmuje żądanie zawierające placeId miejsca oraz pola wskazujące, które typy danych o miejscach mają zostać zwrócone. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.

Wymaga też metody 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);
  }
}

Zobacz przykład

Fields (Place details)

Parametr fields przyjmuje tablicę ciągów znaków (nazw pól).

Użyj parametru fields, aby określić tablicę typów danych o miejscu, które mają zostać zwrócone. Na przykład: fields: ['address_components', 'opening_hours', 'geometry']. Podczas określania wartości złożonych używaj kropki. Przykład: opening_hours.weekday_text.

Pola odpowiadają wynikom informacji o miejscu i są podzielone na 3 kategorie rozliczeniowe: Podstawowe, Kontakt i Atmosfera. Pola podstawowe są rozliczane według stawki podstawowej i nie wiążą się z dodatkowymi opłatami. Pola Kontakt i Atmosfera są rozliczane według wyższej stawki. Więcej informacji znajdziesz w cenniku. Atrybucje (html_attributions) są zawsze zwracane przy każdym wywołaniu, niezależnie od tego, czy zostały zażądane.

Podstawowe

Kategoria Basic obejmuje te 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 (wycofane w bibliotece Miejsc, Maps JavaScript API), utc_offset_minutes, vicinity

Kontakt

Kategoria Kontakt obejmuje te pola:
formatted_phone_number, international_phone_number, opening_hours, website

Atmosfera

Kategoria Atmosfera obejmuje te pola: price_level, rating, reviews, user_ratings_total

Dowiedz się więcej o polach miejsc. Więcej informacji o tym, jak rozliczane są żądania danych o miejscach, znajdziesz w artykule Użycie i rozliczenia.

Odpowiedzi na zapytania o informacje o miejscu

Kody stanu

Obiekt odpowiedzi PlacesServiceStatus zawiera stan żądania i może zawierać informacje na potrzeby debugowania, które pomogą Ci ustalić, dlaczego żądanie informacji o miejscu się nie powiodło. Możliwe wartości stanu:

  • INVALID_REQUEST: ta prośba była nieprawidłowa.
  • OK: odpowiedź zawiera prawidłowy wynik.
  • OVER_QUERY_LIMIT: strona internetowa przekroczyła limit żądań.
  • NOT_FOUND Nie znaleziono wskazanej lokalizacji w bazie danych Miejsc.
  • REQUEST_DENIED: strona internetowa nie może używać usługi PlacesService.
  • UNKNOWN_ERROR: nie udało się przetworzyć żądania PlacesService z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.
  • ZERO_RESULTS: nie znaleziono wyników dla tego żądania.

Wyniki dotyczące informacji o miejscu

Udane wywołanie getDetails() zwraca obiekt PlaceResult z tymi właściwościami:

  • address_components: tablica zawierająca osobne komponenty dotyczące tego adresu.

    Każdy komponent adresu zawiera zwykle te pola:

    • types[] to tablica wskazująca typ komponentu adresu. Jeśli nie ma znanych typów dla danego komponentu adresu, tablica typów może być pusta. W razie potrzeby interfejs API może dodawać nowe wartości typu. Więcej informacji znajdziesz w sekcji Typy adresów i typy komponentów adresów.
    • long_name to pełny opis tekstowy lub nazwa komponentu adresu zwracanego przez geokoder.
    • short_name to skrócona nazwa tekstowa komponentu adresu, jeśli jest dostępna. Na przykład komponent adresu dla stanu Alaska może mieć wartość long_name „Alaska” i short_name „AK” (dwuliterowy skrót pocztowy).

    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 zawierać wszystkich jednostek politycznych, które zawierają adres, oprócz tych, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj odwrotnego geokodowania, przekazując szerokość i długość geograficzną adresu jako parametr żądania.
    • Nie ma gwarancji, że format odpowiedzi będzie taki sam w przypadku różnych żądań. W szczególności liczba 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 zmienić pozycję w tablicy. Typ komponentu może się zmienić. W późniejszej odpowiedzi może brakować określonego komponentu.
  • business_status wskazuje status działalności miejsca, jeśli jest to firma. Może zawierać jedną z tych wartości:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jeśli nie ma żadnych danych, business_status nie jest zwracany.
  • formatted_address: zrozumiały dla człowieka adres tego miejsca.

    Często jest on taki sam jak adres pocztowy. Pamiętaj, że w niektórych krajach, np. w Wielkiej Brytanii, ze względu na ograniczenia licencyjne nie można rozpowszechniać prawdziwych adresów pocztowych.

    Sformatowany adres składa się logicznie z co najmniej 1 komponentu adresu. Na przykład adres „111 8th Avenue, New York, NY” składa się z tych komponentów: „111” (numer domu), „8th Avenue” (ulica), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu automatycznie. Zamiast tego użyj poszczególnych komponentów adresu, które odpowiedź interfejsu API zawiera oprócz sformatowanego pola adresu.

  • formatted_phone_number: numer telefonu miejsca sformatowany zgodnie z  regionalną konwencją numeracji.
  • geometry: informacje o geometrii miejsca. Obejmuje to:
    • location podaje szerokość i długość geograficzną miejsca.
    • viewport określa preferowany widoczny obszar na mapie podczas wyświetlania tego miejsca.
  • permanently_closed (wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe lub tymczasowo (wartość true). Nie używaj permanently_closed. Zamiast tego użyj business_status, aby uzyskać status działalności firm.
  • plus_code (patrz Open Location Code i plus codes) to zakodowane odniesienie do lokalizacji, pochodzące ze współrzędnych szerokości i długości geograficznej, które reprezentuje obszar: 1/8000 stopnia na 1/8000 stopnia (około 14 m na 14 m na równiku) lub mniejszy. Plus codes mogą zastępować adresy ulic w miejscach, gdzie ich nie ma (gdzie budynki nie są ponumerowane lub ulice nie mają nazw).

    Plus Code jest sformatowany jako kod globalny i kod złożony:

    • global_code to 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9).
    • compound_code to co najmniej 6-znakowy kod lokalny z wyraźną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści automatycznie.
    Zwykle zwracane są zarówno kody globalne, jak i kody złożone. Jeśli jednak wynik znajduje się w odległej lokalizacji (np. na oceanie lub pustyni), może zostać zwrócony tylko kod globalny.
  • html_attributions: tekst informacji o pochodzeniu danych, który ma być wyświetlany w przypadku tego wyniku dotyczącego miejsca.
  • icon: URL zasobu obrazu, który może być używany do reprezentowania typu tego miejsca.
  • international_phone_number zawiera numer telefonu miejsca w formacie międzynarodowym. Format międzynarodowy zawiera kod kraju i jest poprzedzony znakiem plusa (+). Na przykład international_phone_number biura Google w Sydney w Australii to +61 2 9374 4000.
  • name: nazwa miejsca.
  • utc_offset Wycofane w bibliotece Miejsc, Maps JavaScript API, użyj zamiast tego utc_offset_minutes.
  • utc_offset_minutes zawiera liczbę minut, o którą bieżąca strefa czasowa tego miejsca różni się od czasu UTC. Na przykład w przypadku miejsc w Sydney w Australii w czasie letnim będzie to 660 (+11 godzin od UTC), a w przypadku miejsc w Kalifornii poza czasem letnim będzie to -480 (-8 godzin od UTC).
  • opening_hours zawiera te informacje:
    • open_now (wycofane w bibliotece Miejsc, Maps JavaScript API; zamiast tego użyj opening_hours.isOpen(). Aby dowiedzieć się, jak używać parametru isOpen z informacjami o miejscu, obejrzyj film Jak uzyskać godziny otwarcia w interfejsie Places API (starsza wersja). `open_now` to wartość logiczna wskazująca, czy miejsce jest obecnie otwarte.
    • periods[] to tablica okresów otwarcia obejmująca 7 dni, zaczynając od niedzieli, w porządku chronologicznym. Każdy okres zawiera:
      • open zawiera parę obiektów z dniem i godziną, które opisują, kiedy miejsce jest otwierane:
        • day – liczba od 0 do 6 odpowiadająca dniom tygodnia, zaczynając od niedzieli. Na przykład 2 oznacza wtorek.
        • time może zawierać godzinę w formacie 24-godzinnym ggmm (wartości z zakresu 0000–2359). time będzie podawany w strefie czasowej miejsca.
      • close może zawierać parę obiektów dnia i godziny opisujących, kiedy miejsce jest zamykane. Uwaga: jeśli miejsce jest zawsze otwarte, w odpowiedzi nie będzie sekcji close. Aplikacje mogą polegać na tym, że zawsze otwarte jest reprezentowane jako okres open zawierający day z wartością 0 i time z wartością 0000 oraz bez close.
    • weekday_text to tablica 7 ciągów znaków reprezentujących sformatowane godziny otwarcia w poszczególne dni tygodnia. Jeśli w żądaniu informacji o miejscu podano parametr language, usługa Places sformatuje i zlokalizuje godziny otwarcia odpowiednio do tego języka. Kolejność elementów w tej tablicy zależy od parametru language. W niektórych językach tydzień zaczyna się w poniedziałek, a w innych w niedzielę.
  • permanently_closed (wycofane) to flaga wartości logicznej, która określa, czy miejsce zostało zamknięte na stałe lub tymczasowo (wartość true). Nie używaj permanently_closed. Zamiast tego użyj business_status, aby uzyskać status działalności firm.
  • photos[]: tablica obiektów PlacePhoto. Możesz użyć PlacePhoto, aby uzyskać zdjęcie za pomocą metody getUrl(), lub sprawdzić obiekt pod kątem tych wartości:
    • height: maksymalna wysokość obrazu w pikselach.
    • width: maksymalna szerokość obrazu w pikselach.
    • html_attributions: tekst informacji o pochodzeniu danych, który ma być wyświetlany ze 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 informacji o miejscu. Dowiedz się więcej o odwoływaniu się do miejsca za pomocą identyfikatora miejsca.
  • rating: ocena miejsca od 0, 0 do 5, 0 na podstawie zbiorczych opinii użytkowników.
  • reviews – tablica zawierająca maksymalnie 5 opinii. 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 placówki. Pierwszy obiekt w tablicy jest uważany za aspekt podstawowy. Każdy PlaceAspectRating jest zdefiniowany jako:
      • type – nazwa ocenianego aspektu. Obsługiwane są te typy: appeal, atmosphere, decor, facilities, food, overall, quality i service.
      • rating – ocena użytkownika dotycząca tego konkretnego aspektu, od 0 do 3.
    • author_name – nazwa użytkownika, który przesłał opinię. Anonimowe opinie są przypisywane do „Użytkownika Google”. Jeśli parametr języka został ustawiony, wyrażenie „Użytkownik Google” zwróci zlokalizowany ciąg znaków.
    • author_url – adres URL profilu Google+ użytkownika, jeśli jest dostępny.
    • language – kod języka IETF wskazujący język użyty w opinii użytkownika. To pole zawiera tylko główny tag języka, a nie tag dodatkowy wskazujący kraj lub region. Na przykład wszystkie opinie w języku angielskim są oznaczone tagiem „en”, a nie „en-AU” czy „en-UK”.
    • rating – ogólna ocena tego miejsca wystawiona przez użytkownika. Jest to liczba całkowita z zakresu od 1 do 5.
    • text opinię użytkownika. Podczas oceniania lokalizacji w Miejscach Google opinie tekstowe są traktowane jako 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ą zostać wprowadzone bez wcześniejszego powiadomienia. Zobacz listę obsługiwanych typów.
  • url: URL oficjalnej strony Google tego miejsca. Jest to strona należąca do Google, która zawiera najlepsze dostępne informacje o miejscu. Aplikacje muszą zawierać link do tej strony lub umieszczać ją na każdym ekranie, na którym użytkownik widzi szczegółowe wyniki dotyczące miejsca.
  • vicinity: uproszczony adres miejsca, w tym nazwa ulicy, numer domu i miejscowość, ale bez województwa/stanu, kodu pocztowego i kraju. Na przykład biuro Google w Sydney w Australii ma wartość vicinity równą 5/48 Pirrama Road, Pyrmont. Właściwość vicinity jest zwracana tylko w przypadku wyszukiwania w pobliżu.
  • website zawiera adres wiarygodnej witryny tego miejsca, np. strony głównej firmy.

Uwaga: oceny wielowymiarowe mogą nie być dostępne we wszystkich lokalizacjach. Jeśli opinii jest zbyt mało, odpowiedź ze szczegółami będzie zawierać starszą ocenę w skali od 0,0 do 5,0 (jeśli jest dostępna) lub nie będzie zawierać żadnej oceny.

Odwoływanie się do miejsca za pomocą identyfikatora miejsca

Identyfikator miejsca to niepowtarzalny identyfikator miejsca w 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żyć identyfikatora miejsca w aplikacji, musisz go najpierw wyszukać. Jest on dostępny w PlaceResult żądania wyszukiwania miejsca lub żądania szczegółów. Możesz użyć tego identyfikatora miejsca, aby wyszukać informacje o miejscu.

Identyfikatory miejsc są wyłączone z ograniczeń dotyczących buforowania określonych w sekcji 3.2.3(b) Warunków korzystania z usługi Google Maps Platform. Dlatego możesz przechowywać wartości identyfikatorów miejsc do późniejszego wykorzystania. 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);

Place Photos

Użyj funkcji Zdjęcie miejsca, aby dodać do witryny wysokiej jakości treści fotograficzne. Usługa Photo daje dostęp do milionów zdjęć przechowywanych w bazie danych Miejsc i Lokalnych stron Google+. Gdy uzyskasz informacje o miejscu za pomocą żądania szczegółów miejsca, w przypadku odpowiednich treści fotograficznych zostaną zwrócone odwołania do zdjęć. Żądania wyszukiwania w pobliżu i wyszukiwania tekstowego zwracają też w odpowiednich przypadkach pojedyncze odwołanie do zdjęcia dla każdego miejsca. Korzystając z usługi Photo, możesz uzyskać dostęp do zdjęć, do których odwołują się te odnośniki, i zmienić ich rozmiar na optymalny dla Twojej 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 zwracanych zdjęć różni się w zależności od żądania.

  • Wyszukiwanie w pobliżu lub wyszukiwanie tekstowe zwraca maksymalnie 1 obiekt PlacePhoto.
  • Żądanie szczegółów zwraca maksymalnie 10 obiektów PlacePhoto.

Możesz poprosić o adres URL powiązanego obrazu, wywołując metodę PlacePhoto.getUrl() i przekazując prawidłowy obiekt PhotoOptions. Użyj obiektu PhotoOptions, aby określić maksymalną wysokość i szerokość obrazu. Jeśli określisz wartość zarówno dla maxHeight, jak i maxWidth, usługa zdjęć zmieni rozmiar obrazu na mniejszy z tych 2 rozmiarów, zachowując oryginalny współczynnik proporcji.

Poniższy fragment kodu akceptuje obiekt miejsca i dodaje znacznik do mapy, jeśli istnieje zdjęcie. Domyślny obraz znacznika zostanie zastąpiony 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ęć pochodzą z różnych źródeł, w tym od właścicieli firm i użytkowników. W większości przypadków można ich używać bez podawania źródła lub wymagane źródło jest już podane na obrazie. Jeśli jednak zwrócony element photo zawiera wartość w polu html_attributions, musisz dodać dodatkowe informacje o autorze w aplikacji wszędzie tam, gdzie wyświetlasz obraz.