libreria Places

Panoramica

Le funzioni dell'API Maps JavaScript, Places Library, consentono alla tua applicazione di cercare luoghi (definiti in questa API come stabilimenti, località geografiche o punti di interesse importanti) contenuti in un'area definita, come i confini di una mappa o intorno a un punto fisso.

L'API Places offre una funzionalità di completamento automatico che puoi utilizzare per assegnare alle tue applicazioni il comportamento di ricerca di tipo avanzato del campo di ricerca di Google Maps. Quando un utente inizia a digitare un indirizzo, il completamento automatico completa il resto. Per saperne di più, consulta la documentazione sul completamento automatico.

Per iniziare

Se non hai dimestichezza con l'API Maps JavaScript o con JavaScript, ti consigliamo di consultare la documentazione di JavaScript e di ottenere una chiave API prima di iniziare.

Abilita API

Prima di utilizzare la libreria Places nell'API JavaScript di Maps, assicurati innanzitutto che l'API Places sia attivata nella console Google Cloud, nello stesso progetto configurato per l'API JavaScript di Maps.

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla console Google Cloud.
  2. Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella dashboard, cerca API Places.
  4. Se nell'elenco è presente l'API Places, significa che è già abilitata. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API E SERVIZI per visualizzare la scheda Libreria. In alternativa, nel menu a sinistra, seleziona Raccolta.
    2. Cerca API Places e selezionala dall'elenco dei risultati.
    3. Seleziona ATTIVA. Al termine della procedura, API Places viene visualizzata nell'elenco delle API nella dashboard.

Caricamento della libreria

Il servizio Places è una libreria autosufficiente, separata dal codice principale dell'API Maps JavaScript. Per utilizzare le funzionalità contenute all'interno di questa libreria, devi prima caricarla utilizzando il parametro libraries nell'URL di bootstrap dell'API Maps:

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

Per ulteriori informazioni, consulta la Panoramica delle librerie.

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

L'applicazione di limitazioni delle API alle tue chiavi limita l'utilizzo della chiave API a una o più API o SDK. Verranno elaborate le richieste relative a SDK e API associati alla chiave API. Le richieste riguardanti SDK e API non associati alla chiave API non andranno a buon fine. Per limitare una chiave API per l'utilizzo con l'API Maps JavaScript, Libreria Places:
  1. Vai alla console Google Cloud.
  2. Fai clic sul menu a discesa del progetto e seleziona il progetto che contiene la chiave API che vuoi proteggere.
  3. Fai clic sul pulsante Menu e seleziona Google Maps Platform > Credenziali.
  4. Nella pagina Credenziali, fai clic sul nome della chiave API che vuoi proteggere.
  5. Nella pagina Limita e rinomina la chiave API, imposta le restrizioni:
    • 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 è elencata, devi attivarla.
  6. Fai clic su SALVA.

Limiti e norme di utilizzo

Quote

La libreria Places condivide una quota di utilizzo con l'API Places, come descritto nella documentazione dei limiti di utilizzo dell'API Places.

Norme

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

Ricerche di luoghi

Con il servizio Luoghi puoi eseguire i seguenti tipi di ricerche:

Le informazioni restituite possono includere attività come ristoranti, negozi e uffici, nonché risultati "geocodifica", che indicano indirizzi, aree politiche come paesi e città e altri punti di interesse.

Richieste di Trova luogo

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

Trova luogo da query

Find Place from Query accetta un input di testo e restituisce un luogo. L'input può essere costituito da qualsiasi tipo di dati di Places, ad esempio il nome o l'indirizzo di un'attività. Per effettuare una richiesta di ricerca di luoghi da query, chiama il metodo findPlaceFromQuery() di PlacesService, che accetta i seguenti parametri:

  • query (obbligatorio) La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante" o "123 Via Principale". Deve essere un toponimo, un indirizzo o una categoria di stabilimenti. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca risultati validi. L'API Places restituirà le corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla pertinenza percepita.
  • fields (obbligatorio) Uno o più campi che specificano 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 risultati e la risposta google.maps.places.PlacesServiceStatus.

