libreria Places

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Panoramica

Le funzioni nella libreria Places, nell'API Maps JavaScript consentono la tua applicazione per cercare luoghi (definiti in questa API come stabilimenti, località o punti di interesse di rilievo) contenuti in un'area definita, come i confini di una mappa o intorno a un punto fisso.

L'API Places offre una funzione di completamento automatico che puoi utilizzare per dare alle tue applicazioni il comportamento type-ahead-search di Google Maps campo di ricerca. Quando un utente inizia a digitare un indirizzo, il completamento automatico e riempi il resto. Per ulteriori informazioni, consulta completamento automatico documentazione.

Per iniziare

Se non hai dimestichezza con l'API Maps JavaScript o con JavaScript, ti consigliamo di consultare Ottenere una chiave API prima per iniziare.

Abilita API

Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata nella console Google Cloud, nella stessa configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla sezione Console Google Cloud.
  2. Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai configurato. per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API sulla Dashboard, cerca API Places.
  4. Se nell'elenco vedi l'API Places, significa che è già abilitata. Se l'API non è elencato, abilitalo:
    1. Nella parte superiore della pagina, seleziona ABILITA API E SERVIZI per visualizzare i campi Scheda Raccolta. In alternativa, dal menu laterale a sinistra, Seleziona Libreria.
    2. Cerca API Places e selezionala dalla dei risultati di ricerca.
    3. Seleziona ABILITA. Al termine del processo, L'API Places viene visualizzata nell'elenco delle API nella Dashboard.

Caricamento della libreria in corso...

Il servizio Places è una libreria indipendente, separata dalla piattaforma Codice dell'API Maps JavaScript. Per utilizzare la funzionalità contenuta all'interno di questa libreria, devi prima caricarla utilizzando l'libraries nell'URL del bootstrap dell'API di Google Maps:

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

Consulta Panoramica delle librerie.

Aggiungi l'API Places all'elenco delle limitazioni API della chiave API

L'applicazione di restrizioni API alle chiavi limita l'utilizzo della chiave API a uno o più API o SDK. Le richieste a un'API o a un SDK associati alla chiave API essere elaborati. Le richieste a un'API o a un SDK non associati alla chiave API non riuscito. Per limitare l'utilizzo di una chiave API con Places Library, l'API Maps JavaScript:
  1. Vai alla console Google Cloud.
  2. Fai clic sul menu a discesa del progetto e seleziona il progetto che contiene Chiave API che vuoi proteggere.
  3. Fai clic sul pulsante di menu e seleziona Google Maps Platform > Credenziali.
  4. Nella pagina Credenziali, fai clic sul nome dell'API chiave che vuoi proteggere.
  5. Nella pagina Limita e rinomina la chiave API, imposta le limitazioni:
    • Restrizioni delle API
      • Seleziona Limita chiave.
      • Fai clic su Seleziona API e seleziona sia l'API Maps JavaScript sia l'API Places.
        Se una delle API non è presente nell'elenco, devi abilitarla.
  6. Fai clic su SALVA.

Limiti e norme di utilizzo

Quote

La libreria di Places condivide una quota di utilizzo con API Places come descritto nella documentazione sui limiti di utilizzo per API Places.

Norme

L'utilizzo dell'API Places Library, Maps JavaScript deve essere conforme ai norme descritte per l'API Places.

Ricerche di luoghi

Con il servizio Places puoi effettuare i seguenti tipi di ricerche:

Le informazioni restituite possono includere attività, ad esempio ristoranti, negozi e uffici, nonché il 'codici geografici' di risultati, che indicare indirizzi, aree politiche come città e altri punti d'interesse.

Richieste Trova luogo

Una richiesta Trova luogo ti consente di cercare un luogo tramite query di testo o numero di telefono. Esistono due tipi di richiesta Trova luogo:

Trova luogo dalla query

Trova luogo dalla query richiede un input di testo e restituisce un luogo. L'input può essere qualsiasi tipo di dati dei luoghi, ad esempio il nome o l'indirizzo di un'attività commerciale. Per creare un Trova luogo dalla richiesta Query, chiama il PlacesService findPlaceFromQuery() , che accetta i seguenti parametri:

  • query (obbligatorio) La stringa di testo in cui eseguire la ricerca, esempio: "ristorante" o "Via Cavour 123". Deve essere il nome di un luogo, l'indirizzo o la categoria di attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituiscano risultati validi. API Places restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla percezione della loro pertinenza.
  • fields (obbligatorio) Uno o più campi che specifica i tipi di dati dei luoghi da restituire.
  • locationBias (Facoltativo) Coordinate che definiscono l'area da cercare. Può essere uno dei seguenti:

