libreria Places

Sviluppatori dello Spazio economico europeo (SEE)

Panoramica

Le funzioni della libreria Places, API Maps JavaScript, consentono alla tua applicazione di cercare luoghi (definiti in questa API come attività, posizioni geografiche o punti d'interesse principali) contenuti in un'area definita, ad esempio i limiti di una mappa o intorno a un punto fisso.

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

Per iniziare

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

Carica la libreria

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 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 saperne di più, consulta la panoramica delle librerie.

Aggiungi l'API Places (legacy) all'elenco delle restrizioni delle API della chiave API

L'applicazione di restrizioni delle API alle chiavi limita l'utilizzo della chiave API a una o più API o SDK. Le richieste a un'API o a un SDK associato alla chiave API verranno elaborate. 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, API Maps JavaScript:
  1. Vai alla console Google Cloud.
  2. Fai clic sul menu a discesa dei progetti 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 chiave.
      • Fai clic su Seleziona API e seleziona sia API Maps JavaScript sia API Places (Legacy).
        (Se una delle API non è elencata, devi abilitarla.)
  6. Fai clic su SALVA.

Limiti di utilizzo e norme

Quote

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

Norme

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

Place Search

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

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

Richieste Find Place (Legacy)

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

Find Place from Query

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

  • query (obbligatorio) La stringa di testo su cui eseguire la ricerca, ad esempio "ristorante" o "123 Main Street". Deve essere un nome di luogo, un indirizzo o una categoria di attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca risultati validi. L'API Places restituirà le corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla loro 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 di ricerca. Può essere uno dei seguenti:
    • Un insieme di coordinate di latitudine/longitudine specificate come LatLngLiteral o oggetto LatLng
    • Limiti rettangolari (due coppie di latitudine/longitudine o un oggetto LatLngBounds)
    • Raggio (in metri) centrato su una latitudine/longitudine

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(), che cerca "Museum of Contemporary Art Australia" e include i campi name e geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 Visualizza esempio

Find Place from Phone Number

Find Place from Phone Number accetta 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 accetta i seguenti parametri:

  • phoneNumber (obbligatorio) Un numero di telefono nel formato E.164.
  • fields (obbligatorio) Uno o più campi che specificano i tipi di dati di Place da restituire.
  • locationBias (facoltativo) Coordinate che definiscono l'area da cercare. Può essere uno dei seguenti:
    • Un insieme di coordinate di latitudine/longitudine specificate come LatLngLiteral o oggetto LatLng
    • Limiti rettangolari (quattro punti di latitudine/longitudine o un oggetto LatLngBounds)
    • Raggio (in metri) centrato su una latitudine/longitudine

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

Campi (metodi Find Place)

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

I campi corrispondono ai risultati di Place Search e sono suddivisi in tre categorie di fatturazione: Basic, Contact e Atmosphere. I campi di base vengono fatturati alla tariffa base e non comportano costi aggiuntivi. I campi Contatto e Atmosfera vengono fatturati a una tariffa più elevata. Per ulteriori informazioni, consulta il prospetto dei prezzi. Le attribuzioni (html_attributions) vengono sempre restituite con ogni chiamata, indipendentemente dal fatto che il campo sia stato richiesto.

Basic

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

Contatto

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

Atmosfera

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

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

Imposta l'influenza della località (metodi Find Place)

Utilizza il parametro locationBias per fare in modo che Find Place dia la priorità ai risultati in un'area specifica. Puoi impostare locationBias nei seguenti modi:

Per orientare i risultati verso un'area specifica:

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

Definisci un'area rettangolare da cercare:

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

Puoi anche utilizzare un LatLngBounds.

Definisci un raggio di ricerca (in metri), centrato su un'area specifica:

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

Richieste di Nearby Search

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

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

Una Nearby Search 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:

  • Uno dei seguenti:
    • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare. La distanza diagonale massima supportata per l'area dei limiti è di circa 100.000 metri.
    • un location e un radius; il primo accetta un oggetto google.maps.LatLng, mentre il secondo accetta 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 DISTANCE, devi specificare un location, ma non puoi specificare un radius o un bounds.
  • keyword (facoltativo): un termine da confrontare con tutti i campi disponibili, inclusi, a titolo esemplificativo, nome, tipo e indirizzo, nonché recensioni dei clienti e altri contenuti di terze parti.
  • minPriceLevel e maxPriceLevel (facoltativo): limita i risultati solo ai luoghi compresi nell'intervallo specificato. I valori validi sono compresi tra 0 (più economico) e 4 (più costoso) inclusi.
  • name Deprecato. Equivalente a keyword. I valori in questo campo vengono combinati con i valori nel campo keyword e trasmessi come parte della stessa stringa di ricerca.
  • openNow (facoltativo): un valore booleano che indica che il servizio Places deve restituire solo i luoghi aperti 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 di rilievo all'interno del raggio impostato rispetto ai luoghi nelle vicinanze che corrispondono, ma che sono meno importanti. L'importanza può essere influenzata dal ranking di un luogo nell'indice di Google, dalla popolarità globale e da altri fattori. Quando viene specificato google.maps.places.RankBy.PROMINENCE, il parametro radius è obbligatorio.
    • google.maps.places.RankBy.DISTANCE. Questa opzione ordina i risultati in ordine crescente in base alla distanza dal valore location specificato (obbligatorio). Tieni presente che non puoi specificare un bounds e/o un radius personalizzati se specifichi RankBy.DISTANCE. Quando specifichi RankBy.DISTANCE, è obbligatorio uno o più dei seguenti valori: keyword, name o type.
  • type: limita i risultati ai luoghi corrispondenti al tipo specificato. Può essere specificato un solo tipo (se ne vengono forniti 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 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 di Google Places è un servizio web che restituisce informazioni su un insieme di luoghi in base a una stringa, ad esempio "pizza a New York" o "negozi di scarpe vicino a Ottawa". Il servizio risponde con un elenco di luoghi corrispondenti alla stringa di testo e a qualsiasi bias di località impostato. La risposta alla ricerca includerà un elenco di luoghi. Puoi inviare una richiesta Place Details per ulteriori informazioni su uno dei luoghi nella risposta.

Le ricerche testuali 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 "123 Main Street". Deve essere un nome di luogo, un indirizzo o una categoria di attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituisca risultati validi. Il servizio Places restituirà le corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla loro pertinenza percepita. Questo parametro diventa facoltativo se nella richiesta di ricerca viene utilizzato anche il parametro type.
  • (Facoltativo)
    • openNow: un valore booleano che indica che il servizio Places deve restituire solo i luoghi aperti al momento dell'invio della query. I luoghi che non specificano l'orario di apertura nel database di Google Places non verranno restituiti se includi questo parametro nella query. L'impostazione di openNow su false non ha alcun effetto.
    • minPriceLevel e maxPriceLevel: limita i risultati solo ai luoghi che rientrano nel livello di prezzo specificato. I valori validi sono compresi nell'intervallo tra 0 (più economico) e 4 (più costoso) inclusi.
    • Uno dei seguenti:
      • bounds, che deve essere un oggetto google.maps.LatLngBounds che definisce l'area di ricerca rettangolare. La distanza diagonale massima supportata per l'area dei limiti è di circa 100.000 metri.
      • location e radius: puoi influenzare i risultati in base a un cerchio specificato passando un parametro location e un parametro radius. In questo modo, il servizio Places mostrerà preferibilmente i risultati all'interno di quel cerchio. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. La posizione accetta un oggetto google.maps.LatLng e il raggio accetta un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è di 50.000 metri.
    • type: limita i risultati ai luoghi corrispondenti al tipo specificato. È possibile specificare un solo tipo (se vengono forniti più tipi, tutti quelli 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]);
    }
  }
}