L'esempio seguente mostra una chiamata a findPlaceFromQuery(), la ricerca di "Museum of Contemporary Art Australia" e i campi 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 da numero di telefono

Find Place from Phone Number accetta un numero di telefono e restituisce un luogo. Per effettuare una richiesta di ricerca di un luogo da un numero di telefono, chiama il metodo findPlaceFromPhoneNumber() di PlacesService, che accetta i seguenti parametri:

  • phoneNumber (obbligatorio) Un numero di telefono in formato E.164.
  • fields (obbligatorio) Uno o più campi che specificano 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 findPlaceFromPhoneNumber() per gestire l'oggetto risultati e la risposta google.maps.places.PlacesServiceStatus.

Campi (metodi di Find Place)

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 valori composti. Ad esempio: opening_hours.weekday_text.

I campi corrispondono ai risultati di Ricerca luoghi e sono suddivisi in tre categorie di fatturazione: Di base, Contatti e Atmosfera. I campi di base vengono fatturati alla tariffa base e non comportano costi aggiuntivi. I campi Contact e Atmosphere vengono fatturati a una tariffa più elevata. Per ulteriori informazioni, consulta il listino prezzi. Le attribuzioni (html_attributions) vengono sempre rese a ogni chiamata, indipendentemente dal fatto che il campo sia stato richiesto.

Basic

La categoria Di base include i seguenti campi:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (non più supportato), photos, place_id, plus_code, types

Contatto