Devi anche passare un metodo di callback a findPlaceFromQuery(), per gestire l'oggetto dei risultati e google.maps.places.PlacesServiceStatus risposta.

L'esempio seguente mostra una chiamata a findPlaceFromQuery(), ha cercato "Museum of Contemporaneo Art Australia" e ha incluso name e 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);
    }
  });
}
Visualizza esempio

Trova luogo dal numero di telefono

Trova luogo da numero di telefono prende un numero di telefono e restituisce un luogo. A per effettuare una richiesta Trova luogo dal numero di telefono, chiama findPlaceFromPhoneNumber() di PlacesService , che accetta i seguenti parametri:

  • phoneNumber (obbligatorio) Un numero di telefono nel formato E.164.
  • fields (obbligatorio) Uno o più campi che specifica i tipi di dati dei luoghi da restituire.
  • (Facoltativo) locationBias Coordinate che definiscono l'area da eseguire una ricerca. I valori possono essere:
    • Un insieme di coordinate di latitudine/longitudine specificate come LatLngLiteral o oggetto LatLng
    • Limiti rettangolari (quattro punti latitudine/longitudine oppure un oggetto LatLngBounds)
    • Raggio (in metri) centrato su latitudine/longitudine

Devi anche passare un metodo di callback a findPlaceFromPhoneNumber(), per gestire l'oggetto dei risultati e google.maps.places.PlacesServiceStatus risposta.

Campi (metodi Trova luogo)

Utilizza il parametro fields per specificare un array di tipi di dati dei luoghi da restituire. Ad esempio: fields: ['formatted_address', 'opening_hours', 'geometry']. Utilizza un punto quando specifichi i valori composti. Ad esempio: opening_hours.weekday_text.

I campi corrispondono ai risultati di Ricerca di luoghi e sono divisi in tre categorie di fatturazione: Base, Contatto e Ambiente. I campi di base sono fatturati alla tariffa di base e non ci sono costi aggiuntivi. Contatti e atmosfera vengono fatturati a una tariffa superiore. Consulta il listino prezzi per ulteriori informazioni. Le attribuzioni (html_attributions) sono sempre viene restituito a ogni chiamata, indipendentemente dal fatto che il campo sia stato richiesto.

Basic

La categoria Base include i seguenti campi:
business_status, formatted_address, geometry icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (deprecato), photos, place_id, plus_code e types

Contatto

