biblioteka Miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Przegląd

Funkcje w bibliotece Miejsc w interfejsie Maps JavaScript API umożliwiają aplikacji wyszukiwanie miejsc (zdefiniowanych w tym interfejsie API jako obiekty, lokalizacje geograficzne lub ważne ciekawe miejsca) znajdujących się na określonym obszarze, np. w granicach mapy lub wokół stałego punktu.

Interfejs Places API oferuje funkcję autouzupełniania, której możesz używać, aby zapewnić aplikacjom działanie wyszukiwania z wyprzedzeniem, podobne do pola wyszukiwania w Mapach Google. Gdy użytkownik zacznie wpisywać adres, funkcja automatycznego uzupełniania 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 pracy zapoznaj się z informacjami o JavaScript i uzyskiwaniu klucza interfejsu API.

Wczytaj bibliotekę

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

<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 interfejsu Places API do listy ograniczeń interfejsów API klucza interfejsu API

Zastosowanie ograniczeń interfejsu API do kluczy zawęża możliwość wykorzystywania klucza interfejsu API do jednego bądź kilku interfejsów 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 kończą się niepowodzeniem. Aby ograniczyć użycie klucza interfejsu API do biblioteki Miejsc w Maps JavaScript API:
  1. Otwórz konsolę Google Cloud.
  2. Kliknij menu projektu i wybierz projekt, który zawiera 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 i zmień nazwę klucza interfejsu API ustaw ograniczenia:
    • Ograniczenia interfejsów API
      • Kliknij Ogranicz klucz.
      • Kliknij Wybierz interfejsy API i wybierz Maps JavaScript API oraz Places API.
        (Jeśli któregoś z tych interfejsów API nie ma na liście, musisz go włączyć).
  6. Kliknij ZAPISZ.

Limity wykorzystania i zasady

Limity

Biblioteka Miejsc ma wspólny limit wykorzystania z interfejsem Places API, co opisano w dokumentacji limitów wykorzystania interfejsu Places API.

Zasady

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

Wyszukiwanie miejsc

Usługa Miejsca umożliwia przeprowadzanie tych rodzajów wyszukiwania:

Zwracane informacje mogą obejmować obiekty, takie jak restauracje, sklepy i biura, a także wyniki „geokodowania”, które wskazują adresy, obszary polityczne, takie jak miasta i miasteczka, oraz inne punkty orientacyjne.

Żądania Find Place

Żądanie Znajdź miejsce umożliwia wyszukiwanie miejsca na podstawie zapytania tekstowego lub numeru telefonu. Istnieją 2 typy żądań Find Place:

Znajdowanie miejsca na podstawie zapytania

Usługa Find Place from Query przyjmuje tekst jako dane wejściowe i zwraca miejsce. Dane wejściowe mogą być dowolnego rodzaju danymi o miejscu, np. nazwą firmy lub adresem. Aby wysłać żądanie Find Place from Query, wywołaj metodę PlacesServicefindPlaceFromQuery(), która przyjmuje te parametry:

  • query (wymagane) Ciąg tekstowy, w którym ma być przeprowadzone wyszukiwanie, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria placówek. Inne typy danych wejściowych mogą generować błędy i nie gwarantują zwrócenia prawidłowych wyników. Interfejs Places API zwróci pasujące kandydatury 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 miejscach, które mają zostać zwrócone.
  • locationBias (opcjonalnie) Współrzędne określające obszar wyszukiwania. Może to być jedna z tych wartości:
    • Zestaw współrzędnych szerokości i długości geograficznej określony jako LatLngLiteral lub obiekt LatLng.
    • Prostokątne granice (2 pary współrzędnych geograficznych lub obiekt LatLngBounds)
    • Promień (w metrach) wyśrodkowany na szerokości i długości geograficznej

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

Poniższy przykład pokazuje wywołanie funkcji findPlaceFromQuery(), która wyszukuje „Museum of Contemporary Art Australia” i zawiera 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

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

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

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

Pola (metody Find Place)