La categoria Contatti include il seguente campo: opening_hours
(disponibile nella Libreria Places, API Maps JavaScript. Utilizza una richiesta Places Details per ottenere i risultatiopening_hours.

Atmosfera

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

I metodi findPlaceFromQuery() e findPlaceFromPhoneNumber() accettano lo stesso insieme di campi e possono restituire gli stessi campi nelle rispettive risposte.

Impostare la bias di geolocalizzazione (metodi Trova posto)

Utilizza il parametro locationBias per fare in modo che Find Place favorisca i risultati in una determinata area. Puoi impostare locationBias nei seguenti modi:

Inclinare i risultati verso un'area specifica:

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

Definisci un'area rettangolare da cercare:

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

Puoi anche utilizzare un LatLngBounds.

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

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

Richieste di Nearby Search

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

  • a LatLngBounds.
  • un'area circolare definita come combinazione della proprietà location che specifica il centro del cerchio come oggetto LatLng e di un raggio misurato in metri.

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

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

Questo metodo riceve una richiesta con i seguenti campi:

  • Una di queste soglie:
    • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare. La distanza diagonale massima supportata per l'area delimitata è di circa 100.000 metri.
    • un location e un radius; il primo accetta un oggetto google.maps.LatLng, mentre il secondo accetta un semplice numero intero, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri. Tieni presente che quando rankBy è impostato su DISTANCE, devi specificare un location, ma non puoi specificare un radius o un bounds.
  • keyword (facoltativo): un termine da abbinare a tutti i campi disponibili, inclusi, a titolo esemplificativo, nome, tipo e indirizzo, nonché recensioni dei clienti e altri contenuti di terze parti.
  • minPriceLevel e maxPriceLevel (facoltativo): limita i risultati solo ai luoghi all'interno dell'intervallo specificato. I valori validi vanno da 0 (più accessibile) a 4 (più costoso), inclusi.
  • name Ritirato. Equivalente a keyword. I valori in questo campo vengono combinati con i valori nel campo keyword e trasmessi come parte della stessa stringa di ricerca.
  • openNow (facoltativo) : un valore booleano che indica che il servizio Luoghi deve restituire solo i luoghi aperti al pubblico al momento dell'invio della query. I luoghi che non specificano l'orario di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella query. L'impostazione di openNow su false non ha alcun effetto.
  • rankBy (facoltativo) - Specifica l'ordine in cui vengono elencati i risultati. I valori possibili sono:
    • google.maps.places.RankBy.PROMINENCE (valore predefinito). Questa opzione ordina i risultati in base alla loro importanza. Il ranking favorirebbe i luoghi in evidenza all'interno del raggio impostato rispetto ai luoghi nelle vicinanze corrispondenti, ma meno in evidenza. L'importanza può essere influenzata dal ranking di un luogo nell'indice di Google, dalla popolarità globale e da altri fattori. Quando viene specificato google.maps.places.RankBy.PROMINENCE, il parametro radius è obbligatorio.
    • google.maps.places.RankBy.DISTANCE. Questa opzione ordina i risultati in ordine crescente in base alla distanza dal valore location specificato (obbligatorio). Tieni presente che non puoi specificare un valore personalizzato per bounds e/o radius se specifichi RankBy.DISTANCE. Quando specifichi RankBy.DISTANCE, è necessario specificare uno o più valori tra keyword, name o type.
  • type: limita i risultati ai luoghi corrispondenti al tipo specificato. È possibile specificare un solo tipo (se vengono forniti più tipi, tutti i tipi successivi alla prima voce vengono ignorati). Consulta l'elenco dei tipi supportati.

Devi anche passare un metodo di callback a nearbySearch() per gestire l'oggetto risultati e la 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 di testo

Il servizio di ricerca di testi di Google Places è un servizio web che restituisce informazioni su un insieme di luoghi in base a una stringa, ad esempio "pizza a New York" o "negozi di scarpe vicino a Ottawa". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e a eventuali bias di località impostati. La risposta alla ricerca includerà un elenco di luoghi. Puoi inviare una richiesta di dettagli sui luoghi per avere ulteriori informazioni su uno dei luoghi nella 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 riceve una richiesta con i seguenti campi:

  • query (obbligatorio) La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante" o "123 Via Principale". Deve essere un nome, un indirizzo o una categoria di stabilimenti. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca risultati validi. Il servizio Luoghi restituirà le corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla pertinenza percepita. Questo parametro diventa facoltativo se il parametro type viene utilizzato anche nella richiesta di ricerca.
  • Facoltativamente:
    • openNow: un valore booleano che indica che il servizio Luoghi deve restituire solo i luoghi aperti al pubblico al momento dell'invio della query. I luoghi che non specificano l'orario di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella query. L'impostazione di openNow su false non ha alcun effetto.
    • minPriceLevel e maxPriceLevel – Limita i risultati solo ai luoghi che rientrano nel livello di prezzo specificato. I valori validi sono compresi nell'intervallo da 0 (il più conveniente) a 4 (il più costoso), inclusi.
    • Una di queste opzioni:
      • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare. La distanza diagonale massima supportata per l'area delimitata è di circa 100.000 metri.
      • location e radius: puoi orientare i risultati verso un circolo specificato passando un parametro location e un parametro radius. In questo modo, il servizio Luoghi darà la preferenza alla visualizzazione dei risultati all'interno di questo cerchio. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. La posizione accetta un oggetto google.maps.LatLng e il raggio accetta un semplice numero intero che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri.
    • type: limita i risultati ai luoghi corrispondenti al tipo specificato. È possibile specificare un solo tipo (se vengono forniti più tipi, tutti i tipi successivi alla prima voce vengono ignorati). Consulta l'elenco dei tipi supportati.

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

Risposte di ricerca

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire il motivo del mancato completamento della richiesta del luogo. 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 quota di richieste.
  • REQUEST_DENIED: alla pagina web non è consentito utilizzare PlacesService.
  • UNKNOWN_ERROR: non è stato possibile elaborare la richiesta di PlacesService a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.
  • ZERO_RESULTS: nessun risultato è stato trovato per questa richiesta.

Risultati di ricerca dei luoghi

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

Ogni oggetto PlaceResult può includere le seguenti proprietà:

  • business_status indica lo stato di funzionamento del luogo, se si tratta di un'attività. Può contenere uno dei seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se non esistono dati, business_status non viene restituito.
  • formatted_address è una stringa contenente l'indirizzo di questo luogo in formato leggibile. La proprietà formatted_address viene riportata solo per una ricerca di testo.

    Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali veri a causa di limitazioni relative alle licenze.

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

    Non analizzare l'indirizzo formattato tramite programmazione. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.

  • geometry: le informazioni relative alla geometria del luogo. Ad esempio:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizzi questo luogo.
  • permanently_closed (non più supportato) è un indicatore booleano che indica se il luogo è chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per recuperare lo stato operativo delle attività.
  • plus_code (vedi Open Location Code e plus code) è un riferimento di 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 più piccola. I Plus Code possono essere utilizzati al posto degli indirizzi in luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

    Il plus code è formattato come codice globale e codice composto:

    • global_code è un codice area di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una località esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti tramite programmazione.
    In genere, vengono restituiti sia il codice globale sia il codice composto. Tuttavia, se il risultato si trova in una località remota (ad esempio un oceano o un deserto), potrebbe essere restituito solo il codice globale.
  • html_attributions: un array di attribuzioni da visualizzare quando vengono visualizzati i risultati di ricerca. Ogni voce dell'array contiene il testo HTML di un singolo attributo. Nota:si tratta di un'aggregazione di tutti gli attributi per l'intera risposta alla ricerca. Pertanto, tutti gli oggetti PlaceResult nella risposta contengono elenchi di attribuzione identici.
  • icon restituisce l'URL di un'icona PNG a colori di 71 x 71 pixel.
  • icon_mask_base_uri restituisce l'URL di base per un'icona non colorata, 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 nella libreria Places, API Maps JavaScript, utilizza utc_offset_minutes).
  • place_id è un identificatore di testo che identifica in modo univoco un luogo. Per recuperare le informazioni sul luogo, passa questo identificatore nella richiesta Places Details. 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 alle recensioni degli utenti aggregate.
  • types Un array di tipi per questo luogo (ad es. ["political", "locality"] o ["restaurant", "lodging"]). Questo array può contenere più valori o essere vuoto. I nuovi valori possono essere introdotti senza preavviso. Consulta l'elenco dei tipi supportati.
  • vicinity: un indirizzo semplificato per il luogo, che include il nome della via, il numero civico e la località, ma non la provincia/stato, il codice postale o il paese. Ad esempio, l'ufficio di Google a Sydney, Australia, ha un valore vicinity pari a 5/48 Pirrama Road, Pyrmont.