La categoria Contatto include il seguente campo: opening_hours
(ritirato nella Places Library, nell'API Maps JavaScript. Utilizza una richiesta Place Details per ottenere opening_hours risultati).

Atmosfera

La categoria Atmosfera include i seguenti campi: price_level, rating e user_ratings_total

Le findPlaceFromQuery() e findPlaceFromPhoneNumber() metodi utilizzano ciascuno lo stesso insieme e può restituire gli stessi campi nelle rispettive risposte.

Impostare la differenziazione della località (metodi Trova luogo)

Utilizza il parametro locationBias per ottenere risultati preferiti in Trova luogo in una determinata area. Puoi impostare locationBias in quanto segue modi:

Risultati bias relativi a un'area specifica:

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

Definisci un'area rettangolare in cui eseguire la ricerca:

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

Puoi anche utilizzare un campo LatLngBounds.

Definisci il raggio di ricerca (in metri), centrato su una determinata area:

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

Richieste di ricerca nelle vicinanze

Una ricerca nelle vicinanze ti consente di cercare luoghi all'interno di un'area specifica tramite: parola chiave o tipo. Una ricerca nelle vicinanze deve sempre includere una località, che può essere possono essere specificate in uno dei due modi seguenti:

  • un LatLngBounds.
  • un'area circolare definita come la combinazione di location : specifica il centro del cerchio come LatLng oggetto e un raggio misurato in metri.

Viene avviata una ricerca di luoghi nelle vicinanze con una chiamata al Il metodo nearbySearch() di PlacesService, che restituiscono un array di PlaceResult. Tieni presente che nearbySearch() sostituisce il metodo search() a partire dalla versione 3.9.

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

Questo metodo accetta una richiesta con i seguenti campi:

  • Una di queste opzioni:
    • bounds, che deve essere un google.maps.LatLngBounds l'oggetto che definisce il rettangolo nell'area di ricerca. La distanza diagonale massima supportata per i limiti è di circa 100.000 metri.
    • un location e un radius; la prima prende un google.maps.LatLng e il secondo utilizza una semplice numero intero, che rappresenta il raggio del cerchio in metri. Il valore massimo consentito è di 50.000 metri. Tieni presente che quando rankBy è impostato su DISTANZA, devi specificare un valore location ma non puoi specificare un radius o bounds.
  • keyword (facoltativo): un termine da abbinare in tutti i campi disponibili, inclusi, a titolo esemplificativo, name, type e indirizzo, nonché recensioni dei clienti e altri contenuti di terze parti.
  • minPriceLevel e maxPriceLevel (Facoltativo) - Limita i risultati solo alle posizioni all'interno di per l'intervallo specificato. Intervallo di valori validi compreso tra 0 (il più conveniente) a 4 (il più costoso), inclusivo.
  • name Obsoleta. Equivalente a keyword. Valori in questo campo vengono combinati con i valori del campo keyword e passati come parte della stessa stringa di ricerca.
  • openNow (facoltativo): un valore booleano, indicando che il servizio Places deve restituire solo i luoghi che sono aperte al momento dell'invio della query. Luoghi che non specificare gli orari di apertura nel database di Google Places non verranno se includi questo parametro nella query. Impostazione Da openNow a false non ha alcun effetto.
  • rankBy (facoltativo): specifica l'ordine in i risultati visualizzati. I valori possibili sono:
    • google.maps.places.RankBy.PROMINENCE (valore predefinito). Questo ordina i risultati in base alla loro importanza. Il ranking dai la priorità ai luoghi più prominenti all'interno del raggio impostato rispetto alle vicinanze luoghi corrispondenti, ma meno visibili. L'evidenza può essere influenzati dal ranking di un luogo nell'indice di Google, dalla popolarità globale, e altri fattori. Quando google.maps.places.RankBy.PROMINENCE è specificato, il parametro radius è obbligatorio.
    • google.maps.places.RankBy.DISTANCE. Questa opzione ordina i risultati in ordine crescente in base alla loro distanza dal location (obbligatorio). Tieni presente che non puoi specificare bounds e/o radius personalizzati se specificare RankBy.DISTANCE. Se specifichi RankBy.DISTANCE, uno o più di keyword, name o type sono obbligatorio.
  • type: limita il tra i risultati in posizioni corrispondenti al tipo specificato. È possibile specificare un solo tipo specificato (se viene fornito più di un tipo, tutti i tipi successivi al primo vengono ignorate). Consulta l'elenco di tipi supportati.

Devi anche passare un metodo di callback a nearbySearch() per e gestire l'oggetto dei risultati Risposta 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]);
    }
  }
}

Visualizza esempio

Richieste di ricerca testuale

Il servizio di ricerca testuale di Google Places è un servizio web che restituisce informazioni su un insieme di posizioni basate su una stringa, ad esempio "pizza a Roma" o "negozi di scarpe vicino a Roma". Il servizio risponde un elenco di luoghi corrispondenti alla stringa di testo e gli eventuali bias di località è stata configurata. La risposta della ricerca includerà un elenco di luoghi. Puoi inviare Richiesta Dettagli luogo per ulteriori informazioni su qualsiasi luogo nel risposta.

Le ricerche di testo vengono avviate con una chiamata al Metodo textSearch() di PlacesService. 

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

Questo metodo accetta una richiesta con i seguenti campi:

  • query (obbligatorio) La stringa di testo su cui cerca, ad esempio: "ristorante" o "Via Cavour 123". Deve essere un luogo nome, indirizzo o categoria di attività. Qualsiasi altro tipo di input può generano errori e non è garantito che restituiscano risultati validi. I luoghi restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla percezione della loro pertinenza. Questo parametro diventa facoltativo se il parametro type viene utilizzato anche nella richiesta di ricerca.
  • Facoltativamente:
    • openNow: un valore booleano, indicando che il servizio Places deve restituire solo i luoghi che sono aperte al momento dell'invio della query. Luoghi che non specificare gli orari di apertura nel database di Google Places non verranno se includi questo parametro nella query. Impostazione Da openNow a false non ha alcun effetto.
    • minPriceLevel e maxPriceLevel - Limita i risultati solo alle posizioni all'interno di al livello di prezzo specificato. I valori validi sono compresi nell'intervallo 0 (il più conveniente) a 4 (il più costoso), inclusivo.
    • Una di queste opzioni:
      • bounds, che deve essere un google.maps.LatLngBounds l'oggetto che definisce il rettangolo nell'area di ricerca. La distanza diagonale massima supportata per i limiti è di circa 100.000 metri.
      • location e radius. Puoi polarizza i risultati a una circonferenza specificata passando location e un parametro radius. In questo modo indica al servizio Places di preferire la visualizzazione dei risultati cerchio. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. La posizione accetta un oggetto google.maps.LatLng e il raggio prende un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è 50.000 metri.
    • type: limita i risultati ai luoghi corrispondenti del tipo specificato. È possibile specificare un solo tipo (se più di uno) viene specificato, tutti i tipi successivi alla prima vengono ignorati). Consulta: l'elenco dei tipi supportati.