Użyj parametru fields, aby określić tablicę typów danych o miejscu do zwrócenia. 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: podstawową, kontaktową i atmosfery. Za pola podstawowe naliczana jest stawka podstawowa i nie są pobierane żadne dodatkowe opłaty. Pola Contact i Atmosphere są rozliczane według wyższej stawki. Więcej informacji znajdziesz w arkuszu cen. Atrybucje (html_attributions) są zawsze zwracane w każdym wywołaniu, niezależnie od tego, czy pole zostało wysłane w żądaniu.

Basic

Kategoria Podstawowe obejmuje te pola:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (przestarzałe), photos, place_id, plus_code, types

Kontakt

Kategoria Kontakt zawiera to pole: opening_hours
(wycofane w bibliotece Miejsc w Maps JavaScript API. Użyj prośby o szczegóły miejsca, 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 preferencji lokalizacji (metody Find Place)

Użyj parametru locationBias, aby funkcja Znajdź miejsce preferowała wyniki z określonego obszaru. locationBias możesz ustawić w ten sposób:

Przesuń wyniki w stronę określonego 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ć LatLngBounds.

Określ promień wyszukiwania (w metrach) wyśrodkowany na określonym obszarze:

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

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

Wyszukiwanie miejsc w pobliżu jest inicjowane przez wywołanie metody nearbySearch() interfejsu 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:

  • Jeden z tych warunków:
    • bounds, który musi być obiektem google.maps.LatLngBounds określającym prostokątny obszar wyszukiwania. Maksymalna obsługiwana odległość po przekątnej w przypadku obszaru granic wynosi około 100 tys. metrów.
    • location i radius. Pierwszy z nich przyjmuje obiekt google.maps.LatLng, a drugi prostą liczbę całkowitą reprezentującą promień okręgu w metrach. Maksymalny dozwolony promień to 50 000 metrów. Pamiętaj, że gdy parametr rankBy ma wartość DISTANCE, musisz określić parametr location, ale nie możesz określić parametrów radius ani bounds.
  • keyword (opcjonalny) – termin, który ma być dopasowany do wszystkich dostępnych pól, w tym między innymi nazwy, typu i adresu, a także opinii klientów i innych treści pochodzących od osób trzecich.
  • minPriceLevel i maxPriceLevel (opcjonalnie) – ogranicza wyniki do miejsc w określonym zakresie. Prawidłowe wartości mieszczą się w zakresie od 0 (najtańszy) do 4 (najdroższy) włącznie.
  • name Wycofano. 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 usługa Miejsca 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 będą zwracane, jeśli w zapytaniu uwzględnisz ten parametr. Ustawienie openNow na false nie ma żadnego efektu.
  • rankBy (opcjonalny) – określa kolejność wyświetlania wyników. Możliwe wartości:
    • google.maps.places.RankBy.PROMINENCE (domyślnie). Ta opcja sortuje wyniki według ich ważności. Ranking będzie faworyzować popularne miejsca w określonym promieniu w stosunku do pobliskich miejsc, które pasują do kryteriów, ale są mniej popularne. Na widoczność może wpływać pozycja miejsca w indeksie Google, globalna popularność i inne czynniki. Jeśli określono parametr 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 podanego location (wymagane). Pamiętaj, że jeśli określisz parametr RankBy.DISTANCE, nie możesz podać niestandardowego parametru bounds ani radius. Jeśli podasz wartość RankBy.DISTANCE, musisz podać co najmniej jedną z wartości keyword, name lub type.
  • type – ogranicza wyniki do miejsc pasujących do określonego typu. Można określić tylko 1 typ (jeśli podasz więcej niż 1 typ, wszystkie typy po pierwszym wpisie zostaną zignorowane). Zobacz listę obsługiwanych typów.

Musisz też przekazać metodę wywołania zwrotnego do nearbySearch(), aby obsługiwać 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 w Miejscach Google to usługa internetowa, która zwraca informacje o zbiorze miejsc na podstawie ciągu znaków, np. „pizza w Warszawie” lub „sklepy obuwnicze w pobliżu Krakowa”. Usługa odpowiada listą miejsc pasujących do ciągu tekstowego i wszelkich ustawionych odchyleń lokalizacji. Odpowiedź na wyszukiwanie będzie zawierać listę miejsc. Możesz wysłać żądanie szczegółów miejsca, aby uzyskać więcej informacji o dowolnym miejscu w odpowiedzi.

Wyszukiwanie tekstowe jest inicjowane przez wywołanie metody textSearch() urządzenia PlacesService.

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

Ta metoda przyjmuje żądanie z tymi polami:

  • query (wymagane) Ciąg tekstowy, w którym chcesz wyszukać informacje, np. „restauracja” lub „ul. Główna 123”. Musi to być nazwa miejsca, adres lub kategoria obiektów. Inne typy danych wejściowych mogą generować błędy i nie gwarantują zwrócenia prawidłowych wyników. Usługa Places zwróci pasujące kandydatury 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 jest też używany parametr type.
  • Opcjonalnie:
    • openNow – wartość logiczna wskazująca, że usługa Miejsca 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 będą zwracane, jeśli w zapytaniu uwzględnisz ten parametr. Ustawienie openNow na false nie ma żadnego efektu.
    • minPriceLevel i maxPriceLevel – ogranicza wyniki do miejsc w określonym przedziale cenowym. Prawidłowe wartości to od 0 (najtańszy) do 4 (najdroższy) włącznie.
    • Jeden z tych warunków:
      • bounds, który musi być obiektem google.maps.LatLngBounds określającym prostokątny obszar wyszukiwania. Maksymalna obsługiwana odległość po przekątnej w przypadku obszaru bounds to około 100 tys. metrów.
      • location i radius – możesz zawęzić wyniki do 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. Mogą być wyświetlane wyniki spoza zdefiniowanego obszaru. Lokalizacja przyjmuje obiekt google.maps.LatLng, a promień przyjmuje prostą liczbę całkowitą reprezentującą 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 1 typ (jeśli podasz więcej niż 1 typ, wszystkie typy po pierwszym wpisie zostaną zignorowane). Zobacz listę obsługiwanych typów.

Musisz też przekazać metodę wywołania zwrotnego do textSearch(), aby przetworzyć 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 do debugowania, które pomogą Ci ustalić, dlaczego żądanie dotyczące miejsca nie powiodło się. Możliwe wartości stanu:

  • INVALID_REQUEST: Ta prośba jest nieprawidłowa.
  • OK: odpowiedź zawiera prawidłowy wynik.
  • OVER_QUERY_LIMIT: Strona internetowa przekroczyła limit żądań.
  • REQUEST_DENIED: strona 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, pole business_status nie jest zwracane.
  • formatted_address to ciąg tekstowy zawierający adres tego miejsca w formacie czytelnym dla człowieka. Właściwość formatted_address jest zwracana tylko w przypadku wyszukiwania tekstowego.

    Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, np. Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

    Sformatowany adres logicznie składa się 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 ulicy), „8th Avenue” (trasa), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu programowo. Zamiast tego używaj poszczególnych komponentów adresu, które są uwzględniane w odpowiedzi interfejsu API 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 mapy podczas wyświetlania tego miejsca.
  • permanently_closed (przestarzałe) 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 parametru permanently_closed. Zamiast tego użyj business_status, aby uzyskać stan działalności firm.
  • plus_code (patrz Open Location Code i kody plus) to zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie współrzędnych geograficznych i reprezentuje obszar o wielkości 1/8000 stopnia szerokości i 1/8000 stopnia długości geograficznej (około 14 m × 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastępować adresy w miejscach, w których nie istnieją (gdzie budynki nie mają numerów lub ulice nie mają nazw).

    Kod plus ma format kodu globalnego i kodu złożonego:

    • global_code to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9).
    • compound_code to 6-znakowy lub dłuższy kod lokalny z określoną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści programowo.
    Zwykle zwracany jest zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległym miejscu (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 w całej odpowiedzi na wyszukiwanie. 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 kategorii miejsca.
  • name: nazwa miejsca.
  • opening_hours może zawierać następujące informacje:
  • place_id to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w żądaniu Szczegóły miejsca. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.
  • rating zawiera ocenę miejsca w skali 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, który zawiera nazwę ulicy, numer domu i miejscowość, ale nie zawiera województwa/stanu, kodu pocztowego ani 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 miejsca zwraca do 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ą dalsze wyniki. true gdy jest dostępna dodatkowa strona wyników.
  • nextPage() funkcja, która zwróci następny zestaw wyników. Po przeprowadzeniu wyszukiwania musisz odczekać 2 sekundy, zanim będzie dostępna następna strona wyników.

Aby zobaczyć kolejny 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 i 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;
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

Wypróbuj przykład

Szczegóły miejsc

Usługa Places nie tylko udostępnia listę miejsc w danym obszarze, ale też zwraca szczegółowe informacje o konkretnym miejscu. Gdy w odpowiedzi na wyszukiwanie miejsca pojawi się miejsce, jego identyfikator można wykorzystać do wysłania prośby o dodatkowe informacje na jego temat, takie jak pełny adres, numer telefonu, oceny i opinie użytkowników itp.

Żądania dotyczące informacji o miejscu

Szczegóły miejsca 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 i pola wskazujące, które typy danych Miejsc mają zostać zwrócone. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.

Przyjmuje też metodę wywołania zwrotnego, która musi obsługiwać kod stanu przekazywany w odpowiedzi google.maps.places.PlacesServiceStatus, a także 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 (informacje o miejscu)

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

Użyj parametru fields, aby określić tablicę typów danych o miejscu do zwrócenia. 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, kontaktowe i atmosfera. Za pola podstawowe naliczana jest stawka podstawowa i nie wiążą się one z dodatkowymi opłatami. Pola Kontakt i Atmosfera są rozliczane według wyższej stawki. Więcej informacji znajdziesz w arkuszu cen. Atrybucje (html_attributions) są zawsze zwracane w każdym wywołaniu, niezależnie od tego, czy zostały o nie wysłane żądanie.

Basic

Kategoria Podstawowe 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 w Maps JavaScript API), utc_offset_minutes, vicinity