Accesso a risultati aggiuntivi

Per impostazione predefinita, ogni ricerca di luoghi restituisce fino a 20 risultati per query. Tuttavia, ogni ricerca può restituire fino a 60 risultati, suddivisi in tre pagine. Altre pagine sono disponibili tramite l'oggetto PlaceSearchPagination. Per accedere ad altre pagine, devi acquisire l'oggetto PlaceSearchPagination tramite una funzione di callback. L'oggetto PlaceSearchPagination è definito come:

  • hasNextPage una proprietà booleana che indica se sono disponibili altri risultati. true se è presente un'altra pagina di risultati.
  • nextPage() una funzione che restituisce il successivo insieme di risultati. Dopo aver eseguito una ricerca, devi attendere due secondi prima che la pagina di risultati successiva sia disponibile.

Per visualizzare l'insieme di risultati successivo, chiama nextPage. Ogni pagina di risultati deve essere visualizzata prima di visualizzare la pagina successiva di risultati. Tieni presente che ogni ricerca viene conteggiata come una singola richiesta ai fini dei limiti di utilizzo.

L'esempio seguente mostra come modificare la funzione di callback per acquisire l'oggetto PlaceSearchPagination, in modo da poter emettere 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, il servizio Luoghi può anche restituire informazioni dettagliate su un luogo specifico. Una volta che un luogo è stato restituito in una risposta alla ricerca di luoghi, il suo ID luogo può essere utilizzato per richiedere ulteriori dettagli sul luogo, ad esempio l'indirizzo completo, il numero di telefono, la valutazione degli utenti e le recensioni e così via.

Richieste di dettagli dei luoghi

I dettagli dei luoghi vengono richiesti con una chiamata al metodo getDetails() del servizio.

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

Questo metodo riceve una richiesta contenente il placeId del luogo desiderato 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.

Inoltre, accetta un metodo di callback, che deve gestire il codice di stato passato nella risposta google.maps.places.PlacesServiceStatus, nonché l'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 del 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 valori composti. Ad esempio: opening_hours.weekday_text.

