Panoramica
Le funzioni nella libreria Places, nell'API Maps JavaScript consentono la tua applicazione per cercare luoghi (definiti in questa API come stabilimenti, località o punti di interesse di rilievo) contenuti in un'area definita, come i confini di una mappa o intorno a un punto fisso.
L'API Places offre una funzione di completamento automatico che puoi utilizzare per dare alle tue applicazioni il comportamento type-ahead-search di Google Maps campo di ricerca. Quando un utente inizia a digitare un indirizzo, il completamento automatico e riempi il resto. Per ulteriori informazioni, consulta completamento automatico documentazione.
Per iniziare
Se non hai dimestichezza con l'API Maps JavaScript o con JavaScript, ti consigliamo di consultare Ottenere una chiave API prima per iniziare.
Abilita API
Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata nella console Google Cloud, nella stessa configurato per l'API Maps JavaScript.
Per visualizzare l'elenco delle API abilitate:
- Vai alla sezione Console Google Cloud.
- Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai configurato. per l'API Maps JavaScript e fai clic su Apri.
- Nell'elenco delle API sulla Dashboard, cerca API Places.
- Se nell'elenco vedi l'API Places, significa che è già abilitata. Se l'API
non è elencato, abilitalo:
- Nella parte superiore della pagina, seleziona ABILITA API E SERVIZI per visualizzare i campi Scheda Raccolta. In alternativa, dal menu laterale a sinistra, Seleziona Libreria.
- Cerca API Places e selezionala dalla dei risultati di ricerca.
- Seleziona ABILITA. Al termine del processo, L'API Places viene visualizzata nell'elenco delle API nella Dashboard.
Caricamento della libreria in corso...
Il servizio Places è una libreria indipendente, separata dalla piattaforma
Codice dell'API Maps JavaScript. Per utilizzare la funzionalità contenuta
all'interno di questa libreria, devi prima caricarla utilizzando l'libraries
nell'URL del bootstrap dell'API di Google Maps:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Consulta Panoramica delle librerie.
Aggiungi l'API Places all'elenco delle limitazioni API della chiave API
L'applicazione di restrizioni API alle chiavi limita l'utilizzo della chiave API a uno o più API o SDK. Le richieste a un'API o a un SDK associati alla chiave API essere elaborati. Le richieste a un'API o a un SDK non associati alla chiave API non riuscito. Per limitare l'utilizzo di una chiave API con Places Library, l'API Maps JavaScript:- Vai alla console Google Cloud.
- Fai clic sul menu a discesa del progetto e seleziona il progetto che contiene Chiave API che vuoi proteggere.
- Fai clic sul pulsante di menu
e seleziona Google Maps Platform > Credenziali.
- Nella pagina Credenziali, fai clic sul nome dell'API chiave che vuoi proteggere.
- Nella pagina Limita e rinomina la chiave API, imposta le limitazioni:
- Restrizioni delle API
- Seleziona Limita chiave.
- Fai clic su Seleziona API e seleziona sia l'API Maps JavaScript sia l'API Places.
Se una delle API non è presente nell'elenco, devi abilitarla.
- Fai clic su SALVA.
Limiti e norme di utilizzo
Quote
La libreria di Places condivide una quota di utilizzo con API Places come descritto nella documentazione sui limiti di utilizzo per API Places.
Norme
L'utilizzo dell'API Places Library, Maps JavaScript deve essere conforme ai norme descritte per l'API Places.
Ricerche di luoghi
Con il servizio Places puoi effettuare i seguenti tipi di ricerche:
- Trova luogo dalla query restituisce un luogo in base a una query di testo (ad esempio, il nome o l'indirizzo di un luogo).
- Trova un luogo dal telefono Numero restituisce un luogo in base a un numero di telefono.
- Ricerca nelle vicinanze restituisce un elenco di luoghi nelle vicinanze in base alla posizione dell'utente.
- Ricerca testuale restituisce un elenco di luoghi nelle vicinanze in base a una stringa di ricerca, ad esempio "Pizza".
- Richieste Place Details restituire informazioni più dettagliate su un luogo specifico, tra cui: recensioni degli utenti.
Le informazioni restituite possono includere attività, ad esempio ristoranti, negozi e uffici, nonché il 'codici geografici' di risultati, che indicare indirizzi, aree politiche come città e altri punti d'interesse.
Richieste Trova luogo
Una richiesta Trova luogo ti consente di cercare un luogo tramite query di testo o numero di telefono. Esistono due tipi di richiesta Trova luogo:
Trova luogo dalla query
Trova luogo dalla query richiede un input di testo e restituisce un luogo. L'input può
essere qualsiasi tipo di dati dei luoghi, ad esempio il nome o l'indirizzo di un'attività commerciale. Per creare un
Trova luogo dalla richiesta Query, chiama il PlacesService
findPlaceFromQuery()
, che accetta i seguenti parametri:
query
(obbligatorio) La stringa di testo in cui eseguire la ricerca, esempio: "ristorante" o "Via Cavour 123". Deve essere il nome di un luogo, l'indirizzo o la categoria di attività. Qualsiasi altro tipo di input può generare errori e non è garantito che restituiscano risultati validi. API Places restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla percezione della loro pertinenza.fields
(obbligatorio) Uno o più campi che specifica i tipi di dati dei luoghi da restituire.locationBias
(Facoltativo) Coordinate che definiscono l'area da cercare. Può essere uno dei seguenti:- Un insieme di coordinate di latitudine/longitudine specificate come LatLngLiteral o oggetto LatLng
- Limiti rettangolari (due coppie lat/lng o un oggetto LatLngBounds)
- Raggio (in metri) centrato su latitudine/longitudine
Devi anche passare un metodo di callback a findPlaceFromQuery()
,
per gestire l'oggetto dei risultati e google.maps.places.PlacesServiceStatus
risposta.
L'esempio seguente mostra una chiamata a findPlaceFromQuery()
,
ha cercato "Museum of Contemporaneo Art Australia" e ha incluso
name
e geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }Visualizza esempio
Trova luogo dal numero di telefono
Trova luogo da numero di telefono prende un numero di telefono e restituisce un luogo. A
per effettuare una richiesta Trova luogo dal numero di telefono, chiama
findPlaceFromPhoneNumber()
di PlacesService
, che accetta i seguenti parametri:
phoneNumber
(obbligatorio) Un numero di telefono nel formato E.164.fields
(obbligatorio) Uno o più campi che specifica i tipi di dati dei luoghi da restituire.- (Facoltativo)
locationBias
Coordinate che definiscono l'area da eseguire una ricerca. I valori possono essere:- Un insieme di coordinate di latitudine/longitudine specificate come LatLngLiteral o oggetto LatLng
- Limiti rettangolari (quattro punti latitudine/longitudine oppure un oggetto LatLngBounds)
- Raggio (in metri) centrato su latitudine/longitudine
Devi anche passare un metodo di callback a findPlaceFromPhoneNumber()
,
per gestire l'oggetto dei risultati e google.maps.places.PlacesServiceStatus
risposta.
Campi (metodi Trova luogo)
Utilizza il parametro fields
per specificare un array di tipi di dati dei luoghi da restituire.
Ad esempio: fields: ['formatted_address', 'opening_hours', 'geometry']
.
Utilizza un punto quando specifichi i valori composti. Ad esempio: opening_hours.weekday_text
.
I campi corrispondono ai risultati di Ricerca di luoghi e sono divisi
in tre categorie di fatturazione: Base, Contatto e Ambiente. I campi di base sono
fatturati alla tariffa di base e non ci sono costi aggiuntivi. Contatti e atmosfera
vengono fatturati a una tariffa superiore. Consulta il listino prezzi
per ulteriori informazioni. Le attribuzioni (html_attributions
) sono sempre
viene restituito a ogni chiamata, indipendentemente dal fatto che il campo sia stato
richiesto.
Basic
La categoria Base include i seguenti campi:
business_status
, formatted_address
, geometry
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(deprecato),
photos
, place_id
, plus_code
e types
Contatto
La categoria Contatto include il seguente campo:opening_hours
(ritirato nella Places Library, nell'API Maps JavaScript. Utilizza una richiesta Place Details per ottenere
opening_hours
risultati).
Atmosfera
La categoria Atmosfera include i seguenti campi:price_level
, rating
e user_ratings_total
Le findPlaceFromQuery()
e
findPlaceFromPhoneNumber()
metodi utilizzano ciascuno lo stesso insieme
e può restituire gli stessi campi nelle rispettive risposte.
Impostare la differenziazione della località (metodi Trova luogo)
Utilizza il parametro locationBias
per ottenere risultati preferiti in Trova luogo
in una determinata area. Puoi impostare locationBias
in quanto segue
modi:
Risultati bias relativi a un'area specifica:
locationBias: {lat: 37.402105, lng: -122.081974}
Definisci un'area rettangolare in cui eseguire la ricerca:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Puoi anche utilizzare un campo LatLngBounds.
Definisci il raggio di ricerca (in metri), centrato su una determinata area:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
Richieste di ricerca nelle vicinanze
Una ricerca nelle vicinanze ti consente di cercare luoghi all'interno di un'area specifica tramite: parola chiave o tipo. Una ricerca nelle vicinanze deve sempre includere una località, che può essere possono essere specificate in uno dei due modi seguenti:
- un
LatLngBounds
. - un'area circolare definita come la combinazione di
location
: specifica il centro del cerchio comeLatLng
oggetto e un raggio misurato in metri.
Viene avviata una ricerca di luoghi nelle vicinanze con una chiamata al
Il metodo nearbySearch()
di
PlacesService
, che
restituiscono un array di
PlaceResult
. Tieni presente che nearbySearch()
sostituisce il metodo search()
a partire dalla versione 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
Questo metodo accetta una richiesta con i seguenti campi:
- Una di queste opzioni:
bounds
, che deve essere ungoogle.maps.LatLngBounds
l'oggetto che definisce il rettangolo nell'area di ricerca. La distanza diagonale massima supportata per i limiti è di circa 100.000 metri.- un
location
e unradius
; la prima prende ungoogle.maps.LatLng
e il secondo utilizza una semplice numero intero, che rappresenta il raggio del cerchio in metri. Il valore massimo consentito è di 50.000 metri. Tieni presente che quandorankBy
è impostato su DISTANZA, devi specificare un valorelocation
ma non puoi specificare unradius
obounds
.
keyword
(facoltativo): un termine da abbinare in tutti i campi disponibili, inclusi, a titolo esemplificativo, name, type e indirizzo, nonché recensioni dei clienti e altri contenuti di terze parti.minPriceLevel
emaxPriceLevel
(Facoltativo) - Limita i risultati solo alle posizioni all'interno di per l'intervallo specificato. Intervallo di valori validi compreso tra 0 (il più conveniente) a 4 (il più costoso), inclusivo.name
Obsoleta. Equivalente akeyword
. Valori in questo campo vengono combinati con i valori del campokeyword
e passati come parte della stessa stringa di ricerca.openNow
(facoltativo): un valore booleano, indicando che il servizio Places deve restituire solo i luoghi che sono aperte al momento dell'invio della query. Luoghi che non specificare gli orari di apertura nel database di Google Places non verranno se includi questo parametro nella query. Impostazione DaopenNow
afalse
non ha alcun effetto.rankBy
(facoltativo): specifica l'ordine in i risultati visualizzati. I valori possibili sono:google.maps.places.RankBy.PROMINENCE
(valore predefinito). Questo ordina i risultati in base alla loro importanza. Il ranking dai la priorità ai luoghi più prominenti all'interno del raggio impostato rispetto alle vicinanze luoghi corrispondenti, ma meno visibili. L'evidenza può essere influenzati dal ranking di un luogo nell'indice di Google, dalla popolarità globale, e altri fattori. Quandogoogle.maps.places.RankBy.PROMINENCE
è specificato, il parametroradius
è obbligatorio.google.maps.places.RankBy.DISTANCE
. Questa opzione ordina i risultati in ordine crescente in base alla loro distanza dallocation
(obbligatorio). Tieni presente che non puoi specificarebounds
e/oradius
personalizzati se specificareRankBy.DISTANCE
. Se specifichiRankBy.DISTANCE
, uno o più dikeyword
,name
otype
sono obbligatorio.
type
: limita il tra i risultati in posizioni corrispondenti al tipo specificato. È possibile specificare un solo tipo specificato (se viene fornito più di un tipo, tutti i tipi successivi al primo vengono ignorate). Consulta l'elenco di tipi supportati.
Devi anche passare un metodo di callback a nearbySearch()
per
e gestire l'oggetto dei risultati
Risposta google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
Richieste di ricerca testuale
Il servizio di ricerca testuale di Google Places è un servizio web che restituisce informazioni su un insieme di posizioni basate su una stringa, ad esempio "pizza a Roma" o "negozi di scarpe vicino a Roma". Il servizio risponde un elenco di luoghi corrispondenti alla stringa di testo e gli eventuali bias di località è stata configurata. La risposta della ricerca includerà un elenco di luoghi. Puoi inviare Richiesta Dettagli luogo per ulteriori informazioni su qualsiasi luogo nel risposta.
Le ricerche di testo vengono avviate con una chiamata al
Metodo textSearch()
di PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Questo metodo accetta una richiesta con i seguenti campi:
query
(obbligatorio) La stringa di testo su cui cerca, ad esempio: "ristorante" o "Via Cavour 123". Deve essere un luogo nome, indirizzo o categoria di attività. Qualsiasi altro tipo di input può generano errori e non è garantito che restituiscano risultati validi. I luoghi restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla percezione della loro pertinenza. Questo parametro diventa facoltativo se il parametrotype
viene utilizzato anche nella richiesta di ricerca.- Facoltativamente:
openNow
: un valore booleano, indicando che il servizio Places deve restituire solo i luoghi che sono aperte al momento dell'invio della query. Luoghi che non specificare gli orari di apertura nel database di Google Places non verranno se includi questo parametro nella query. Impostazione DaopenNow
afalse
non ha alcun effetto.minPriceLevel
emaxPriceLevel
- Limita i risultati solo alle posizioni all'interno di al livello di prezzo specificato. I valori validi sono compresi nell'intervallo 0 (il più conveniente) a 4 (il più costoso), inclusivo.- Una di queste opzioni:
bounds
, che deve essere ungoogle.maps.LatLngBounds
l'oggetto che definisce il rettangolo nell'area di ricerca. La distanza diagonale massima supportata per i limiti è di circa 100.000 metri.location
eradius
. Puoi polarizza i risultati a una circonferenza specificata passandolocation
e un parametroradius
. In questo modo indica al servizio Places di preferire la visualizzazione dei risultati cerchio. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. La posizione accetta un oggettogoogle.maps.LatLng
e il raggio prende un numero intero semplice, che rappresenta il raggio del cerchio in metri. Il raggio massimo consentito è 50.000 metri.
type
: limita i risultati ai luoghi corrispondenti del tipo specificato. È possibile specificare un solo tipo (se più di uno) viene specificato, tutti i tipi successivi alla prima vengono ignorati). Consulta: l'elenco dei tipi supportati.
Devi anche passare un metodo di callback a textSearch()
per
per gestire l'oggetto dei risultati
Risposta google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
Cerca risposte
Codici di stato
L'oggetto risposta PlacesServiceStatus
contiene lo stato di
la richiesta e potrebbero contenere informazioni di debug per aiutarti a rintracciare
perché la richiesta di luogo non è andata a buon fine. I valori di stato possibili sono:
INVALID_REQUEST
: questa richiesta non è valida.OK
: la risposta contiene un risultato valido.OVER_QUERY_LIMIT
: la pagina web ha superato la sua richiesta quota.REQUEST_DENIED
: la pagina web non è autorizzata a utilizzare i PlacesService.UNKNOWN_ERROR
: impossibile inviare la richiesta PlacesService elaborati a causa di un errore del server. Riprova.ZERO_RESULTS
: nessun risultato trovato per questa richiesta.
Risultati di ricerca di luoghi
findPlace()
, nearbySearch()
e
Le funzioni textSearch()
restituiscono un array di
PlaceResult
di oggetti.
Ogni oggetto PlaceResult
può includere le seguenti proprietà:
business_status
indica l'operatività del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti i seguenti valori:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
non viene restituito.formatted_address
è una stringa contenente la stringa leggibile di questo luogo. La proprietàformatted_address
è solo per una ricerca testuale.Spesso, questo indirizzo equivale all'indirizzo postale. Tieni presente che alcune paesi, come il Regno Unito, non consentono la distribuzione di veri e propri indirizzi postali a causa di limitazioni di licenza.
L'indirizzo formattato è logicamente composto da uno o più indirizzi componenti. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (stato USA).
Non analizzare l'indirizzo formattato in modo programmatico. Dovresti invece usare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta nel campo dell'indirizzo formattato.
geometry
: informazioni relative alla geometria del luogo. Questo include:location
fornisce la latitudine e la longitudine posto.viewport
definisce l'area visibile preferita sulla mappa quando visualizza questo luogo.
permanently_closed
(ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valoretrue
). Non utilizzarepermanently_closed
. Usa invecebusiness_status
per conoscere lo stato di attività delle aziende.plus_code
(vedi Apri codice posizione e plus code) è un riferimento a una posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione di indirizzi in luoghi in cui non esistono (in cui gli edifici non sono numerati o le vie non hanno un nome).Il Plus Code è formattato come codice globale e codice composto:
global_code
è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).compound_code
è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
html_attributions
: un array di attribuzioni che dovresti durante la visualizzazione dei risultati di ricerca. Ogni voce dell'array contiene il testo HTML di una singola attribuzione. Nota: questa è una l'aggregazione di tutte le attribuzioni per l'intera risposta della ricerca. TuttiPlaceResult
oggetti nella risposta contengono quindi elenchi di attribuzioni identici.icon
restituisce l'URL per un'icona PNG a colori da 71 x 71 px.icon_mask_base_uri
restituisce l'URL di base per un elemento non colorato , meno l'estensione .svg o .png.icon_background_color
restituisce il codice colore esadecimale predefinito per la categoria del luogo.name
: il nome del luogo.opening_hours
può contenere le seguenti informazioni:open_now
è un valore booleano che indica se il luogo è aperto al momento (deprecato in Places Library, API Maps JavaScript, usautc_offset_minutes
).
place_id
è un identificatore testuale che identifica in modo univoco un posto. Per recuperare informazioni sul luogo, passa questo identificatore nella Dettagli luogo richiesta. Scopri di più su come fare riferimento a un luogo con un ID luogo.rating
contiene la valutazione del luogo, da 0,0 a 5,0, in base sulla base di recensioni aggregate degli utenti.types
Un array di tipi per questo luogo (ad es.["political", "locality"]
o["restaurant", "lodging"]
). Questo array può contenere più valori oppure vuoto. È possibile che vengano introdotti nuovi valori senza preavviso. Consulta l'elenco di tipi supportati.vicinity
: un indirizzo semplificato del luogo, che include: il nome della via, il numero civico e la località, ma non i provincia/stato, codice postale o paese. Ad esempio, Google's Sydney, La sede dell'Australia ha un valore divicinity
pari a5/48 Pirrama Road, Pyrmont
.
Accesso a risultati aggiuntivi
Per impostazione predefinita, la ricerca di ogni luogo restituisce fino a 20 risultati per query. Tuttavia,
ogni ricerca può restituire fino a 60 risultati, suddivisi in tre pagine.
Pagine aggiuntive sono disponibili tramite PlaceSearchPagination
. Per accedere a pagine aggiuntive, devi acquisire i campi
PlaceSearchPagination
tramite una funzione di callback. La
L'oggetto PlaceSearchPagination
è definito come:
hasNextPage
è una proprietà booleana che indica se ulteriormente disponibili i risultati.true
quando è presente un ulteriore pagina dei risultati.nextPage()
una funzione che restituirà il set successivo di che consentono di analizzare i dati e visualizzare i risultati. Dopo aver eseguito una ricerca, devi attendere secondi prima che sia disponibile la pagina successiva di risultati.
Per visualizzare la serie di risultati successiva, chiama nextPage
.
Ogni pagina di risultati deve essere visualizzata prima che venga visualizzata la pagina successiva di
che consentono di analizzare i dati
e visualizzare i risultati. Tieni presente che ogni ricerca viene conteggiata come una singola richiesta nei confronti del tuo
limiti di utilizzo.
L'esempio seguente mostra come modificare la funzione di callback in
acquisire l'oggetto PlaceSearchPagination
, in modo da poter inviare
più richieste di ricerca.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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;
Prova Sample
Place Details
Oltre a fornire un elenco di luoghi all'interno di un'area, i luoghi può anche restituire informazioni dettagliate su un luogo specifico. Una volta che un luogo è stato restituito in una risposta di ricerca di un luogo, L'ID luogo può essere utilizzato per richiedere ulteriori dettagli sul luogo, come l'indirizzo completo, il numero di telefono, la valutazione degli utenti e recensioni, ecc.
Richieste Place Details
I dettagli sul luogo vengono richiesti con una chiamata al
getDetails()
.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Questo metodo accetta una richiesta, contenente i dati del luogo
placeId
e i campi che indicano i tipi di dati di Places
da restituire. Scopri di più su
come fare riferimento a un luogo con un ID luogo.
Prende anche un metodo di callback, che deve gestire il codice di stato passato
nella risposta google.maps.places.PlacesServiceStatus
.
come oggetto google.maps.places.PlaceResult
.
var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] }; service = new google.maps.places.PlacesService(map); service.getDetails(request, callback); function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }
Campi (Dettagli luogo)
Il parametrofields
accetta un array di stringhe (nomi di campo).
Utilizza il parametro fields
per specificare un array di tipi di dati dei luoghi da restituire.
Ad esempio: fields: ['address_components', 'opening_hours', 'geometry']
.
Utilizza un punto quando specifichi i valori composti. Ad esempio: opening_hours.weekday_text
.
I campi corrispondono a Dettagli luogo
di fatturazione e sono suddivise in tre categorie di fatturazione: Base, Contatto e
Atmosfera. I campi di base vengono fatturati alla tariffa di base e non sono soggetti a
addebiti. I campi Contact e Atmosphere vengono fatturati a una tariffa superiore. Consulta il listino prezzi
per ulteriori informazioni. Le attribuzioni (html_attributions
) sono sempre
restituito a ogni chiamata, indipendentemente dal fatto che sia stata richiesta.
Basic
La categoria Base include i seguenti campi:
address_components
, adr_address
, business_status
formatted_address
, geometry
, icon
,
icon_mask_base_uri
, icon_background_color
,name
,
permanently_closed
(ritirato),
photo
, place_id
, plus_code
, type
,
url
, utc_offset
(ritirato
in Places Library, nell'API Maps JavaScript), utc_offset_minutes
,
vicinity
Contatto
La categoria Contatto include i seguenti campi:
formatted_phone_number
, international_phone_number
opening_hours
website
Atmosfera
La categoria Atmosfera include i seguenti campi:
price_level
, rating
, reviews
user_ratings_total
Scopri di più su campi del luogo. Per ulteriori informazioni informazioni su come vengono fatturate le richieste di dati di Place, vedi Utilizzo e fatturazione.
Risposte Place Details
Codici di stato
L'oggetto risposta PlacesServiceStatus
contiene lo stato di
la richiesta e potrebbero contenere informazioni di debug per aiutarti a rintracciare
perché la richiesta Dettagli luogo non è andata a buon fine. I valori di stato possibili sono:
INVALID_REQUEST
: questa richiesta non è valida.OK
: la risposta contiene un risultato valido.OVER_QUERY_LIMIT
: la pagina web ha superato la sua richiesta quota.NOT_FOUND
La località di riferimento non era nel database di Places.REQUEST_DENIED
: la pagina web non è autorizzata a utilizzare i PlacesService.UNKNOWN_ERROR
: impossibile inviare la richiesta PlacesService elaborati a causa di un errore del server. Riprova.ZERO_RESULTS
: nessun risultato trovato per questa richiesta.
Risultati Place Details
Una chiamata getDetails()
andata a buon fine restituisce un
PlaceResult
con le seguenti proprietà:
address_components
: un array contenente l'elemento applicabili a questo indirizzo.In genere, ogni componente dell'indirizzo contiene i seguenti campi:
types[]
è un array che indica il tipo di . Consulta l'elenco di tipi supportati.long_name
è la descrizione testuale o il nome completo del indirizzo come restituito dal Geocoder.short_name
è un nome testuale abbreviato per l'indirizzo , se disponibile. Ad esempio, un componente dell'indirizzo per lo stato dell'Alaska potrebbe avere una metricalong_name
"Alaska" e unshort_name
di "AK" utilizzando l'abbreviazione postale a due lettere.
Prendi nota delle seguenti informazioni su
address_components[]
array:- L'array dei componenti dell'indirizzo può contenere più componenti rispetto
formatted_address
. - L'array non include necessariamente tutte le entità politiche
contenere un indirizzo, diverso da quelli inclusi nei
formatted_address
. Per recuperare tutte le entità politiche che contengono un indirizzo specifico, devi usare la geocodifica inversa, La latitudine/longitudine dell'indirizzo come parametro della richiesta. - Non è garantito che il formato della risposta rimanga lo stesso tra
richieste. In particolare, il numero di
address_components
varia in base all'indirizzo richiesto e può cambiare nel tempo in base all'indirizzo nello stesso indirizzo. Un componente può cambiare posizione nell'array. Il tipo di componente può cambiare. Un particolare componente può essere mancante in una risposta successiva.
business_status
indica l'operatività del luogo, se si tratta di un'attività commerciale. Può contenere uno dei seguenti i seguenti valori:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
non viene restituito.formatted_address
: l'indirizzo leggibile di questo luogo.Spesso, questo indirizzo equivale all'indirizzo postale. Tieni presente che alcune paesi, come il Regno Unito, non consentono la distribuzione di veri e propri indirizzi postali a causa di limitazioni di licenza.
L'indirizzo formattato è logicamente composto da uno o più indirizzi componenti. Ad esempio, l'indirizzo "111 8th Avenue, New York, NY" è costituito dai seguenti componenti: "111" (il numero civico), "8th Avenue" (il percorso), "New York" (la città) e "NY" (stato USA).
Non analizzare l'indirizzo formattato in modo programmatico. Dovresti invece usare i singoli componenti dell'indirizzo, che la risposta dell'API include in aggiunta nel campo dell'indirizzo formattato.
formatted_phone_number
: il numero di telefono del luogo, formattato secondo convenzione regionale di un numero.geometry
: informazioni relative alla geometria del luogo. Questo include:location
fornisce la latitudine e la longitudine posto.viewport
definisce l'area visibile preferita sulla mappa quando visualizza questo luogo.
permanently_closed
(ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valoretrue
). Non utilizzarepermanently_closed
. Usa invecebusiness_status
per conoscere lo stato di attività delle aziende.plus_code
(vedi Apri codice posizione e plus code) è un riferimento a una posizione codificato, derivato dalle coordinate di latitudine e longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. I Plus Code possono essere utilizzati in sostituzione di indirizzi in luoghi in cui non esistono (in cui gli edifici non sono numerati o le vie non hanno un nome).Il Plus Code è formattato come codice globale e codice composto:
global_code
è un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri (849VCWC8+R9).compound_code
è un codice locale di almeno 6 caratteri con una posizione esplicita (CWC8+R9, Mountain View, CA, USA). Non analizzare questi contenuti in modo programmatico.
html_attributions
: testo dell'attribuzione da visualizzare risultato di questo luogo.icon
: URL a una risorsa immagine che può essere utilizzata per rappresentano il tipo di luogo.international_phone_number
contiene il telefono del luogo numero in formato internazionale. Il formato internazionale include il paese ed è preceduta dal segno più (+). Ad esempio,international_phone_number
per Google a Sydney, Australia ufficio è+61 2 9374 4000
.name
: il nome del luogo.utc_offset
Obsoleta In Places Library, nell'API Maps JavaScript, usautc_offset_minutes
.utc_offset_minutes
contiene il numero di minuti il fuso orario attuale del luogo è diverso da UTC. Ad esempio, per i luoghi in Sydney, Australia durante l'ora legale sarà 660 (+11 ore) dal fuso orario UTC) e per i luoghi della California al di fuori dell'ora legale sarà -480 (-8 ore dal fuso orario UTC).opening_hours
contiene le seguenti informazioni:open_now
(Deprecato in Places Library, nell'API Maps JavaScript; utilizzare opening_hours.isOpen(). Guarda questo video per scoprire come utilizzareisOpen
con Place Details.) è un valore booleano che indica se il luogo è aperto nel punto attuale nel tempo.periods[]
è un array di periodi di apertura che coprono sette giorni, a partire da domenica, in ordine cronologico. Ogni periodo contiene:open
contiene una coppia di oggetti giorno e ora che descrive l'apertura del luogo:day
un numero compreso tra 0 e 6, corrispondente ai giorni della settimana, a partire dalla domenica. Ad esempio, 2 significa martedì.time
può contenere un'ora del giorno in formato hhmm di 24 ore (i valori sono compresi tra 0000 e 2359). Latime
verrà registrato nel fuso orario del luogo.
close
può contenere una coppia di oggetti giorno e ora che descrive quando il luogo chiude. Nota: se un luogo è sempre aperta, la sezioneclose
presenti nella risposta. Le applicazioni possono fare affidamento rappresentato come un puntoopen
contenenteday
con valore 0 etime
con valore 0000, e nessunaclose
.
weekday_text
è un array di sette stringhe che rappresenta gli orari di apertura formattati per ogni giorno della settimana. Se Il parametrolanguage
è stato specificato in Place Details richiesta, il servizio Places formatterà e localizzerà l'orario di apertura in modo appropriato per quella lingua. L'ordine degli elementi in questo dipende dal parametrolanguage
. Alcune lingue iniziano la settimana di lunedì, mentre gli altri iniziano di domenica.
permanently_closed
(ritirato) è un flag booleano che indica se il luogo è stato chiuso in modo permanente o temporaneo (valoretrue
). Non utilizzarepermanently_closed
. Usa invecebusiness_status
per conoscere lo stato di attività delle aziende.photos[]
: un array diPlacePhoto
oggetti. È possibile usare unPlacePhoto
per ottenere una foto congetUrl()
oppure puoi ispezionare l'oggetto per i seguenti valori:height
: l'altezza massima dell'immagine in pixel.width
: la larghezza massima dell'immagine in pixel.html_attributions
: testo dell'attribuzione da visualizzare con la foto di questo luogo.
place_id
: un identificatore testuale che identifica in modo univoco un luogo e può essere utilizzato per recuperare informazioni sul luogo tramite Dettagli luogo richiesta. Scopri di più su come fare riferimento a un luogo con un ID luogo.rating
: la valutazione del luogo, da 0,0 a 5,0, in base a e recensioni aggregate degli utenti.reviews
un array di massimo cinque recensioni. Ogni recensione è costituito da diversi componenti:aspects[]
contiene un array diPlaceAspectRating
oggetti, ognuno dei quali fornisce un valutazione di un singolo attributo della struttura. Il primo oggetto nell'array è considerato l'aspetto principale. CiascunaPlaceAspectRating
è definito come:type
il nome dell'aspetto che viene valutato. Sono supportati i seguenti tipi:appeal
,atmosphere
,decor
facilities
,food
,overall
quality
eservice
.rating
la valutazione dell'utente per questo particolare specifico, da 0 a 3.
author_name
il nome dell'utente che ha inviato la per la revisione. Le recensioni anonime vengono attribuite a "Un utente Google". Se parametro della lingua è stato impostato, poi la frase "Un utente Google" che restituiscono una stringa localizzata.author_url
l'URL del profilo Google+ dell'utente, se disponibili.language
: un codice lingua IETF che indica la lingua utilizzati nella recensione dell'utente. Questo campo contiene il tag della lingua principale e non il tag secondario che indica il paese o la regione. Per Ad esempio, tutte le recensioni in inglese sono contrassegnate come "en" e non "en-AU" o "en-UK" e così via.rating
la valutazione complessiva dell'utente per questo luogo. Questo è un numero intero compreso tra 1 e 5.text
la recensione dell'utente. Quando esamini un posizione con Google Places, le recensioni testuali sono considerate facoltative; pertanto questo campo può essere vuoto.
types
Un array di tipi per questo luogo (ad es.["political", "locality"]
o["restaurant", "lodging"]
). Questo array può contenere più valori oppure vuoto. È possibile che vengano introdotti nuovi valori senza preavviso. Consulta l'elenco di tipi supportati.url
: URL della pagina Google ufficiale dedicata posto. Questa è la pagina di proprietà di Google che contiene le migliori le informazioni disponibili sul luogo. Le applicazioni devono rimandare a o incorporare questa pagina in qualsiasi schermata che mostri risultati dettagliati sul luogo utente.vicinity
: un indirizzo semplificato del luogo, che include: il nome della via, il numero civico e la località, ma non i provincia/stato, codice postale o paese. Ad esempio, Google's Sydney, La sede dell'Australia ha un valore divicinity
pari a5/48 Pirrama Road, Pyrmont
. La proprietàvicinity
viene restituita solo per una Ricerca nelle vicinanze.website
elenca il sito web ufficiale di questo luogo, ad esempio come azienda" homepage.
Nota: le valutazioni multidimensionali potrebbero non essere disponibili per tutte le località. Se il numero di recensioni è troppo basso, la risposta dettagliata includere una valutazione precedente su una scala da 0,0 a 5,0 (se disponibile) oppure nessuna valutazione.
Utilizzare il componente Panoramica del luogo
Nota: questo esempio utilizza una libreria open source. Consulta le README per ricevere assistenza e feedback relativi alla raccolta.
Prova i componenti web. Utilizza la Componente web Panoramica del luogo per visualizzare i dettagli del luogo con una rappresentazione visiva.
![Immagine che mostra variazioni di dimensioni x-small, small, medium, large e x-large delle
Componente Panoramica del luogo visualizzato in base al campo delle dimensioni inserito dall'utente.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=5&hl=it)
Fare riferimento a un luogo con un ID luogo
Un ID luogo è un riferimento univoco a un luogo su una mappa di Google. ID luogo sono disponibili per la maggior parte delle località, tra cui attività, punti di riferimento, parchi, e incroci.
Per utilizzare un ID luogo nella tua app, devi prima cercare l'ID, ovvero
disponibile in PlaceResult
di una richiesta Place Search o Details.
Puoi quindi utilizzare questo ID luogo per cercare
Luogo
Dettagli.
Gli ID luogo sono esenti dalle limitazioni di memorizzazione nella cache dichiarate nella Sezione 3.2.3(b) del Termini di servizio di Google Maps Platform. Puoi quindi memorizzare i valori degli ID luogo per utilizzarli in un secondo momento. Per best practice per la memorizzazione degli ID luogo, consulta le panoramica di Place ID.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
Place Photos
La funzionalità Place Photo ti consente di aggiungere immagini fotografiche di alta qualità sul tuo sito. Il servizio Foto ti consente di accedere a milioni di foto archiviate nel database di Places e Google+ Local. Quando arrivi a destinazione utilizzando una richiesta Place Details, foto verranno restituiti i riferimenti per i contenuti fotografici pertinenti. La ricerca nelle vicinanze e ricerca testuale restituiscono anche un solo riferimento foto per luogo, quando pertinenti. Tramite il servizio Foto puoi accedere alle foto di riferimento e ridimensiona l'immagine alle dimensioni ottimali per la tua applicazione.
Verrà restituito un array di PlacePhoto
oggetti come parte dell'istruzione
Oggetto PlaceResult
per qualsiasi getDetails()
,
textSearch()
o
Richiesta di nearbySearch()
effettuata nei confronti di PlacesService
.
Nota: il numero di foto restituite varia a seconda della richiesta.
- Una ricerca nelle vicinanze o una ricerca testuale restituirà al massimo uno
PlacePhoto
oggetto. - Una richiesta di dettagli restituirà fino a dieci oggetti
PlacePhoto
.
Puoi richiedere l'URL dell'immagine associata chiamando il metodo
PlacePhoto.getUrl()
e trasmettere un valore
Oggetto PhotoOptions
. L'oggetto PhotoOptions
consente
di specificare l'altezza e la larghezza massime desiderate per l'immagine. Se
specificare un valore sia per maxHeight
sia per maxWidth
,
il servizio fotografico ridimensiona l'immagine al valore più piccolo tra le due dimensioni, mentre
mantenendo le proporzioni originali.
Il seguente snippet di codice accetta un oggetto luogo e aggiunge un indicatore alla mappa se esiste una foto. L'immagine dell'indicatore predefinito viene sostituita da una versione ridotta della foto.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
Le foto restituite dal servizio Foto provengono da una vasta gamma di
sedi, tra cui proprietari di attività e foto fornite dagli utenti. Nella maggior parte dei casi,
casi, queste foto possono essere utilizzate senza attribuzione o avranno i requisiti
dell'immagine. Tuttavia, se l'oggetto restituito
L'elemento photo
include un valore nell'elemento
html_attributions
, devi includere il valore aggiuntivo
nella tua applicazione ovunque mostri l'immagine.