Devi anche passare un metodo di callback a textSearch() per per gestire l'oggetto dei risultati Risposta 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]);
    }
  }
}

Cerca risposte

Codici di stato

L'oggetto risposta PlacesServiceStatus contiene lo stato di la richiesta e potrebbero contenere informazioni di debug per aiutarti a rintracciare perché la richiesta di luogo non è andata a buon fine. I valori di stato possibili sono:

  • INVALID_REQUEST: questa richiesta non è valida.
  • OK: la risposta contiene un risultato valido.
  • OVER_QUERY_LIMIT: la pagina web ha superato la sua richiesta quota.
  • REQUEST_DENIED: la pagina web non è autorizzata a utilizzare i PlacesService.
  • UNKNOWN_ERROR: impossibile inviare la richiesta PlacesService elaborati a causa di un errore del server. Riprova.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati di ricerca di luoghi

findPlace(), nearbySearch() e Le funzioni textSearch() restituiscono un array di PlaceResult di oggetti.

Ogni oggetto PlaceResult può includere le seguenti proprietà:

  • business_status indica l'operatività del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti i seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    di Gemini Advanced. Se non esistono dati, business_status non viene restituito.
  • formatted_address è una stringa contenente la stringa leggibile di questo luogo. La proprietà formatted_address è solo per una ricerca testuale.

    Spesso, questo indirizzo equivale all'indirizzo postale. Tieni presente che alcune paesi, come il Regno Unito, non consentono la distribuzione di veri e propri indirizzi postali a causa di limitazioni di licenza.

    L'indirizzo formattato è logicamente composto da uno o più indirizzi componenti. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (stato USA).

    Non analizzare l'indirizzo formattato in modo programmatico. Dovresti invece usare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta nel campo dell'indirizzo formattato.

  • geometry: informazioni relative alla geometria del luogo. Questo include:
    • location fornisce la latitudine e la longitudine posto.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizza questo luogo.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Usa invece business_status per conoscere lo stato di attività delle aziende.
  • plus_code (vedi Apri codice posizione e plus code) è un riferimento a una posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione di indirizzi in luoghi in cui non esistono (in cui gli edifici non sono numerati o le vie non hanno un nome).

    Il Plus Code è formattato come codice globale e codice composto:

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    di Gemini Advanced. In genere, vengono restituiti sia il codice globale sia il codice composto. Tuttavia, se il risultato è una località remota (ad esempio, un oceano o un deserto) può essere restituito solo il codice globale.
  • html_attributions: un array di attribuzioni che dovresti durante la visualizzazione dei risultati di ricerca. Ogni voce dell'array contiene il testo HTML di una singola attribuzione. Nota: questa è una l'aggregazione di tutte le attribuzioni per l'intera risposta della ricerca. Tutti PlaceResult oggetti nella risposta contengono quindi elenchi di attribuzioni identici.
  • icon restituisce l'URL per un'icona PNG a colori da 71 x 71 px.
  • icon_mask_base_uri restituisce l'URL di base per un elemento non colorato , meno l'estensione .svg o .png.
  • icon_background_color restituisce il codice colore esadecimale predefinito per la categoria del luogo.
  • name: il nome del luogo.
  • opening_hours può contenere le seguenti informazioni:
    • open_now è un valore booleano che indica se il luogo è aperto al momento (deprecato in Places Library, API Maps JavaScript, usa utc_offset_minutes ).
  • place_id è un identificatore testuale che identifica in modo univoco un posto. Per recuperare informazioni sul luogo, passa questo identificatore nella Dettagli luogo richiesta. Scopri di più su come fare riferimento a un luogo con un ID luogo.
  • rating contiene la valutazione del luogo, da 0,0 a 5,0, in base sulla base di recensioni aggregate degli utenti.
  • types Un array di tipi per questo luogo (ad es. ["political", "locality"] o ["restaurant", "lodging"]). Questo array può contenere più valori oppure vuoto. È possibile che vengano introdotti nuovi valori senza preavviso. Consulta l'elenco di tipi supportati.
  • vicinity: un indirizzo semplificato del luogo, che include: il nome della via, il numero civico e la località, ma non i provincia/stato, codice postale o paese. Ad esempio, Google's Sydney, La sede dell'Australia ha un valore di vicinity pari a 5/48 Pirrama Road, Pyrmont.

