Il servizio Autocomplete (New) è un servizio web che restituisce previsioni delle località e delle query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca testuale e limiti geografici che controlli l'area di ricerca.
Il servizio di completamento automatico (nuovo) può creare corrispondenze con le parole complete e le sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e più codici. Le applicazioni possono quindi inviare query come tipi di utente, per fornire previsioni di query e luoghi in tempo reale.
La risposta dell'API Autocomplete (New) può contenere due tipi di previsioni:
- Previsioni dei luoghi: luoghi, come attività, indirizzi e punti d'interesse, in base alla stringa di testo di input e all'area di ricerca specificate. Le previsioni dei luoghi vengono restituite per impostazione predefinita.
- Previsioni delle query: stringhe di query che corrispondono alla stringa di testo di input e all'area di ricerca. Per impostazione predefinita, non vengono restituite le previsioni delle query. Utilizza il parametro di richiesta
includeQueryPredictions
per aggiungere previsioni delle query alla risposta.
Ad esempio, chiami l'API utilizzando come input una stringa contenente un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, CA. La risposta contiene quindi un elenco di previsioni sui luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, come il ristorante chiamato "Sicilian Pizza Kitchen", insieme ai dettagli sul luogo.
Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per selezionare più facilmente il luogo desiderato. Puoi effettuare una richiesta Place Details (New) (Dettagli luogo) per ricevere ulteriori informazioni su una qualsiasi delle previsioni di luogo restituite.
La risposta può anche contenere un elenco di previsioni delle query corrispondenti alla
stringa di ricerca e all'area di ricerca, ad esempio "Pizza e pasta in Sicilia". Ogni previsione di query nella risposta include il campo text
contenente una stringa di ricerca testuale consigliata. Utilizza questa
stringa come input per
Ricerca testuale (Nuova)
per eseguire una ricerca più dettagliata.
Explorer API ti consente di effettuare richieste in tempo reale in modo da acquisire familiarità con le API e le relative opzioni:
Prova!Richieste di completamento automatico (nuove)
Una richiesta di completamento automatico (nuova) è una richiesta POST HTTP a un URL nel formato:
https://places.googleapis.com/v1/places:autocomplete
Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Informazioni sulla risposta
Il completamento automatico (nuovo) restituisce un oggetto JSON come risposta. Nella risposta:
- L'array
suggestions
contiene tutti i luoghi e le query previsti in ordine in base alla loro pertinenza percepita. Ogni luogo è rappresentato da un campoplacePrediction
e ogni query è rappresentata da un campoqueryPrediction
. - Un campo
placePrediction
contiene informazioni dettagliate sulla previsione di una singola località, inclusi l'ID luogo e la descrizione testuale. - Un campo
queryPrediction
contiene informazioni dettagliate su una singola previsione di query.
L'oggetto JSON completo ha il seguente formato:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Parametri obbligatori
-
input
La stringa di testo in cui eseguire la ricerca. Specifica parole complete e sottostringhe, nomi di luoghi, indirizzi e più codici. Il servizio di completamento automatico (nuovo) restituisce le corrispondenze candidati in base a questa stringa e ordina i risultati in base alla pertinenza percepita.
Parametri facoltativi
-
includedPrimaryTypes
Un luogo può avere un solo singolo tipo principale tra quelli elencati nella Tabella A o nella Tabella B. Ad esempio, il tipo principale potrebbe essere
"mexican_restaurant"
o"steak_house"
.Per impostazione predefinita, l'API restituisce tutte le posizioni in base al parametro
input
, indipendentemente dal valore del tipo principale associato al luogo. Limita i risultati in modo che siano di un determinato tipo o di tipi principali passando il parametroincludedPrimaryTypes
.Utilizza questo parametro per specificare fino a cinque valori di tipo nella Tabella A o nella Tabella B. Per essere incluso nella risposta, un luogo deve corrispondere a uno dei valori di tipo primario specificati.
Al suo posto, questo parametro può includere anche un valore tra
(regions)
o(cities)
. I filtri di raccolta dei tipi(regions)
per aree o divisioni, come quartieri e codici postali. I filtri di raccolta dei tipi di(cities)
per i luoghi che Google identifica come città.La richiesta viene rifiutata con un errore
INVALID_REQUEST
se:- Sono stati specificati più di cinque tipi.
- Viene specificato qualsiasi tipo oltre a
(cities)
o(regions)
. - Vengono specificati i tipi non riconosciuti.
-
includeQueryPredictions
Se
true
, la risposta include sia le previsioni relative al luogo sia alle previsioni delle query. Il valore predefinito èfalse
, il che significa che la risposta include solo le previsioni dei luoghi. -
includedRegionCodes
Includi solo i risultati dall'elenco delle regioni specificate, specificate come array di massimo 15 valori di due caratteri ccTLD ("dominio di primo livello"). Se omesso, non vengono applicate limitazioni alla risposta. Ad esempio, per limitare le regioni a Germania e Francia:
"includedRegionCodes": ["de", "fr"]
Se specifichi sia
locationRestriction
siaincludedRegionCodes
, i risultati si trovano nell'area di intersezione delle due impostazioni. -
inputOffset
L'offset di caratteri Unicode in base zero che indica la posizione del cursore in
input
. La posizione del cursore può influire sulle previsioni che vengono restituite. Se è vuoto, il valore predefinito èinput
. -
languageCode
La lingua preferita in cui restituire i risultati. I risultati potrebbero essere in lingue miste se la lingua utilizzata in
input
è diversa dal valore specificato dalanguageCode
o se il luogo restituito non ha una traduzione dalla lingua locale inlanguageCode
.- Devi utilizzare i codici lingua IETF BCP-47 per specificare la lingua preferita.
-
Se
languageCode
non viene fornito, l'API utilizza il valore specificato nell'intestazioneAccept-Language
. Se nessuno dei due è specificato, il valore predefinito èen
. Se specifichi un codice lingua non valido, l'API restituisce un erroreINVALID_ARGUMENT
. - La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Questo influisce anche sulla capacità dell'API di correggere gli errori ortografici.
-
L'API tenta di fornire un indirizzo che sia leggibile sia per l'utente che
per la popolazione locale, rispecchiando allo stesso tempo l'input dell'utente. Le previsioni dei luoghi sono formattate in modo diverso a seconda dell'input utente in ciascuna richiesta.
-
I termini corrispondenti nel parametro
input
vengono scelti per primi, utilizzando nomi allineati alla preferenza di lingua indicata dal parametrolanguageCode
se disponibile, altrimenti utilizzando i nomi che corrispondono meglio all'input utente. -
Gli indirizzi sono formattati nella lingua locale, in uno script leggibile dall'utente quando possibile, solo dopo che i termini corrispondenti sono stati selezionati in modo che corrispondano a quelli del parametro
input
. -
Tutti gli altri indirizzi vengono restituiti nella lingua preferita dopo che i termini corrispondenti
sono stati scelti in modo che corrispondano ai termini del parametro
input
. Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
-
I termini corrispondenti nel parametro
posizioneBias o limitazione di località
Puoi specificare
locationBias
olocationRestriction
, ma non entrambi, per definire l'area di ricerca. Pensa alocationRestriction
come a specificare la regione in cui devono trovarsi i risultati, mentrelocationBias
a specifica la regione in cui i risultati devono essere vicini, ma che possono essere al di fuori dell'area.locationBias
Specifica un'area da cercare. Questa località funge da bias, il che significa che possono essere restituiti i risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.
locationRestriction
Specifica un'area da cercare. I risultati al di fuori dell'area specificata non vengono restituiti.
Specifica la regione
locationBias
olocationRestriction
come area visibile rettangolare o come cerchio.Un cerchio viene definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0,0. Per
locationRestriction
, devi impostare il raggio su un valore maggiore di 0,0. In caso contrario, la richiesta non restituisce alcun risultato.Ad esempio:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due diagonali opposti a
low
e ai punti alti. Un'area visibile è considerata una regione chiusa, ovvero include i suoi confini. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:- Se
low
=high
, l'area visibile è composta da quel singolo punto. - Se
low.longitude
>high.longitude
, l'intervallo di longitudine viene invertito (l'area visibile attraversa la linea di longitudine di 180 gradi). - Se
low.longitude
= -180 gradi ehigh.longitude
= 180 gradi, l'area visibile include tutte le longitudini. - Se
low.longitude
= 180 gradi ehigh.longitude
= -180 gradi, l'intervallo di longitudine è vuoto.
È necessario compilare entrambi i campi
low
ehigh
e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.Ad esempio, questa area visibile racchiude completamente New York City:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Se
-
origine
Il punto di origine da cui calcolare la distanza in linea retta dalla destinazione (restituito come
distanceMeters
). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Devono essere specificate come coordinate di latitudine e longitudine:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").
Se specifichi un codice regione non valido, l'API restituisce un errore
INVALID_ARGUMENT
. Il parametro può influire sui risultati in base alla legge vigente. -
sessionToken
I token di sessione sono stringhe generate dall'utente che monitorano le chiamate di completamento automatico (nuovo) come "sessioni". Il completamento automatico (nuova) utilizza i token di sessione per raggruppare le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. Per maggiori informazioni, consulta la sezione Token sessione.
Esempi di completamento automatico (nuovi)
Usa limitazioni di località e locationBias
Per impostazione predefinita, l'API utilizza la differenziazione IP per controllare l'area di ricerca. Con la differenziazione IP, l'API utilizza
l'indirizzo IP del dispositivo per polarizzare i risultati. Facoltativamente, puoi utilizzare
locationRestriction
o locationBias
, ma non entrambi, per specificare un'area da cercare.
locationRestriction
specifica l'area da cercare. I risultati al di fuori dell'area specificata
non vengono restituiti. Nell'esempio seguente, utilizza locationRestriction
per limitare la richiesta a un cerchio di 5000 metri con un raggio centrato su San Francisco:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Tutti i risultati all'interno delle aree specificate sono contenuti nell'array suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
Con locationBias
, la località funge da bias, il che significa che è possibile restituire i risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata. Nell'esempio successivo, modifichi la richiesta in modo che utilizzi locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
I risultati ora contengono molti più elementi, compresi quelli al di fuori del raggio di 5000 metri:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
Utilizzare inclusioni principali
Utilizza il parametro includedPrimaryTypes
per specificare fino a cinque valori di tipo nella Tabella A, nella Tabella B oppure solo nella tabella (regions)
o solo (cities)
. Un luogo deve corrispondere a uno dei valori di tipo primario specificati per essere incluso nella risposta.
Nell'esempio seguente, specifichi una stringa input
di "Calcio" e utilizzi il parametro includedPrimaryTypes
per limitare i risultati alle fondazioni di tipo "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Se ometti il parametro includedPrimaryTypes
, i risultati possono includere
costruzioni di un tipo non desiderato, come "athletic_field"
.
Richiedi previsioni delle query
Per impostazione predefinita, non vengono restituite le previsioni delle query. Utilizza il parametro di richiesta includeQueryPredictions
per aggiungere previsioni di query alla risposta. Ad esempio:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
L'array suggestions
ora contiene sia le previsioni delle località sia le previsioni delle query, come mostrato sopra in Informazioni sulla risposta. Ogni previsione di query include il campo text
contenente una stringa di ricerca testuale consigliata. Puoi effettuare una richiesta di ricerca testuale (nuova) per ottenere maggiori informazioni su una qualsiasi delle previsioni delle query restituite.
Utilizza origine
In questo esempio, includi nella richiesta origin
come coordinate di latitudine e longitudine.
Se includi origin
, l'API include il campo distanceMeters
nella
risposta che contiene la distanza in linea retta da origin
alla destinazione.
Questo esempio imposta l'origine sul centro di San Francisco:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
La risposta ora include distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Prova.
Explorer API consente di effettuare richieste di esempio in modo da acquisire familiarità con le opzioni API e API.
- Seleziona l'icona dell'API, , sul lato destro della pagina.
- Se vuoi, espandi Mostra parametri standard e imposta il parametro
fields
sulla maschera di campo. - (Facoltativo) Modifica il Corpo della richiesta.
- Seleziona il pulsante Esegui. Nel popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona di espansione, , per espandere la finestra Explorer API.