I campi corrispondono ai risultati di Place Details e sono suddivisi in tre categorie di fatturazione: Basic, Contact e Atmosphere. I campi di base vengono fatturati alla tariffa base e non comportano costi aggiuntivi. I campi Contact e Atmosphere vengono fatturati a una tariffa più elevata. Per ulteriori informazioni, consulta il listino prezzi. Le attribuzioni (html_attributions) vengono sempre rese a ogni chiamata, indipendentemente dal fatto che siano state richieste.

Basic

La categoria di 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 (dismesso), photo, place_id, plus_code, type, url, utc_offset (dismesso nella Libreria Places, API Maps JavaScript), utc_offset_minutes, vicinity

Contatto

La categoria Contatti 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ù sui campi dei luoghi. Per ulteriori informazioni su come vengono fatturate le richieste di dati dei luoghi, consulta Utilizzo e fatturazione.

Risposte di Places Details

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire il motivo del fallimento della richiesta di dettagli sul luogo. 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 quota di richieste.
  • NOT_FOUND La località a cui si fa riferimento non è stata trovata nel database di Luoghi.
  • REQUEST_DENIED: alla pagina web non è consentito utilizzare PlacesService.
  • UNKNOWN_ERROR: non è stato possibile elaborare la richiesta di PlacesService a causa di un errore del server. La richiesta potrebbe andare a buon fine se riprovi.
  • ZERO_RESULTS: nessun risultato è stato trovato per questa richiesta.

Risultati di Place Details