Accesso a risultati aggiuntivi

Per impostazione predefinita, la ricerca di ogni luogo restituisce fino a 20 risultati per query. Tuttavia, ogni ricerca può restituire fino a 60 risultati, suddivisi in tre pagine. Pagine aggiuntive sono disponibili tramite PlaceSearchPagination . Per accedere a pagine aggiuntive, devi acquisire i campi PlaceSearchPagination tramite una funzione di callback. La L'oggetto PlaceSearchPagination è definito come:

  • hasNextPage è una proprietà booleana che indica se ulteriormente disponibili i risultati. true quando è presente un ulteriore pagina dei risultati.
  • nextPage() una funzione che restituirà il set successivo di che consentono di analizzare i dati e visualizzare i risultati. Dopo aver eseguito una ricerca, devi attendere secondi prima che sia disponibile la pagina successiva di risultati.

Per visualizzare la serie di risultati successiva, chiama nextPage. Ogni pagina di risultati deve essere visualizzata prima che venga visualizzata la pagina successiva di che consentono di analizzare i dati e visualizzare i risultati. Tieni presente che ogni ricerca viene conteggiata come una singola richiesta nei confronti del tuo limiti di utilizzo.

L'esempio seguente mostra come modificare la funzione di callback in acquisire l'oggetto PlaceSearchPagination, in modo da poter inviare più richieste di ricerca.

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
Visualizza esempio

Prova Sample

Place Details

Oltre a fornire un elenco di luoghi all'interno di un'area, i luoghi può anche restituire informazioni dettagliate su un luogo specifico. Una volta che un luogo è stato restituito in una risposta di ricerca di un luogo, L'ID luogo può essere utilizzato per richiedere ulteriori dettagli sul luogo, come l'indirizzo completo, il numero di telefono, la valutazione degli utenti e recensioni, ecc.

Richieste Place Details

I dettagli sul luogo vengono richiesti con una chiamata al getDetails().

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

Questo metodo accetta una richiesta, contenente i dati del luogo placeId e i campi che indicano i tipi di dati di Places da restituire. Scopri di più su come fare riferimento a un luogo con un ID luogo.

Prende anche un metodo di callback, che deve gestire il codice di stato passato nella risposta google.maps.places.PlacesServiceStatus. come oggetto 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);
  }
}

Visualizza esempio

Campi (Dettagli luogo)

Il parametro fields accetta un array di stringhe (nomi di campo).

Utilizza il parametro fields per specificare un array di tipi di dati dei luoghi da restituire. Ad esempio: fields: ['address_components', 'opening_hours', 'geometry']. Utilizza un punto quando specifichi i valori composti. Ad esempio: opening_hours.weekday_text.

I campi corrispondono a Dettagli luogo di fatturazione e sono suddivise in tre categorie di fatturazione: Base, Contatto e Atmosfera. I campi di base vengono fatturati alla tariffa di base e non sono soggetti a addebiti. I campi Contact e Atmosphere vengono fatturati a una tariffa superiore. Consulta il listino prezzi per ulteriori informazioni. Le attribuzioni (html_attributions) sono sempre restituito a ogni chiamata, indipendentemente dal fatto che sia stata richiesta.

Basic