Kontakt

Kategoria Kontakt zawiera 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 miejsca. Więcej informacji o tym, jak są rozliczane żądania danych o miejscach, znajdziesz w artykule Wykorzystanie i rozliczenia.

Odpowiedzi dotyczące szczegółów miejsca

Kody stanu

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

  • INVALID_REQUEST: Ta prośba jest nieprawidłowa.
  • OK: odpowiedź zawiera prawidłowy wynik.
  • OVER_QUERY_LIMIT: Strona internetowa przekroczyła limit żądań.
  • NOT_FOUND Wskazanej lokalizacji nie znaleziono w bazie danych Miejsc.
  • REQUEST_DENIED: strona 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 informacji o miejscu

Wywołanie getDetails() zakończone powodzeniem zwraca obiekt PlaceResult z tymi właściwościami:

  • address_components: tablica zawierająca poszczególne komponenty, które mają zastosowanie do tego adresu.

    Każdy komponent adresu zawiera zwykle te pola:

    • types[] to tablica wskazująca typ komponentu adresu. Zobacz listę obsługiwanych typów.
    • long_name to pełny tekst opisu lub nazwa komponentu adresu zwrócona 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 wartość short_name „AK” przy użyciu 2-literowego skrótu pocztowego.

    Pamiętaj o tych faktach dotyczących 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, z wyjątkiem tych, które są uwzględnione w formatted_address. Aby pobrać wszystkie jednostki polityczne, które zawierają określony adres, użyj geokodowania zwrotnego, przekazując szerokość i długość geograficzną adresu jako parametr żądania.
    • Format odpowiedzi nie musi być taki sam w przypadku różnych żądań. W szczególności liczba address_components zależy od żądanego adresu i może się zmieniać z czasem w przypadku 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, pole business_status nie jest zwracane.
  • formatted_address: adres tego miejsca czytelny dla człowieka.

    Często jest to odpowiednik adresu pocztowego. Pamiętaj, że niektóre kraje, np. Wielka Brytania, nie zezwalają na rozpowszechnianie prawdziwych adresów pocztowych ze względu na ograniczenia licencyjne.

    Sformatowany adres logicznie składa się 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 ulicy), „8th Avenue” (trasa), „New York” (miasto) i „NY” (stan w USA).

    Nie analizuj sformatowanego adresu programowo. Zamiast tego używaj poszczególnych komponentów adresu, które są uwzględniane w odpowiedzi interfejsu API oprócz sformatowanego pola adresu.

  • formatted_phone_number: numer telefonu miejsca sformatowany zgodnie z  regionalnymi zasadami dotyczącymi numerów.
  • geometry: informacje o geometrii miejsca. Obejmuje to:
    • location podaje szerokość i długość geograficzną miejsca.
    • viewport określa preferowany widoczny obszar mapy podczas wyświetlania tego miejsca.
  • permanently_closed (przestarzałe) 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 parametru permanently_closed. Zamiast tego użyj business_status, aby uzyskać stan działalności firm.
  • plus_code (patrz Open Location Code i kody plus) to zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie współrzędnych geograficznych i reprezentuje obszar o wielkości 1/8000 stopnia szerokości i 1/8000 stopnia długości geograficznej (około 14 m × 14 m na równiku) lub mniejszy. Kody Plus Code mogą zastępować adresy w miejscach, w których nie istnieją (gdzie budynki nie mają numerów lub ulice nie mają nazw).

    Kod plus ma format kodu globalnego i kodu złożonego:

    • global_code to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9).
    • compound_code to 6-znakowy lub dłuższy kod lokalny z określoną lokalizacją (CWC8+R9, Mountain View, CA, USA). Nie analizuj tych treści programowo.
    Zwykle zwracany jest zarówno kod globalny, jak i kod złożony. Jeśli jednak wynik znajduje się w odległym miejscu (np. na oceanie lub pustyni), może zostać zwrócony tylko kod globalny.
  • html_attributions: Tekst źródła, który ma być wyświetlany w przypadku tego wyniku dotyczącego miejsca.
  • icon: adres 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 dla biura Google w Sydney w Australii to +61 2 9374 4000.
  • name: nazwa miejsca.
  • utc_offset Wycofany w bibliotece miejsc w Maps JavaScript API. Zamiast niego używaj utc_offset_minutes.
  • utc_offset_minutes zawiera liczbę minut, o którą obecna strefa czasowa tego miejsca jest przesunięta względem czasu UTC. Na przykład w przypadku miejsc w Sydney w Australii w okresie obowiązywania czasu letniego będzie to 660 minut (+11 godzin od UTC), a w przypadku miejsc w Kalifornii poza okresem obowiązywania czasu letniego będzie to -480 minut (-8 godzin od UTC).
  • opening_hours zawiera te informacje:
    • open_now (Wycofano w bibliotece miejsc w Maps JavaScript API; zamiast tego używaj opening_hours.isOpen()). Informacje o tym, jak używać parametru isOpen ze szczegółami miejsca, znajdziesz w tym filmie. Parametr `open_now` to wartość logiczna wskazująca, czy miejsce jest otwarte w danym momencie.
    • periods[] to tablica okresów otwarcia obejmująca 7 dni, począwszy od niedzieli, w porządku chronologicznym. Każdy okres zawiera:
      • open zawiera parę obiektów dnia i godziny opisujących, kiedy miejsce jest otwarte:
        • day liczba od 0 do 6 odpowiadająca dniom tygodnia, przy czym niedziela to 0. 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 raportowany w strefie czasowej miejsca.
      • close może zawierać parę obiektów dnia i godziny, które opisują, kiedy miejsce jest zamykane. Uwaga: jeśli miejsce jest zawsze otwarte, w odpowiedzi nie będzie sekcji close. Aplikacje mogą zawsze polegać na tym, że wartość „always-open” jest reprezentowana jako open okres zawierający day o wartości 0 i time o wartości 0000 oraz bez close.
    • weekday_text to tablica 7 ciągów znaków reprezentujących sformatowane godziny otwarcia w poszczególnych dniach tygodnia. Jeśli w żądaniu Szczegóły miejsca podano parametr language, usługa Miejsca 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 (przestarzałe) 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 parametru permanently_closed. Zamiast tego użyj business_status, aby uzyskać stan działalności firm.
  • photos[]: tablica obiektów PlacePhoto. Obiektu PlacePhoto można użyć do uzyskania zdjęcia za pomocą metody getUrl() lub możesz sprawdzić, czy obiekt zawiera te wartości:
    • height: maksymalna wysokość obrazu w pikselach.
    • width: maksymalna szerokość obrazu w pikselach.
    • html_attributions: tekst atrybucji, który ma być wyświetlany z tym zdjęciem miejsca.
  • place_id: identyfikator tekstowy, który jednoznacznie identyfikuje miejsce i może być używany do pobierania informacji o nim za pomocą żądania szczegółów miejsca. Dowiedz się więcej o tym, jak odwoływać się do miejsca za pomocą identyfikatora miejsca.
  • rating: ocena miejsca w skali od 0, 0 do 5, 0 na podstawie zbiorczych opinii użytkowników.
  • reviews tablicę zawierającą 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 obiektu. Pierwszy obiekt w tablicy jest uznawany za aspekt podstawowy. Każdy element PlaceAspectRating jest zdefiniowany w ten sposób:
      • type nazwa aspektu, który jest oceniany; Obsługiwane są te typy: appeal,atmosphere, decor,facilities, food, overall,quality i service.
      • rating ocena użytkownika dotycząca tego konkretnego aspektu w skali od 0 do 3.
    • author_name imię i nazwisko użytkownika, który przesłał opinię; Anonimowe opinie są przypisywane do „Użytkownika Google”. Jeśli ustawiono parametr języka, fraza „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 jako „en”, a nie „en-AU” lub „en-UK”.
    • rating ogólną ocenę użytkownika dla tego miejsca. Jest to liczba całkowita z zakresu od 1 do 5.
    • text opinię użytkownika. Podczas sprawdzania lokalizacji w Miejscach Google opinie tekstowe są 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: adres URL oficjalnej strony Google dotyczącej tego miejsca. Jest to strona należąca do Google, która zawiera najlepsze dostępne informacje o danym miejscu. Aplikacje muszą zawierać link do tej strony lub osadzać ją na każdym ekranie, na którym użytkownikowi wyświetlane są szczegółowe wyniki dotyczące miejsca.
  • vicinity: uproszczony adres miejsca, który zawiera nazwę ulicy, numer domu i miejscowość, ale nie zawiera województwa/stanu, kodu pocztowego ani 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 oficjalną witrynę tego miejsca, np. stronę główną firmy.