Una chiamata getDetails() riuscita restituisce un oggetto PlaceResult con le seguenti proprietà:

  • address_components: un array contenente i componenti distinti applicabili a questo indirizzo.

    Ogni componente dell'indirizzo contiene in genere i seguenti campi:

    • types[] è un array che indica il tipo del componente dell'indirizzo. Consulta l'elenco dei tipi supportati.
    • long_name è la descrizione completa del testo o il nome del componente dell'indirizzo restituito dal geocodificatore.
    • short_name è un nome testuale abbreviato per l'elemento dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un long_name di "Alaska" e un short_name di "AK" utilizzando l'abbreviazione postale di 2 lettere.

    Tieni presente quanto segue sull'array address_components[]:

    • L'array di componenti dell'indirizzo può contenere più componenti rispetto a formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, a parte quelle incluse in formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta.
    • Non è garantito che il formato della risposta rimanga invariato tra le richieste. In particolare, il numero di address_components varia in base all'indirizzo richiesto e può cambiare nel tempo per lo stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un determinato componente potrebbe essere mancante in una risposta successiva.
  • business_status indica lo stato di funzionamento del luogo, se si tratta di un'attività. Può contenere uno dei seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se non esistono dati, business_status non viene restituito.
  • formatted_address: l'indirizzo leggibile di questo luogo.

    Spesso questo indirizzo è equivalente all'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali veri a causa di limitazioni relative alle licenze.

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

    Non analizzare l'indirizzo formattato tramite programmazione. Devi invece utilizzare i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.

  • formatted_phone_number: il numero di telefono del luogo, formattato in base alle convenzioni regionali del numero.
  • geometry: le informazioni relative alla geometria del luogo. Ad esempio:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizzi questo luogo.
  • permanently_closed (non più supportato) è un indicatore booleano che indica se il luogo è chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per recuperare lo stato operativo delle attività.
  • plus_code (vedi Open Location Code e plus code) è un riferimento di 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 più piccola. I Plus Code possono essere utilizzati al posto degli indirizzi in luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

    Il plus code è formattato come codice globale e codice composto:

    • global_code è un codice area di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una località esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti tramite programmazione.
    In genere, vengono restituiti sia il codice globale che il codice composto. Tuttavia, se il risultato si trova in una località remota (ad esempio un oceano o un deserto), potrebbe essere restituito solo il codice globale.
  • html_attributions: il testo dell'attribuzione da visualizzare per questo risultato di ricerca.
  • icon: URL di una risorsa immagine che può essere utilizzata per rappresentare il tipo di luogo.
  • international_phone_number contiene il numero di telefono del luogo in formato internazionale. Il formato internazionale include il codice paese ed è preceduto dal segno più (+). Ad esempio, il valore international_phone_number per l'ufficio di Google a Sydney, in Australia, è +61 2 9374 4000.
  • name: il nome del luogo.
  • utc_offset Ritirata nell'API Maps JavaScript, nella libreria Places, utilizza utc_offset_minutes.
  • utc_offset_minutes contiene il numero di minuti di differenza tra il fuso orario corrente di questo luogo e UTC. Ad esempio, per i luoghi di Sydney, in Australia, durante l'ora legale, il valore sarà 660 (+11 ore rispetto a UTC) e per i luoghi della California al di fuori dell'ora legale, il valore sarà -480 (-8 ore rispetto a UTC).
  • opening_hours contiene le seguenti informazioni:
    • open_now (Ritiro nell'API Maps JavaScript, nella raccolta Places; utilizza opening_hours.isOpen(). Guarda questo video per scoprire come utilizzare isOpen con i dettagli dei luoghi. è un valore booleano che indica se il luogo è aperto al momento.
    • 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 descrivono l'orario di apertura del luogo:
        • day un numero compreso tra 0 e 6, corrispondente ai giorni della settimana, a partire da domenica. Ad esempio, 2 significa martedì.
        • time può contenere un'ora nel formato 24 ore (hh:mm) (i valori sono nell'intervallo 0000-2359). time verrà registrato nel fuso orario del luogo.
      • close può contenere una coppia di oggetti giorno e ora che descrivono quando il luogo chiude. Nota: se un luogo è sempre aperto, la sezione close non sarà presente nella risposta. Le applicazioni possono fare affidamento su un valore sempre aperto rappresentato da un periodo open contenente day con valore 0 e time con valore 0000, senza close.
    • weekday_text è un array di sette stringhe che rappresentano gli orari di apertura formattati per ogni giorno della settimana. Se nella richiesta dettagli del luogo è stato specificato un parametro language, il servizio Places formatta e localizza l'orario di apertura in modo appropriato per la lingua in questione. L'ordine degli elementi in questo array dipende dal parametro language. Alcune lingue iniziano la settimana di lunedì, mentre altre di domenica.
  • permanently_closed (non più supportato) è un indicatore booleano che indica se il luogo è chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per recuperare lo stato operativo delle attività.
  • photos[]: un array di oggetti PlacePhoto. Puoi utilizzare un PlacePhoto per ottenere una foto con il metodo getUrl() oppure puoi controllare l'oggetto per verificare 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 del luogo.
  • place_id: un identificatore di testo che identifica in modo univoco un luogo e può essere utilizzato per recuperare informazioni sul luogo tramite una richiesta dettagli sul luogo. 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 alle recensioni aggregate degli utenti.
  • reviews un array di massimo cinque recensioni. Ogni recensione è composta da diversi componenti:
    • aspects[] contiene un array di oggetti PlaceAspectRating, ognuno dei quali fornisce una valutazione di un singolo attributo della struttura. Il primo oggetto nell'array è considerato l'aspetto principale. Ogni 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 aspetto specifico, da 0 a 3.
    • author_name il nome dell'utente che ha inviato la recensione. Le recensioni anonime vengono attribuite a "Un utente Google". Se è stato impostato un parametro di lingua, la frase "Un utente Google" restituirà una stringa localizzata.
    • author_url l'URL del profilo Google+ dell'utente, se disponibile.
    • language un codice lingua IETF che indica la lingua utilizzata nella recensione dell'utente. Questo campo contiene solo il tag della lingua principale e non il tag secondario che indica il paese o la regione. Ad esempio, tutte le recensioni in inglese sono contrassegnate come "en" e non come "en-AU" o "en-UK" e così via.
    • rating la valutazione complessiva dell'utente per questo luogo. Deve essere un numero intero compreso tra 1 e 5.
    • text la recensione dell'utente. Quando recensisci un luogo con Google Places, le recensioni con testo sono considerate facoltative. Pertanto, questo campo potrebbe essere vuoto.
  • types Un array di tipi per questo luogo (ad es. ["political", "locality"] o ["restaurant", "lodging"]). Questo array può contenere più valori o essere vuoto. I nuovi valori possono essere introdotti senza preavviso. Consulta l'elenco dei tipi supportati.
  • url: URL della pagina ufficiale di Google per questo luogo. Questa è la pagina di proprietà di Google che contiene le migliori informazioni disponibili sul luogo. Le applicazioni devono collegarsi a questa pagina o incorporarla in qualsiasi schermata che mostri all'utente risultati dettagliati sul luogo.
  • vicinity: un indirizzo semplificato per il luogo, che include il nome della via, il numero civico e la località, ma non la provincia/stato, il codice postale o il paese. Ad esempio, l'ufficio di Google a Sydney, Australia, ha un valore vicinity pari a 5/48 Pirrama Road, Pyrmont. La proprietà vicinity viene restituita solo per una Ricerca nelle vicinanze.
  • website elenca il sito web autorevole per questo luogo, ad esempio la home page di un'attività.