Risposte di ricerca

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a individuare il motivo per cui 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. La richiesta potrebbe andare a buon fine se riprovi.
  • ZERO_RESULTS: non è stato trovato alcun risultato per questa richiesta.

Risultati di Place Search

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

Ogni oggetto PlaceResult può includere le seguenti proprietà:

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

    Spesso questo indirizzo corrisponde all'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 è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la 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: le informazioni relative alla geometria del luogo. Sono inclusi:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando si visualizza questo luogo.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato di attività delle attività.
  • plus_code (vedi Open Location Code e Plus Code) è un riferimento di posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione degli indirizzi nei luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno sei 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), potrebbe essere restituito solo il codice globale.
  • html_attributions: un array di attribuzioni da mostrare quando vengono visualizzati i risultati di ricerca. Ogni voce dell'array contiene il testo HTML per una singola attribuzione. Nota: Questa è un'aggregazione di tutte le attribuzioni per l'intera risposta di ricerca. Tutti gli oggetti PlaceResult nella risposta contengono quindi elenchi di attribuzione identici.
  • icon restituisce l'URL di un'icona PNG colorata di 71 x 71 px.
  • icon_mask_base_uri restituisce l'URL di base di 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 al momento (ritirato nella libreria Places, API Maps JavaScript, utilizza 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 alle 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 o essere vuoto. Nuovi valori potrebbero 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, l'ufficio di Google a Sydney, in Australia, ha un valore vicinity di 5/48 Pirrama Road, Pyrmont.