Uwaga: oceny wielowymiarowe mogą być niedostępne w przypadku niektórych lokalizacji. 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 unikalny odnośnik do miejsca na mapie Google. Identyfikatory miejsc są dostępne w przypadku większości lokalizacji, w tym firm, punktów orientacyjnych, parków i skrzyżowań.

Aby użyć identyfikatora miejsca w aplikacji, musisz najpierw go wyszukać. Jest on dostępny w PlaceResult w przypadku żądania wyszukiwania miejsca lub żądania szczegółów. Następnie możesz użyć tego identyfikatora miejsca, aby wyszukać szczegóły miejsca.

Identyfikatory miejsc nie podlegają ograniczeniom dotyczącym buforowania określonym w artykule 3.2.3(b) Warunków korzystania z usługi Google Maps Platform. Dzięki temu możesz zapisywać 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 Zdjęcia zapewnia dostęp do milionów zdjęć przechowywanych w bazie danych Miejsc i Google+ Lokalnie. Gdy uzyskasz informacje o miejscu za pomocą żądania Szczegóły miejsca, w przypadku odpowiednich treści fotograficznych zostaną zwrócone odwołania do zdjęć. Żądania wyszukiwania w pobliżu i wyszukiwania tekstowego zwracają też 1 odniesienie do zdjęcia na miejsce, jeśli jest to istotne. Korzystając z usługi Zdjęcia, możesz uzyskać dostęp do zdjęć, do których się odwołujesz, i zmienić ich rozmiar na optymalny dla Twojej aplikacji.

Tablica obiektów PlacePhoto zostanie zwrócona w ramach obiektu PlaceResult w przypadku każdego żądania getDetails(), textSearch() lub nearbySearch() wysłanego do PlacesService.

Uwaga: liczba zwróconych zdjęć zależy od żądania.

  • Wyszukiwanie w pobliżu lub wyszukiwanie tekstowe zwraca maksymalnie 1 obiekt.PlacePhoto
  • Żądanie szczegółów zwróci 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 dwóch rozmiarów, zachowując oryginalny współczynnik proporcji.

Poniższy fragment kodu akceptuje obiekt miejsca i dodaje do mapy znacznik, 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ęcia pochodzą z różnych lokalizacji, w tym od właścicieli firm i użytkowników. W większości przypadków można ich używać bez podawania atrybucji lub z wymaganą atrybucją jako częścią obrazu. 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.