La categoria Base include i seguenti campi:
address_components, adr_address, business_status formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (ritirato), photo, place_id, plus_code, type, url, utc_offset (ritirato in Places Library, nell'API Maps JavaScript), utc_offset_minutes, vicinity

Contatto

La categoria Contatto include i seguenti campi:
formatted_phone_number, international_phone_number opening_hours website

Atmosfera

La categoria Atmosfera include i seguenti campi: price_level, rating, reviews user_ratings_total

Scopri di più su campi del luogo. Per ulteriori informazioni informazioni su come vengono fatturate le richieste di dati di Place, vedi Utilizzo e fatturazione.

Risposte Place Details

Codici di stato

L'oggetto risposta PlacesServiceStatus contiene lo stato di la richiesta e potrebbero contenere informazioni di debug per aiutarti a rintracciare perché la richiesta Dettagli luogo non è andata a buon fine. I valori di stato possibili sono:

  • INVALID_REQUEST: questa richiesta non è valida.
  • OK: la risposta contiene un risultato valido.
  • OVER_QUERY_LIMIT: la pagina web ha superato la sua richiesta quota.
  • NOT_FOUND La località di riferimento non era nel database di Places.
  • REQUEST_DENIED: la pagina web non è autorizzata a utilizzare i PlacesService.
  • UNKNOWN_ERROR: impossibile inviare la richiesta PlacesService elaborati a causa di un errore del server. Riprova.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati Place Details

Una chiamata getDetails() andata a buon fine restituisce un PlaceResult con le seguenti proprietà:

  • address_components: un array contenente l'elemento applicabili a questo indirizzo.

    In genere, ogni componente dell'indirizzo contiene i seguenti campi:

    • types[] è un array che indica il tipo di . Consulta l'elenco di tipi supportati.
    • long_name è la descrizione testuale o il nome completo del indirizzo come restituito dal Geocoder.
    • short_name è un nome testuale abbreviato per l'indirizzo , se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere una metrica long_name "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale a due lettere.

    Prendi nota delle seguenti informazioni su address_components[] array:

    • L'array dei componenti dell'indirizzo può contenere più componenti rispetto formatted_address.
    • L'array non include necessariamente tutte le entità politiche contenere un indirizzo, diverso da quelli inclusi nei formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi usare la geocodifica inversa, La latitudine/longitudine dell'indirizzo come parametro della richiesta.
    • Non è garantito che il formato della risposta rimanga lo stesso tra richieste. In particolare, il numero di address_components varia in base all'indirizzo richiesto e può cambiare nel tempo in base all'indirizzo nello stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un particolare componente può essere mancante in una risposta successiva.
  • business_status indica l'operatività del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti i seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    di Gemini Advanced. Se non esistono dati, business_status non viene restituito.
  • formatted_address: l'indirizzo leggibile di questo luogo.

    Spesso, questo indirizzo equivale all'indirizzo postale. Tieni presente che alcune paesi, come il Regno Unito, non consentono la distribuzione di veri e propri indirizzi postali a causa di limitazioni di licenza.

    L'indirizzo formattato è logicamente composto da uno o più indirizzi componenti. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (stato USA).

    Non analizzare l'indirizzo formattato in modo programmatico. Dovresti invece usare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta nel campo dell'indirizzo formattato.

  • formatted_phone_number: il numero di telefono del luogo, formattato secondo convenzione regionale di un numero.
  • geometry: informazioni relative alla geometria del luogo. Questo include:
    • location fornisce la latitudine e la longitudine posto.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizza questo luogo.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Usa invece business_status per conoscere lo stato di attività delle aziende.
  • plus_code (vedi Apri codice posizione e plus code) è un riferimento a una posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione di indirizzi in luoghi in cui non esistono (in cui gli edifici non sono numerati o le vie non hanno un nome).

    Il Plus Code è formattato come codice globale e codice composto:

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    di Gemini Advanced. In genere, vengono restituiti sia il codice globale sia il codice composto. Tuttavia, se il risultato è una località remota (ad esempio, un oceano o un deserto) può essere restituito solo il codice globale.
  • html_attributions: testo dell'attribuzione da visualizzare risultato di questo luogo.
  • icon: URL a una risorsa immagine che può essere utilizzata per rappresentano il tipo di luogo.
  • international_phone_number contiene il telefono del luogo numero in formato internazionale. Il formato internazionale include il paese ed è preceduta dal segno più (+). Ad esempio, international_phone_number per Google a Sydney, Australia ufficio è +61 2 9374 4000.
  • name: il nome del luogo.
  • utc_offset Obsoleta In Places Library, nell'API Maps JavaScript, usa utc_offset_minutes.
  • utc_offset_minutes contiene il numero di minuti il fuso orario attuale del luogo è diverso da UTC. Ad esempio, per i luoghi in Sydney, Australia durante l'ora legale sarà 660 (+11 ore) dal fuso orario UTC) e per i luoghi della California al di fuori dell'ora legale sarà -480 (-8 ore dal fuso orario UTC).
  • opening_hours contiene le seguenti informazioni:
    • open_now (Deprecato in Places Library, nell'API Maps JavaScript; utilizzare opening_hours.isOpen(). Guarda questo video per scoprire come utilizzare isOpen con Place Details.) è un valore booleano che indica se il luogo è aperto nel punto attuale nel tempo.
    • periods[] è un array di periodi di apertura che coprono sette giorni, a partire da domenica, in ordine cronologico. Ogni periodo contiene:
      • open contiene una coppia di oggetti giorno e ora che descrive l'apertura del luogo:
        • day un numero compreso tra 0 e 6, corrispondente ai giorni della settimana, a partire dalla domenica. Ad esempio, 2 significa martedì.
        • time può contenere un'ora del giorno in formato hhmm di 24 ore (i valori sono compresi tra 0000 e 2359). La time verrà registrato nel fuso orario del luogo.
      • close può contenere una coppia di oggetti giorno e ora che descrive quando il luogo chiude. Nota: se un luogo è sempre aperta, la sezione close presenti nella risposta. Le applicazioni possono fare affidamento rappresentato come un punto open contenente day con valore 0 e time con valore 0000, e nessuna close.
    • weekday_text è un array di sette stringhe che rappresenta gli orari di apertura formattati per ogni giorno della settimana. Se Il parametro language è stato specificato in Place Details richiesta, il servizio Places formatterà e localizzerà l'orario di apertura in modo appropriato per quella lingua. L'ordine degli elementi in questo dipende dal parametro language. Alcune lingue iniziano la settimana di lunedì, mentre gli altri iniziano di domenica.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Usa invece business_status per conoscere lo stato di attività delle aziende.
  • photos[]: un array di PlacePhoto oggetti. È possibile usare un PlacePhoto per ottenere una foto con getUrl() oppure puoi ispezionare l'oggetto per i seguenti valori:
    • height: l'altezza massima dell'immagine in pixel.
    • width: la larghezza massima dell'immagine in pixel.
    • html_attributions: testo dell'attribuzione da visualizzare con la foto di questo luogo.
  • place_id: un identificatore testuale che identifica in modo univoco un luogo e può essere utilizzato per recuperare informazioni sul luogo tramite Dettagli luogo richiesta. Scopri di più su come fare riferimento a un luogo con un ID luogo.
  • rating: la valutazione del luogo, da 0,0 a 5,0, in base a e recensioni aggregate degli utenti.
  • reviews un array di massimo cinque recensioni. Ogni recensione è costituito da diversi componenti:
    • aspects[] contiene un array di PlaceAspectRating oggetti, ognuno dei quali fornisce un valutazione di un singolo attributo della struttura. Il primo oggetto nell'array è considerato l'aspetto principale. Ciascuna PlaceAspectRating è definito come:
      • type il nome dell'aspetto che viene valutato. Sono supportati i seguenti tipi: appeal, atmosphere, decor facilities, food, overall quality e service.
      • rating la valutazione dell'utente per questo particolare specifico, da 0 a 3.
    • author_name il nome dell'utente che ha inviato la per la revisione. Le recensioni anonime vengono attribuite a "Un utente Google". Se parametro della lingua è stato impostato, poi la frase "Un utente Google" che restituiscono una stringa localizzata.
    • author_url l'URL del profilo Google+ dell'utente, se disponibili.
    • language: un codice lingua IETF che indica la lingua utilizzati nella recensione dell'utente. Questo campo contiene il tag della lingua principale e non il tag secondario che indica il paese o la regione. Per Ad esempio, tutte le recensioni in inglese sono contrassegnate come "en" e non "en-AU" o "en-UK" e così via.
    • rating la valutazione complessiva dell'utente per questo luogo. Questo è un numero intero compreso tra 1 e 5.
    • text la recensione dell'utente. Quando esamini un posizione con Google Places, le recensioni testuali sono considerate facoltative; pertanto questo campo può essere vuoto.
  • types Un array di tipi per questo luogo (ad es. ["political", "locality"] o ["restaurant", "lodging"]). Questo array può contenere più valori oppure vuoto. È possibile che vengano introdotti nuovi valori senza preavviso. Consulta l'elenco di tipi supportati.
  • url: URL della pagina Google ufficiale dedicata posto. Questa è la pagina di proprietà di Google che contiene le migliori le informazioni disponibili sul luogo. Le applicazioni devono rimandare a o incorporare questa pagina in qualsiasi schermata che mostri risultati dettagliati sul luogo utente.
  • vicinity: un indirizzo semplificato del luogo, che include: il nome della via, il numero civico e la località, ma non i provincia/stato, codice postale o paese. Ad esempio, Google's Sydney, La sede dell'Australia ha un valore di vicinity pari a 5/48 Pirrama Road, Pyrmont. La proprietà vicinity viene restituita solo per una Ricerca nelle vicinanze.
  • website elenca il sito web ufficiale di questo luogo, ad esempio come azienda" homepage.

Nota: le valutazioni multidimensionali potrebbero non essere disponibili per tutte le località. Se il numero di recensioni è troppo basso, la risposta dettagliata includere una valutazione precedente su una scala da 0,0 a 5,0 (se disponibile) oppure nessuna valutazione.

Utilizzare il componente Panoramica del luogo

Nota: questo esempio utilizza una libreria open source. Consulta le README per ricevere assistenza e feedback relativi alla raccolta.

Prova i componenti web. Utilizza la Componente web Panoramica del luogo per visualizzare i dettagli del luogo con una rappresentazione visiva.

Immagine che mostra variazioni di dimensioni x-small, small, medium, large e x-large delle Componente Panoramica del luogo visualizzato in base al campo delle dimensioni inserito dall&#39;utente.
Figura 1: informazioni sui dettagli dei luoghi con cinque diverse varianti di dimensioni

Fare riferimento a un luogo con un ID luogo

Un ID luogo è un riferimento univoco a un luogo su una mappa di Google. ID luogo sono disponibili per la maggior parte delle località, tra cui attività, punti di riferimento, parchi, e incroci.

Per utilizzare un ID luogo nella tua app, devi prima cercare l'ID, ovvero disponibile in PlaceResult di una richiesta Place Search o Details. Puoi quindi utilizzare questo ID luogo per cercare Luogo Dettagli.

Gli ID luogo sono esenti dalle limitazioni di memorizzazione nella cache dichiarate nella Sezione 3.2.3(b) del Termini di servizio di Google Maps Platform. Puoi quindi memorizzare i valori degli ID luogo per utilizzarli in un secondo momento. Per best practice per la memorizzazione degli ID luogo, consulta le panoramica di Place ID.

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

La funzionalità Place Photo ti consente di aggiungere immagini fotografiche di alta qualità sul tuo sito. Il servizio Foto ti consente di accedere a milioni di foto archiviate nel database di Places e Google+ Local. Quando arrivi a destinazione utilizzando una richiesta Place Details, foto verranno restituiti i riferimenti per i contenuti fotografici pertinenti. La ricerca nelle vicinanze e ricerca testuale restituiscono anche un solo riferimento foto per luogo, quando pertinenti. Tramite il servizio Foto puoi accedere alle foto di riferimento e ridimensiona l'immagine alle dimensioni ottimali per la tua applicazione.

Verrà restituito un array di PlacePhoto oggetti come parte dell'istruzione Oggetto PlaceResult per qualsiasi getDetails(), textSearch() o Richiesta di nearbySearch() effettuata nei confronti di PlacesService.

Nota: il numero di foto restituite varia a seconda della richiesta.

  • Una ricerca nelle vicinanze o una ricerca testuale restituirà al massimo uno PlacePhoto oggetto.
  • Una richiesta di dettagli restituirà fino a dieci oggetti PlacePhoto.

Puoi richiedere l'URL dell'immagine associata chiamando il metodo PlacePhoto.getUrl() e trasmettere un valore Oggetto PhotoOptions. L'oggetto PhotoOptions consente di specificare l'altezza e la larghezza massime desiderate per l'immagine. Se specificare un valore sia per maxHeight sia per maxWidth, il servizio fotografico ridimensiona l'immagine al valore più piccolo tra le due dimensioni, mentre mantenendo le proporzioni originali.

Il seguente snippet di codice accetta un oggetto luogo e aggiunge un indicatore alla mappa se esiste una foto. L'immagine dell'indicatore predefinito viene sostituita da una versione ridotta della foto.

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

Le foto restituite dal servizio Foto provengono da una vasta gamma di sedi, tra cui proprietari di attività e foto fornite dagli utenti. Nella maggior parte dei casi, casi, queste foto possono essere utilizzate senza attribuzione o avranno i requisiti dell'immagine. Tuttavia, se l'oggetto restituito L'elemento photo include un valore nell'elemento html_attributions, devi includere il valore aggiuntivo nella tua applicazione ovunque mostri l'immagine.