Accedi a risultati aggiuntivi

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

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

Per visualizzare il successivo insieme di risultati, chiama nextPage. Ogni pagina di risultati deve essere visualizzata prima di mostrare la pagina di risultati successiva. 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

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. Una volta restituito un luogo in una risposta di Place Search, il suo ID luogo può essere utilizzato per richiedere ulteriori dettagli su quel luogo, ad esempio l'indirizzo completo, il numero di telefono, la valutazione degli utenti, le recensioni e così via.

Richieste Place Details

I Place Details 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 l'placeId di un luogo e i campi che indicano i tipi di dati di Places da restituire. Scopri di più su come fare riferimento a un luogo con un ID luogo.

Inoltre, accetta un metodo di callback, che deve gestire il codice di stato passato nella risposta google.maps.places.PlacesServiceStatus, nonché l'oggetto google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Visualizza esempio

Campi (Place Details)

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

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

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

Basic

La categoria Basic include i seguenti campi:
address_components, 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 (deprecato nella libreria Places, API Maps JavaScript), utc_offset_minutes, vicinity

Contatto

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

Atmosfera

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

Scopri di più sui campi dei luoghi. Per saperne di più sulla fatturazione delle richieste di dati di Place, consulta Utilizzo e fatturazione.

Risposte di Place Details

Codici di stato

L'oggetto di risposta PlacesServiceStatus contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a individuare il motivo per cui 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à 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. La richiesta potrebbe andare a buon fine se riprovi.
  • ZERO_RESULTS: non è stato trovato alcun risultato per questa richiesta.

