libreria Places

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Panoramica

Le funzioni nella libreria Places e nell'API Maps JavaScript consentono all'applicazione di cercare luoghi (definiti in questa API come attività, posizioni geografiche o punti di 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 puoi utilizzare per assegnare alle tue applicazioni il comportamento di ricerca type-ahead del campo di ricerca di Google Maps. Quando un utente inizia a digitare un indirizzo, il completamento automatico compila il resto. Per maggiori informazioni, consulta la documentazione relativa al completamento automatico.

Per iniziare

Se non hai dimestichezza con l'API Maps JavaScript o JavaScript, ti consigliamo di consultare le risorse JavaScript e Ottieni una chiave API prima di iniziare.

abilita le API

Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata nella console Google Cloud, 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, poi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella dashboard, cerca API Places.
  4. Se vedi l'API Places nell'elenco, significa che è già abilitata. Se l'API non è nell'elenco, 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, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, l'API Places viene visualizzata nell'elenco delle API nella dashboard.

Caricamento della libreria 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 prima 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&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 restrizioni delle API alle chiavi limita l'utilizzo della chiave API a uno o più API o SDK. Verranno elaborate le richieste a un'API o a un SDK associati alla chiave API. Le richieste a un'API o a un SDK non associati alla chiave API non andranno a buon fine. Per limitare una chiave API da utilizzare 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 da proteggere.
  3. Fai clic sul pulsante del menu e seleziona Google Maps Platform > Credenziali.
  4. Nella pagina Credentials (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 chiave.
      • Fai clic su Seleziona API e seleziona sia API Maps JavaScript sia API Places.
        Se una delle API non è presente nell'elenco, devi enable.
  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 sui 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 i seguenti tipi di ricerche:

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

Richieste di ricerca di luoghi

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

Trova luogo da query

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

  • query (obbligatorio) La stringa di testo in cui cercare, ad esempio: "ristorante" o "Via Roma 123". Deve essere il nome di un luogo, un indirizzo o una categoria di luoghi. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca 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 dei luoghi da restituire.
  • locationBias (Facoltativo) Coordinate che definiscono l'area da cercare. Può essere uno dei seguenti:

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

L'esempio seguente mostra una chiamata a findPlaceFromQuery(), durante la ricerca di "Museo di arte contemporanea Australia" e l'inclusione dei 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

Trova luogo da numero di telefono prende un numero di telefono e restituisce un luogo. Per effettuare una richiesta Trova luogo da numero di telefono, 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 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 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 sui luoghi da restituire. Ad esempio: fields: ['formatted_address', 'opening_hours', 'geometry']. Per specificare valori composti, utilizza un punto. Ad esempio: opening_hours.weekday_text.

I campi corrispondono ai risultati di ricerca di luoghi e sono suddivisi in tre categorie di fatturazione: Base, Contatto e Ambiente. I campi Basic vengono fatturati in base alla tariffa di base e non comportano costi aggiuntivi. I campi Contatto e Ambiente vengono fatturati a una tariffa superiore. Per ulteriori informazioni, consulta il listino prezzi. Le attribuzioni (html_attributions) vengono sempre restituite a ogni chiamata, indipendentemente dal fatto che il campo sia stato o richiesto o meno.

Basic

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

Contatto

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

Ambiente

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

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

Imposta bias di località (metodi Trova luogo)

Utilizza il parametro locationBias per assegnare a Trova luogo i risultati preferiti in una determinata area. Puoi impostare locationBias nei seguenti modi:

Risultati di bias per un'area specifica:

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

Definisci un'area rettangolare in cui eseguire la ricerca:

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

Puoi anche utilizzare LatLngBounds.

Definisci un raggio da ricercare (in metri), centrato su una determinata area:

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

Richieste di ricerca nelle vicinanze

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

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

Una ricerca di Places nelle vicinanze viene avviata con una chiamata al metodo nearbySearch() di PlacesService, che restituirà 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:

  • Una delle seguenti opzioni:
    • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare; oppure
    • location e radius; la prima accetta un oggetto google.maps.LatLng, mentre la seconda richiede un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri. Tieni presente che quando rankBy è impostato su DISTANZA, 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 alle località all'interno dell'intervallo specificato. I valori validi sono compresi tra 0 (il più economico) e 4 (il più costoso) inclusi.
  • name Deprecata. Equivalente a keyword. I valori di questo campo vengono combinati con quelli del campo keyword e passati nell'ambito della stessa stringa di ricerca.
  • openNow (facoltativo): un valore booleano che indica che il servizio Places deve restituire solo i luoghi aperti all'attività 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 favorirà i luoghi in evidenza all'interno del raggio impostato rispetto ai luoghi nelle vicinanze corrispondenti, ma meno evidenti. L'evidenza può essere influenzata dal ranking di un luogo nell'Indice Google, dalla popolarità a livello globale e da altri fattori. Quando google.maps.places.RankBy.PROMINENCE è specificato, è obbligatorio il parametro radius.
    • 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 bounds e/o un radius personalizzato se specifichi RankBy.DISTANCE. Quando specifichi RankBy.DISTANCE, sono obbligatori uno o più keyword, name o type.
  • type: limita i risultati ai luoghi corrispondenti al tipo specificato. È possibile specificare un solo tipo (se ne viene specificato più di uno, tutti quelli 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 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 Ricerca testuale 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 Ottawa". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e a qualsiasi bias di località impostato. La risposta della ricerca includerà un elenco di luoghi. Puoi inviare una richiesta Dettagli luogo per ulteriori informazioni su qualsiasi luogo 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 cercare, ad esempio: "ristorante" o "Via Roma 123". Deve essere il nome, l'indirizzo o la categoria di luoghi. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca 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.
  • (Facoltativo)
    • openNow: un valore booleano che indica che il servizio Places deve restituire solo i luoghi aperti all'attività 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 alle località all'interno del livello di prezzo specificato. I valori validi sono compresi tra 0 (il più economico) e 4 (il più costoso) inclusi.
    • Una delle seguenti opzioni:
      • bounds: un oggetto google.maps.LatLngBounds che definisce il rettangolo in cui eseguire la ricerca; oppure
      • location e radius: puoi influenzare i risultati a una cerchia specificata passando un parametro location e un 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 è costituito da un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è 50.000 metri.
    • type: limita i risultati ai luoghi corrispondenti al tipo specificato. È possibile specificare un solo tipo (se ne viene specificato più di uno, 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 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 risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug utili per capire perché la richiesta di luogo non è andata a buon fine. I valori di stato possibili sono:

  • INVALID_REQUEST: questa richiesta non è valida.
  • OK: la risposta contiene un risultato valido.
  • OVER_QUERY_LIMIT: la pagina web ha superato la 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 riuscire.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati di ricerca di 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 operativo del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se non esistono dati, non viene restituito business_status.
  • formatted_address è una stringa contenente l'indirizzo leggibile di questo luogo. La proprietà formatted_address viene restituita solo per una ricerca testuale.

    Spesso questo indirizzo equivale 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 è logicamente composto da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

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

  • geometry: informazioni relative alla geometria del luogo. Sono inclusi:
    • location indica la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizzi questo luogo.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo è stato chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato operativo delle attività.
  • plus_code (vedi Open Location Code e i plus code) è un riferimento di località codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000° di grado per 1/8000° di grado (circa 14 x 14 m all'equatore) o inferiore. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (dove gli edifici non sono numerati o le strade non hanno nomi).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    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), può essere restituito solo il codice globale.
  • html_attributions: un array di attribuzioni da mostrare quando si visualizzano i risultati di ricerca. Ogni voce nell'array contiene il testo HTML per una singola attribuzione. Nota: questa è un'aggregazione di tutte le attribuzioni per l'intera risposta della ricerca. Tutti gli oggetti PlaceResult nella risposta contengono pertanto elenchi di attribuzione identici.
  • icon restituisce l'URL di un'icona PNG colorata da 71 x 71 px.
  • icon_mask_base_uri restituisce l'URL di base per un'icona non colorata, senza 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 all'ora corrente (Deprecato nella libreria Places, API Maps JavaScript, utilizza invece utc_offset_minutes).
  • place_id è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare informazioni sul luogo, passa questo identificatore nella richiesta Place 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 a recensioni aggregate degli utenti.
  • types Un array dei tipi di 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 del luogo, che include il nome della via, il numero civico e la località, ma non la provincia/lo stato, il codice postale o il paese. Ad esempio, la sede di Google a Sydney, in 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 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'altra pagina dei risultati.
  • nextPage() una funzione che restituirà il successivo insieme di risultati. Dopo aver eseguito una ricerca, devi attendere due secondi prima che la pagina di risultati successiva sia disponibile.

Per vedere il successivo insieme di risultati, chiama nextPage. Prima di visualizzare la pagina di risultati successiva, deve essere visualizzata ogni pagina 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 inviare più richieste di ricerca.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

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

Prova Sample

Place Details

Oltre a fornire un elenco di luoghi all'interno di un'area, il servizio Places può anche restituire informazioni dettagliate su un luogo specifico. Dopo che un luogo viene restituito in una risposta di ricerca di luoghi, il suo ID luogo può essere utilizzato per richiedere ulteriori dettagli su quel luogo, come l'indirizzo completo, il numero di telefono, la valutazione degli utenti e le recensioni e così via.

Richieste di dettagli del 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 valore 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.

Richiede anche un metodo di callback, che deve gestire il codice di stato trasmesso 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 luogo)

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

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

I campi corrispondono ai risultati di Dettagli luogo e sono suddivisi in tre categorie di fatturazione: Base, Contatto e Ambiente. I campi Basic vengono fatturati alla tariffa di base e non comportano addebiti aggiuntivi. I campi Contatto e Ambiente vengono fatturati a una tariffa superiore. Per ulteriori informazioni, consulta il listino prezzi. Le attribuzioni (html_attributions) vengono sempre restituite a ogni chiamata, indipendentemente dal fatto che siano state richieste.

Basic

La categoria Base include i seguenti campi:
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (deprecata), photo, place_id, plus_code, type, url, utc_offset ({190API/JavaScript ritirata),utc_offset_minutesvicinity

Contatto

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

Risposte sui dettagli del luogo

Codici di stato

L'oggetto risposta PlacesServiceStatus contiene lo stato della richiesta e potrebbe contenere informazioni di debug utili per capire perché la richiesta Place Details non è andata a buon fine. I valori di stato possibili sono:

  • INVALID_REQUEST: questa richiesta non è valida.
  • OK: la risposta contiene un risultato valido.
  • OVER_QUERY_LIMIT: la pagina web ha superato la quota di richieste.
  • NOT_FOUND La località a cui viene fatto 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 riuscire.
  • ZERO_RESULTS: nessun risultato trovato per questa richiesta.

Risultati dettagli 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.

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

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

    Tieni presente quanto segue relativo all'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, escluse quelle incluse in formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, trasmettendo la latitudine/longitudine dell'indirizzo come parametro alla 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 nell'array. Il tipo di componente può cambiare. Un componente specifico potrebbe essere mancante in una risposta successiva.
  • business_status indica lo stato operativo del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se non esistono dati, non viene restituito business_status.
  • formatted_address: l'indirizzo leggibile di questo luogo.

    Spesso questo indirizzo equivale 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 è logicamente composto da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la strada), "New York" (la città) e "NY" (lo stato degli Stati Uniti).

    Non analizzare l'indirizzo formattato in modo programmatico. 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 alla convenzione regionale del numero.
  • geometry: informazioni relative alla geometria del luogo. Sono inclusi:
    • location indica la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando visualizzi questo luogo.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo è stato chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato operativo delle attività.
  • plus_code (vedi Open Location Code e i plus code) è un riferimento di località codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000° di grado per 1/8000° di grado (circa 14 x 14 m all'equatore) o inferiore. I plus code possono essere utilizzati in sostituzione degli indirizzi stradali in luoghi in cui non sono presenti (dove gli edifici non sono numerati o le strade non hanno nomi).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
    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), può essere restituito solo il codice globale.
  • html_attributions: testo dell'attribuzione da visualizzare per questo risultato relativo a questo luogo.
  • icon: URL di 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 di Google a Sydney, in Australia, è +61 2 9374 4000.
  • name: il nome del luogo.
  • utc_offset Deprecato nella libreria Places, nell'API Maps JavaScript, utilizza utc_offset_minutes al suo posto.
  • utc_offset_minutes contiene il numero di minuti in cui il fuso orario attuale di questo luogo è diverso da quello UTC. Ad esempio, per luoghi a Sydney, Australia durante l'ora legale il valore sarà 660 (+11 ore dal fuso UTC), mentre per luoghi della California al di fuori dell'ora legale il valore sarà -480 (-8 ore dal fuso UTC).
  • opening_hours contiene le seguenti informazioni:
    • open_now (deprecato nella libreria Places, nell'API Maps JavaScript; usa invece opening_hours.isOpen(). Guarda questo video per scoprire come utilizzare isOpen con Place Details.) è un valore booleano che indica se il luogo è aperto all'ora corrente.
    • 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 in formato hhmm 24 ore (i valori sono compresi nell'intervallo 0000-2359). L'evento 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 periodo sempre aperto come 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 Place Details è stato specificato un parametro language, il servizio Places formatterà e localizzerà gli orari di apertura in base alla lingua. L'ordine degli elementi in questo array dipende dal parametro language. Alcune lingue iniziano la settimana di lunedì, altre di domenica.
  • permanently_closed (deprecato) è un flag booleano che indica se il luogo è stato chiuso definitivamente o temporaneamente (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato operativo delle attività.
  • photos[]: un array di PlacePhoto oggetti. Puoi utilizzare un elemento PlacePhoto per ottenere una foto con il metodo getUrl() oppure ispezionare 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 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 di dati 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 a recensioni aggregate degli utenti.
  • reviews un array di massimo cinque recensioni. Ogni recensione è composta da diversi componenti:
    • aspects[] contiene un array di oggetti PlaceAspectRating, ciascuno dei quali fornisce una valutazione di un singolo attributo dell'attività. Il primo oggetto dell'array è considerato l'aspetto principale. Ogni PlaceAspectRating è definito come:
      • type il nome dell'aspetto valutato. Sono supportati i seguenti tipi: appeal, atmosphere, decor, facilities, food, overall, quality e service.
      • rating la valutazione dell'utente per questo particolare aspetto, 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+ 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 vengono contrassegnate con il tag "en", non "en-AU" o "en-UK" e così via.
    • rating la valutazione complessiva dell'utente per questo luogo. È un numero intero compreso tra 1 e 5.
    • text la recensione dell'utente. Durante la recensione di una località con Google Places, le recensioni testuali sono considerate facoltative; pertanto, questo campo potrebbe essere vuoto.
  • types Un array dei tipi di 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 Google ufficiale di questo luogo. Questa è la 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 sul luogo.
  • vicinity: un indirizzo semplificato del luogo, che include il nome della via, il numero civico e la località, ma non la provincia/lo stato, il codice postale o il paese. Ad esempio, la sede di Google a Sydney, in 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 ufficiale del luogo, ad esempio la home page di un'attività.

Nota: le classificazioni multidimensionali potrebbero non essere disponibili per tutti i luoghi. Se il numero di recensioni è insufficiente, la risposta relativa ai dettagli includerà una valutazione precedente su una scala da 0,0 a 5,0 (se disponibile) o nessuna valutazione.

Utilizzare il componente Panoramica luogo

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

Prova i componenti web. Utilizza il componente web Panoramica del luogo per ottenere i dettagli del luogo con una rappresentazione visiva.

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

Fare riferimento a un luogo con un ID luogo

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

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

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

Foto del luogo

La funzionalità Place Photo ti consente di aggiungere contenuti fotografici di alta qualità al tuo sito. Il servizio Foto ti permette di accedere a milioni di foto archiviate nel database di Places e Google+ Local. Quando ricevi le informazioni sul luogo tramite una richiesta Dettagli luogo, verranno restituiti i riferimenti fotografici per i contenuti fotografici pertinenti. Le richieste Ricerca nelle vicinanze e Ricerca testuale restituiscono anche un unico riferimento foto per luogo, se pertinente. Utilizzando il servizio Foto, potrai quindi accedere alle foto di riferimento e ridimensionarle fino alle dimensioni ottimali per la tua applicazione.

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

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

  • Una ricerca nelle vicinanze o una ricerca testuale restituirà al massimo un oggetto PlacePhoto.
  • Una richiesta di dettagli 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 ti consente di specificare l'altezza e la larghezza massime dell'immagine. Se specifichi un valore sia per maxHeight sia per maxWidth, il servizio foto ridimensionerà l'immagine in base alle due dimensioni, 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 è 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 le foto dei proprietari di attività e quelle fornite dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione oppure avranno l'attribuzione richiesta inclusa nell'immagine. Tuttavia, se l'elemento photo restituito include un valore nel campo html_attributions, devi includere l'attribuzione aggiuntiva nella tua applicazione ogni volta che mostri l'immagine.