Nota:le valutazioni multidimensionali potrebbero non essere disponibili per tutte le località. Se le recensioni sono troppo poche, la risposta ai dettagli includerà una valutazione precedente su una scala da 0,0 a 5,0 (se disponibile) o nessuna valutazione.

Fare riferimento a un luogo con un ID luogo

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

Per utilizzare un ID luogo nella tua app, devi prima cercarlo. L'ID è disponibile in PlaceResult di una richiesta di ricerca o dettagli dei luoghi. Puoi quindi utilizzare questo ID luogo per cercare Dettagli sul luogo.

Gli ID luogo sono esenti da restrizioni alla memorizzazione nella cache riportate nella sezione 3.2.3(b) dei Termini di servizio di Google Maps Platform. Di conseguenza, puoi memorizzare i valori ID luogo per utilizzarli in un secondo momento. Per le best practice per la memorizzazione degli ID luogo, consulta la panoramica degli ID luogo.

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à Foto dei luoghi ti consente di aggiungere contenuti fotografici di alta qualità al tuo sito. Il servizio Foto ti consente di accedere a milioni di foto archiviate nel database di Places e Google+ Local. Quando ottieni informazioni su un luogo utilizzando una richiesta di dettagli sul luogo, vengono restituiti riferimenti alle foto per i contenuti fotografici pertinenti. Le richieste di ricerca nelle vicinanze e di ricerca di testo restituiscono anche un singolo riferimento fotografico per luogo, se pertinente. Utilizzando il servizio Foto, puoi accedere alle foto a cui fai riferimento e ridimensionare l'immagine in base alle dimensioni ottimali per la tua applicazione.

Un array di oggetti PlacePhoto verrà restituito nell'ambito dell'oggetto PlaceResult per qualsiasi richiesta getDetails(), textSearch() o nearbySearch() effettuata in base a un PlacesService.

Nota:il numero di foto restituite varia in base alla richiesta.

  • Una ricerca nelle vicinanze o una ricerca di testo restituirà al massimo un oggettoPlacePhoto.
  • Una richiesta Details restituisce fino a dieci oggetti PlacePhoto.

Puoi richiedere l'URL dell'immagine associata chiamando il metodo PlacePhoto.getUrl() e passando un oggetto PhotoOptions valido. L'oggetto PhotoOptions consente di specificare l'altezza e la larghezza massime desiderate dell'immagine. Se specifichi un valore sia per maxHeight sia per maxWidth, il servizio fotografico ridimensionerà l'immagine in base alla dimensione più piccola, mantenendo le proporzioni originali.

Il seguente snippet di codice accetta un oggetto Place e aggiunge un indicatore alla mappa se esiste una foto. L'immagine dell'indicatore predefinita 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 varie località, tra cui foto inviate da proprietari di attività e utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o l'attribuzione richiesta sarà inclusa nell'immagine. Tuttavia, se l'elemento photo restituito include un valore nel campo html_attributions, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque venga visualizzata l'immagine.