Risultati di Place Details

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

  • address_components: Un array contenente i singoli componenti applicabili a questo indirizzo.

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

    • types[] è un array che indica il tipo del componente dell'indirizzo. Il componente dell'indirizzo potrebbe avere un array di tipi vuoto se non esistono tipi noti per quel componente dell'indirizzo. L'API potrebbe aggiungere nuovi valori di tipo in base alle esigenze. Per saperne di più, consulta Tipi di indirizzi e tipi di componenti degli indirizzi.
    • long_name è il nome o la descrizione testuale completa del componente dell'indirizzo restituito dal geocodificatore.
    • short_name è un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere un long_name "Alaska" e un short_name "AK" utilizzando l'abbreviazione postale di 2 lettere.

    Tieni presente quanto segue sull'array address_components[]:

    • L'array di componenti dell'indirizzo può contenere più componenti rispetto a formatted_address.
    • L'array non include necessariamente tutte le entità politiche che contengono un indirizzo, ad eccezione di quelle incluse in formatted_address. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi utilizzare la geocodifica inversa, passando la latitudine/longitudine dell'indirizzo come parametro alla richiesta.
    • Non è garantito che il formato della risposta rimanga 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 posizione nell'array. Il tipo di componente può cambiare. Un determinato componente potrebbe non essere presente in una risposta successiva.
  • business_status indica lo stato di attività del luogo, se si tratta di un'attività. Può contenere uno dei seguenti valori:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se non esistono dati, business_status non viene restituito.
  • formatted_address: l'indirizzo leggibile di questo luogo.

    Spesso questo indirizzo corrisponde all'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 è composto logicamente da uno o più componenti dell'indirizzo. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è composto dai seguenti componenti: "111" (il numero civico), "8th Avenue" (la 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: le informazioni relative alla geometria del luogo. Sono inclusi:
    • location fornisce la latitudine e la longitudine del luogo.
    • viewport definisce l'area visibile preferita sulla mappa quando si visualizza questo luogo.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato di attività delle attività.
  • plus_code (vedi Open Location Code e Plus Code) è un riferimento di posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione degli indirizzi nei luoghi in cui non esistono (dove gli edifici non sono numerati o le strade non hanno un nome).

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

    • global_code è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).
    • compound_code è un codice locale di almeno sei 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), potrebbe essere restituito solo il codice globale.
  • html_attributions: testo dell'attribuzione da visualizzare per questo risultato del 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 l'ufficio di Google a Sydney, in Australia, è +61 2 9374 4000.
  • name: il nome del luogo.
  • utc_offset Ritirato nella libreria Places, API Maps JavaScript, utilizza utc_offset_minutes.
  • utc_offset_minutes contiene il numero di minuti di differenza tra il fuso orario attuale di questo luogo e l'ora UTC. Ad esempio, per i luoghi di Sydney, in Australia, durante l'ora legale, questo valore sarà 660 (+11 ore rispetto all'ora UTC), mentre per i luoghi della California al di fuori dell'ora legale, questo valore sarà -480 (-8 ore rispetto all'ora UTC).
  • opening_hours contiene le seguenti informazioni:
    • open_now (ritirato nella libreria Places, API Maps JavaScript; utilizza opening_hours.isOpen(). Per scoprire come utilizzare isOpen con Place Details, guarda il video Come ottenere gli orari di apertura nell'API Places (Legacy) .) "open_now" è un valore booleano che indica se il luogo è aperto al momento.
    • periods[] è un array di periodi di apertura che copre sette giorni, a partire da domenica, in ordine cronologico. Ogni periodo contiene:
      • open contiene una coppia di oggetti giorno e ora che descrivono l'orario di apertura del luogo:
        • day un numero compreso tra 0 e 6, corrispondente ai giorni della settimana, a partire dalla domenica. Ad esempio, 2 indica martedì.
        • time può contenere un'ora del giorno nel formato hhmm a 24 ore (i valori sono compresi nell'intervallo 0000-2359). time verrà registrato nel fuso orario del luogo.
      • close può contenere una coppia di oggetti giorno e ora che descrivono l'orario di chiusura del luogo. Nota: se un luogo è sempre aperto, la sezione close non sarà presente nella risposta. Le applicazioni possono fare affidamento sul fatto che l'apertura continua è rappresentata da un periodo open contenente day con valore 0 e time con valore 0000, senza close.
    • weekday_text è un array di sette stringhe che rappresentano l'orario di apertura formattato per ogni giorno della settimana. Se nella richiesta di Place Details è stato specificato un parametro language, il servizio Places formatterà e localizzerà l'orario di apertura in modo appropriato per la lingua in questione. L'ordine degli elementi in questo array dipende dal parametro language. In alcune lingue la settimana inizia di lunedì, mentre in altre inizia di domenica.
  • permanently_closed (ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valore true). Non utilizzare permanently_closed. Utilizza invece business_status per ottenere lo stato di attività delle attività.
  • photos[]: un array di oggetti PlacePhoto. Un PlacePhoto può essere utilizzato per ottenere una foto con il metodo getUrl() oppure puoi ispezionare l'oggetto per i seguenti valori:
    • height: l'altezza massima dell'immagine, in pixel.
    • width: la larghezza massima dell'immagine, in pixel.
    • html_attributions: testo dell'attribuzione da visualizzare con 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 utilizzando una richiesta Place Details. Scopri di più su come fare riferimento a un luogo con un ID luogo.
  • rating: la valutazione del luogo, da 0,0 a 5,0, in base alle recensioni aggregate degli utenti.
  • reviews un array di massimo cinque recensioni. Ogni revisione è composta da diversi componenti:
    • aspects[] contiene un array di oggetti PlaceAspectRating, ognuno 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 che viene valutato. Sono supportati i seguenti tipi: appeal, atmosphere, decor, facilities, food, overall, quality e service.
      • rating: la valutazione dell'utente per questo aspetto specifico, da 0 a 3.
    • author_name il nome dell'utente che ha inviato la recensione. Le recensioni anonime vengono attribuite a "Un utente Google". Se è stato impostato un parametro di lingua, la frase "Un utente Google" restituirà una stringa localizzata.
    • author_url l'URL del profilo Google+ 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 la regione. Ad esempio, tutte le recensioni in inglese sono taggate come "en" e non "en-AU" o "en-UK".
    • rating la valutazione complessiva dell'utente per questo luogo. Questo è un numero intero compreso tra 1 e 5.
    • text la recensione dell'utente. Quando si recensisce una località 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 o essere vuoto. Nuovi valori potrebbero 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 collegarsi 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, l'ufficio 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 Nearby.
  • website elenca il sito web autorevole per questo luogo, ad esempio la home page di un'attività.

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

Fai riferimento a un luogo con un ID luogo

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

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

Gli ID luogo sono esenti dalle limitazioni di memorizzazione nella cache indicate nella Sezione 3.2.3(b) dei Termini di servizio di Google Maps Platform. Pertanto, puoi memorizzare i valori degli ID luogo per utilizzarli in un secondo momento. Per le best practice per l'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);

Place Photos

Utilizza la funzionalità Foto dei luoghi per aggiungere contenuti fotografici di alta qualità al tuo sito. Il servizio Photo ti consente di accedere ai milioni di foto archiviate nel database di Places e Google+ Local. Quando ricevi informazioni su un luogo utilizzando una richiesta Place Details, vengono restituiti riferimenti alle foto per i contenuti fotografici pertinenti. Le richieste di Nearby Search e Ricerca testuale restituiscono anche un singolo riferimento foto per luogo, se pertinente. Utilizzando il servizio Photo, puoi accedere alle foto di riferimento e ridimensionare l'immagine alle dimensioni ottimali per la tua applicazione.

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

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

  • Una ricerca Nearby Search o una Ricerca testuale restituirà al massimo un oggetto PlacePhoto.
  • Una richiesta di dettagli restituirà fino a dieci oggetti PlacePhoto.

Puoi richiedere l'URL dell'immagine associata chiamando il metodo PlacePhoto.getUrl() e passando un oggetto PhotoOptions valido. Utilizza l'oggetto PhotoOptions per specificare l'altezza e la larghezza massime dell'immagine. Se specifichi un valore sia per maxHeight che per maxWidth, il servizio fotografico ridimensionerà l'immagine alla dimensione più piccola delle due, 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 predefinita dell'indicatore viene sostituita da una versione ridotta della foto.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

Le foto restituite dal servizio Photo provengono da diverse fonti, tra cui i proprietari delle attività e le foto caricate dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o l'attribuzione richiesta verrà inclusa nell'immagine. Tuttavia, se l'elemento photo restituito include un valore nel campo html_attributions, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque mostri l'immagine.