libreria Places

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.
Seleziona piattaforma: Android iOS JavaScript Servizio web

Panoramica

Le funzioni della libreria Places, dell'API Maps JavaScript consentono all'applicazione di cercare luoghi (definiti in questa API come strutture, località geografiche o punti d'interesse importanti) contenuti in un'area definita, ad esempio i confini di una mappa o intorno a un punto fisso.

L'API Places offre una funzionalità di completamento automatico che potete utilizzare per fornire alle applicazioni il comportamento di ricerca in anteprima del campo di ricerca di Google Maps. Quando un utente inizia a digitare un indirizzo, il completamento automatico inserirà il resto. Per ulteriori informazioni, consulta la documentazione relativa al completamento automatico.

Per cominciare

Se non conosci l'API Maps JavaScript o con JavaScript, ti consigliamo di esaminare JavaScript e ottenere una chiave API prima di iniziare.

Abilita API

Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata in Google Cloud Console, nello stesso progetto che hai configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla console Google Cloud.
  2. Fai clic sul pulsante Seleziona un progetto, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Cerca API Places dall'elenco delle API nella Dashboard.
  4. Se nell'elenco vedi l'API Places, significa che l'API è già attiva. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API E SERVIZI per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
    2. Cerca l'API Places e selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine del processo, viene visualizzata l'API Places nell'elenco delle API nella Dashboard.

Caricamento della raccolta in corso...

Il servizio Places è una libreria autonoma, separata dal codice principale dell'API Maps JavaScript. Per utilizzare la funzionalità contenuta in questa libreria, devi innanzitutto caricarla utilizzando il parametro libraries nell'URL di bootstrap dell'API di Google Maps:

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

Per maggiori informazioni, consulta la panoramica delle librerie.

Aggiungere l'API Places all'elenco delle limitazioni dell'API della chiave API

L'applicazione di restrizioni API alle tue chiavi limita l'utilizzo della chiave API a uno o più SDK o API. Verranno elaborate le richieste a un'API o a un SDK associato alla chiave API. Le richieste a un'API o a un SDK non associati alla chiave API non andranno a buon fine. Per limitare l'utilizzo di una chiave API con la libreria Places, 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 la chiave API che vuoi proteggere.
  3. Fai clic sul pulsante del 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 limitazioni:
    • Restrizioni delle API
      • Seleziona Limita la 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 criteri di utilizzo

Quote

La libreria libreria Places API condivide una quota di utilizzo con l'API Places come descritto nella documentazione Limiti di utilizzo per l'API Places.

Norme

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

Ricerche di luoghi

Con il servizio Places puoi eseguire le seguenti ricerche:

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

Richieste di ricerca luoghi

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

Trova luogo da query

Trova luogo da query richiede un input di testo e restituisce un luogo. Puoi inserire qualsiasi tipo di dati sul luogo, ad esempio il nome o l'indirizzo di un'attività. Per creare una richiesta Trova luogo da query, chiama il metodo findPlaceFromQuery() di PlacesService, che utilizza i seguenti parametri:

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

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

L'esempio seguente mostra una chiamata a findPlaceFromQuery(), cercando "Museum of Contemporary Art Australia" e includendo 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 l'esempio

Trova luogo da numero di telefono

Trova luogo da numero di telefono accetta un numero di telefono e restituisce un luogo. Per effettuare una richiesta Find Place from Phone Number, chiama il metodo findPlaceFromPhoneNumber() di PlacesService, che prevede 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 sul luogo da restituire.
  • (Facoltativo) locationBias Le coordinate che definiscono l'area da cercare. Il valore può essere uno dei seguenti:

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

Campi (metodi Trova luogo)

Utilizza il parametro fields per specificare un array di tipi di dati relativi al luogo 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 dei luoghi e sono suddivisi in tre categorie di fatturazione: Di base, Contatto e Ambiente. I campi di base vengono fatturati alla tariffa di base e non comportano costi aggiuntivi. I campi Contatto e Ambiente sono fatturati a una tariffa superiore. Consulta il foglio dei prezzi per ulteriori informazioni. Le attribuzioni (html_attributions) vengono sempre restituite 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 (deprecato), photos, place_id, plus_code, types

Contatto

La categoria Contatti include il seguente campo: opening_hours
(deprecato nella libreria Places, nell'API Maps JavaScript). Utilizza una richiesta Dettagli luogo per ottenere i risultati relativi a opening_hours.

Ambiente

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

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

Imposta bias per la posizione (metodi di Trova luogo)

Utilizza il parametro locationBias per rendere i risultati della ricerca di luoghi preferiti in una determinata area. Puoi impostare locationBias nei seguenti modi:

Differenziazione per una zona specifica:

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

Definisci un'area rettangolare per la ricerca:

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

Puoi anche utilizzare un metodo LatLngBounds.

Definisci un raggio per la ricerca (in metri), centrato su una determinata area:

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

Richieste di ricerca nelle vicinanze

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

  • LatLngBounds.
  • un'area circolare definita come la combinazione della proprietà location (specificando il centro del cerchio come oggetto LatLng) e un raggio, misurato in metri

Viene avviata una ricerca di Luoghi nelle vicinanze 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 accetta una richiesta con i seguenti campi:

  • Scegli una delle seguenti opzioni:
    • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare; oppure
    • location e radius; il primo prende un oggetto google.maps.LatLng e il secondo un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri. 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 a quei luoghi all'interno dell'intervallo specificato. I valori validi di questo criterio sono compresi tra 0 (più conveniente) e 4 (più costosi), inclusi.
  • name obsoleto. Equivalente a keyword. I valori in questo campo vengono combinati con quelli nel campo keyword e trasmessi come parte della stessa stringa di ricerca.
  • openNow (facoltativo): un valore booleano che indica che il servizio Places deve restituire i luoghi aperti solo al momento dell'invio della query. I luoghi che non specificano gli orari di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella tua query. L'impostazione di openNow su false non ha alcun effetto.
  • rankBy (facoltativo): consente di specificare 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 favorirà i luoghi in evidenza nel raggio impostato rispetto ai luoghi nelle vicinanze che corrispondono, ma sono meno visibili. L'evidenza può essere influenzata dal ranking di un luogo nell'indice di Google, dalla popolarità globale e da 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 da location (obbligatorio). Tieni presente che non puoi specificare un bounds personalizzato e/o radius se specifichi RankBy.DISTANCE. Quando specifichi RankBy.DISTANCE, sono obbligatori uno o più tra keyword, name o type.
  • type: limita i risultati alle posizioni corrispondenti al tipo specificato. È possibile specificare un solo tipo (se ne viene fornito più di uno), tutti i tipi successivi alla prima vengono ignorati. Consulta l'elenco dei tipi supportati.

Devi anche trasmettere un metodo di callback a nearbySearch() per gestire l'oggetto dei 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 testuale

Il servizio di ricerca testuale 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 calzature vicino a Ottawa". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e l'eventuale bias per la posizione impostato. La risposta di ricerca includerà un elenco di luoghi. Puoi inviare una richiesta Dettagli luogo per ottenere ulteriori informazioni sui luoghi indicati 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 accetta una richiesta con i seguenti campi:

  • query (obbligatorio) La stringa di testo in cui eseguire la ricerca, ad esempio "ristorante" o "Via Garibaldi". Deve essere il nome, l'indirizzo o la categoria di un'attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituiscano risultati validi. Il servizio Places restituirà le corrispondenze candidati in base a questa stringa e ordina 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 Places deve restituire i luoghi aperti al momento dell'invio della query. I luoghi che non specificano gli orari di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella tua query. L'impostazione di openNow su false non ha alcun effetto.
    • minPriceLevel e maxPriceLevel: limita i risultati solo a quei luoghi entro il livello di prezzo specificato. I valori validi sono compresi nell'intervallo da 0 (più conveniente) a 4 (più costoso), inclusi.
    • Scegli una delle seguenti opzioni:
      • bounds: un oggetto google.maps.LatLngBounds che definisce il rettangolo in cui eseguire la ricerca; oppure
      • a location e radius: puoi bias nei risultati per un cerchio specificato passando un parametro location e radius. In questo modo indichi al servizio Places di preferire la visualizzazione dei risultati all'interno di quella cerchia. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. La posizione accetta un oggetto google.maps.LatLng e il raggio assume un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri.
    • type: limita i risultati alle posizioni corrispondenti al tipo specificato. È possibile specificare un solo tipo (se ne viene fornito più di uno), tutti i tipi successivi alla prima vengono ignorati. Consulta l'elenco dei tipi supportati.

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

Cerca risposte

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire perché la richiesta di luogo non è riuscita. I possibili valori di stato 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: la pagina web non è autorizzata a utilizzare PlacesService.
  • UNKNOWN_ERROR: non è stato possibile elaborare la richiesta PlacesService a causa di un errore del server. Se riprovi, la richiesta potrebbe avere esito positivo.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati di ricerca del luogo

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 operativo del luogo, se è 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 leggibile di questo luogo. La proprietà formatted_address viene restituita solo per una ricerca di testo.

    Spesso si tratta dell'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni delle licenze.

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

    Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece i singoli componenti dell'indirizzo, che la risposta dell'API include oltre al campo dell'indirizzo formattato.

  • geometry: informazioni relative alla geometria del luogo. A tal fine si considera incluso quanto segue:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce la visualizzazione preferita sulla mappa quando visualizza questo luogo.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo si è arrestato in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per conoscere lo stato operativo delle attività.
  • plus_code (vedi Apri Codice di località e più codici) è un riferimento di località codificato, derivato dalle coordinate di latitudine e longitudine, che rappresentano 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 come sostituzione degli indirizzi per i luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di 6 o più caratteri (849VCWC8+R9).
    • compound_code è un codice locale di sei o più caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    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), può essere restituito solo il codice globale.
  • html_attributions: un array di attribuzioni che dovresti visualizzare quando mostri i risultati di ricerca. Ogni voce nell'array contiene il testo HTML per una singola attribuzione. Nota: si tratta di un'aggregazione di tutte le attribuzioni per l'intera risposta di ricerca. Tutti gli oggetti PlaceResult nella risposta contengono pertanto elenchi di attribuzione identici.
  • icon restituisce l'URL di un'icona colorata 71px x 71px PNG.
  • 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 corrente (deprecato nella libreria Places, nell'API Maps JavaScript, utilizza invece utc_offset_minutes).
  • place_id è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare le informazioni sul luogo, passa questo identificatore nella richiesta Dettagli luogo. 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, basata su 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 essere vuoto. Potrebbero essere introdotti nuovi valori 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, la sede di Google a Sydney, in Australia, ha un valore vicinity di 5/48 Pirrama Road, Pyrmont.

Accesso a risultati aggiuntivi

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

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

Per visualizzare il gruppo di risultati successivo, chiama nextPage. Ogni pagina di risultati deve essere visualizzata prima di visualizzare la pagina successiva dei 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 e consentirti di effettuare 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 anteprima

Place Details

Oltre a fornire un elenco di luoghi all'interno di una zona, il servizio Places può anche fornire informazioni dettagliate su un luogo specifico. Una volta restituito un luogo nella risposta a una ricerca di luoghi, l'ID luogo può essere utilizzato per richiedere ulteriori dettagli sul luogo, ad esempio indirizzo completo, numero di telefono, valutazione degli utenti e recensioni.

Richieste di dettagli sul luogo

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

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

Questo metodo accetta 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.

Viene inoltre utilizzato un metodo di callback, che deve gestire il codice di stato trasmesso nella risposta google.maps.places.PlacesServiceStatus e 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 luogo)

Il parametro fields accetta una matrice di stringhe (nomi di campo).

Utilizza il parametro fields per specificare un array di tipi di dati relativi al luogo da restituire. Ad esempio: fields: ['address_component', '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 Environment. I campi di base vengono fatturati alla tariffa di base e non comportano costi aggiuntivi. I campi Contatto e Ambiente sono fatturati a una tariffa superiore. Consulta il foglio dei prezzi per ulteriori informazioni. Le attribuzioni (html_attributions) vengono sempre restituite a ogni chiamata, indipendentemente dal fatto che sia stata richiesta.

Basic

La categoria Base include i seguenti campi:
address_component, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (deprecato), photo, place_id, plus_code, type, url, utc_offset (Libreria}

Contatto

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

Ambiente

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

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

Risposte Dettagli luogo

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a capire perché la richiesta di dettagli del luogo non è andata a buon fine. I possibili valori di stato 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à di riferimento non è stata trovata nel database di Places.
  • REQUEST_DENIED: la pagina web non è autorizzata a utilizzare PlacesService.
  • UNKNOWN_ERROR: non è stato possibile elaborare la richiesta PlacesService a causa di un errore del server. Se riprovi, la richiesta potrebbe avere esito positivo.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati dei dettagli del luogo

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

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

    In genere, ogni componente dell'indirizzo contiene 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 Geocoder.
    • short_name è un nome abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente indirizzo per lo stato dell'Alaska potrebbe avere long_name "Alaska" e short_name "AK" utilizzando l'abbreviazione postale di 2 lettere.

    Prendi nota dei seguenti fatti relativi all'array di address_components[]:

    • La matrice dei componenti dell'indirizzo può contenere più componenti di formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse nell'elemento 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 della richiesta.
    • Non è garantito che il formato della risposta rimanga lo stesso 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 la posizione nella matrice. Il tipo del componente può cambiare. Potresti non trovare un determinato componente in una risposta successiva.
  • business_status indica lo stato operativo del luogo, se è 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 si tratta dell'indirizzo postale. Tieni presente che alcuni paesi, come il Regno Unito, non consentono la distribuzione di indirizzi postali reali a causa di limitazioni delle licenze.

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

    Non analizzare l'indirizzo formattato in modo programmatico. Utilizza invece 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 alla convenzione regionale del numero.
  • geometry: informazioni relative alla geometria del luogo. A tal fine si considera incluso quanto segue:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce la visualizzazione preferita sulla mappa quando visualizza questo luogo.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo si è arrestato in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per conoscere lo stato operativo delle attività.
  • plus_code (vedi Apri Codice di località e più codici) è un riferimento di località codificato, derivato dalle coordinate di latitudine e longitudine, che rappresentano 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 come sostituzione degli indirizzi per i luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di 6 o più caratteri (849VCWC8+R9).
    • compound_code è un codice locale di sei o più caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    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), può essere restituito solo il codice globale.
  • html_attributions: testo dell'attribuzione da visualizzare per questo risultato del luogo.
  • icon: URL a una risorsa immagine che può essere utilizzata per rappresentare il tipo di questo 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 international_phone_number per la sede Google di Sydney, in Australia è +61 2 9374 4000.
  • name: il nome del luogo.
  • utc_offset Deprecato nella libreria Places, API Maps JavaScript, utilizza invece utc_offset_minutes.
  • utc_offset_minutes contiene il numero di minuti in cui il fuso orario attuale di questo luogo è utilizzato rispetto al fuso orario UTC. Ad esempio, per i luoghi a Sydney, in Australia, quando è in vigore l'ora legale, questo valore è di 660 (+11 ore dal fuso orario UTC) e per i luoghi in California non compresi l'ora legale come -480 (-8 ore dal fuso orario UTC).
  • opening_hours contiene le seguenti informazioni:
    • open_now (deprecato nella libreria Places, API Maps JavaScript; utilizza invece opening_hours.isOpen()). Guarda questo video per informazioni su come utilizzare isOpen con Dettagli luogo. è 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'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 nel formato hhmm (i valori sono compresi tra 0000 e 2359). time verrà segnalato nel fuso orario del luogo.
      • close può contenere una coppia di oggetti giorno e ora che descrivono la chiusura del luogo. Nota: se un luogo è sempre aperto, la sezione close non sarà presente nella risposta. Le applicazioni possono fare affidamento su un'attività sempre aperta rappresentata come un periodo open contenente day con valore 0 e time con valore 0000 e nessun valore close.
    • weekday_text è un array di sette stringhe che rappresenta l'orario di apertura formattato per ogni giorno della settimana. Se è stato specificato un parametro language nella richiesta Dettagli luogo, il servizio Places formatterà e localizzerà gli orari di apertura in base alla lingua selezionata. L'ordinamento degli elementi in questo array dipende dal parametro language. Alcune lingue iniziano la settimana di lunedì, mentre altre la domenica.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo si è arrestato in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per conoscere lo stato operativo delle attività.
  • photos[]: un array di oggetti PlacePhoto. PlacePhoto può essere utilizzato per ottenere una foto con il metodo getUrl() oppure puoi ispezionare l'oggetto per verificare se sono presenti i seguenti valori:
    • height: l'altezza massima dell'immagine, in pixel.
    • width: la larghezza massima dell'immagine, in pixel.
    • html_attributions: testo di attribuzione da visualizzare con questa foto del luogo.
  • place_id: un identificatore testuale che identifica in modo univoco un luogo e può essere utilizzato per recuperare informazioni sul luogo tramite una richiesta Dettagli luogo. Scopri di più su come fare riferimento a un luogo con un ID luogo.
  • rating: valutazione del luogo, da 0,0 a 5,0, basata su 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 la valutazione di un singolo attributo dell'edificio. 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 della lingua, la frase "Un utente Google" restituirà una stringa localizzata.
    • author_url l'URL del profilo Google+ degli utenti, 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 l'area geografica. Ad esempio, tutte le recensioni in inglese presentano il tag "en" e non "en-AU" o "en-UK" e così via.
    • rating valutazione complessiva dell'utente per questo luogo. È un numero intero compreso tra 1 e 5.
    • text recensione dell'utente. Quando esamini una sede con Google Places, le recensioni di 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 oppure essere vuoto. Potrebbero essere introdotti nuovi valori senza preavviso. Consulta l'elenco dei tipi supportati.
  • url: URL della pagina Google ufficiale di questo luogo. Questa è una pagina di proprietà di Google che contiene le migliori informazioni disponibili sul luogo. Le applicazioni devono rimandare a questa pagina o incorporarla in qualsiasi schermata che mostri all'utente risultati dettagliati relativi al 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, la sede di Google a Sydney, in Australia, ha un valore vicinity di 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 il numero di recensioni è troppo ridotto, la risposta dei dettagli includerà una valutazione precedente su una scala da 0,0 a 5,0 (se disponibile) o non effettuerà alcuna valutazione.

Fare riferimento a un luogo con un ID.

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

Per utilizzare un ID luogo nella tua app, devi innanzitutto cercarlo, disponibile in PlaceResult di una richiesta di ricerca o dettagli di un luogo. Puoi quindi utilizzare questo ID luogo per cercare Dettagli del luogo.

Gli ID luogo sono esenti dalle limitazioni di memorizzazione nella cache indicate nella Sezione 3.2.3(a) dei Termini di servizio di Google Maps Platform. Puoi quindi memorizzare i valori degli ID luogo per utilizzarli in un secondo momento. Per best practice relative alla memorizzazione degli ID luogo, consulta la panoramica sull'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);

Foto del luogo

La funzionalità Foto del luogo ti consente di aggiungere contenuti fotografici di alta qualità al tuo sito. Il servizio Foto ti consente di accedere ai milioni di foto archiviate nel database di Places e di Google+ Local. Quando ricevi informazioni sul luogo tramite una richiesta Dettagli luogo, vengono restituiti riferimenti a foto per contenuti fotografici pertinenti. Anche le richieste di ricerca nelle vicinanze e la ricerca di testo restituiscono un singolo riferimento fotografico per luogo, se pertinente. Grazie al servizio Foto potrai accedere alle foto di riferimento e ridimensionare l'immagine in base alle dimensioni ottimali della tua applicazione.

Un array di oggetti PlacePhoto verrà restituito come parte dell'oggetto PlaceResult per qualsiasi richiesta getDetails(), textSearch() o nearbySearch() effettuata su un elemento PlacesService.

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

  • Una ricerca nelle vicinanze o una ricerca per testo restituiranno al massimo un oggetto PlacePhoto.
  • Una richiesta Dettagli restituirà fino a dieci oggetti PlacePhoto.

Per richiedere l'URL dell'immagine associata, chiama il metodo PlacePhoto.getUrl() e trasmetti 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 di foto ridimensionerà l'immagine in base alle due dimensioni, 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 predefinita dell'indicatore è 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 diverse località, tra cui proprietari di attività e foto fornite dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o includeranno l'attribuzione richiesta come parte dell'immagine. Tuttavia, se l'elemento photo restituito include un valore nel campo html_attributions, devi includere l'attribuzione aggiuntiva nell'applicazione ovunque mostri l'immagine.