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.
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
Effettua una richiesta utilizzando il completamento automatico (novità)
L'API Places supporta le API Autocomplete e Query Autocomplete esistenti. Se hai dimestichezza con queste API, la versione di anteprima di Autocomplete (New) apporta le seguenti modifiche:- La nuova funzionalità di completamento automatico utilizza richieste POST HTTP. Trasferisci i parametri nel corpo della richiesta o nelle intestazioni come parte di una richiesta POST HTTP. Al contrario, con le API esistenti, i parametri URL vengono trasmessi utilizzando una richiesta HTTP GET.
- La nuova funzionalità di completamento automatico supporta sia le chiavi API sia i token OAuth come meccanismo di autenticazione.
- Nel nuovo completamento automatico è supportato solo JSON come formato di risposta.
La seguente tabella elenca i parametri nelle API Autocomplete e Query Autocomplete esistenti che sono stati rinominati o modificati per il nuovo Autocomplete o che non sono più supportati.
Parametro attuale | Nuovo parametro | Note |
---|---|---|
components |
includedRegionCodes |
|
language |
languageCode |
|
location |
locationBias |
|
ipbias |
Se ometti sia locationBias sia locationRestriction , l'API utilizza la differenziazione degli IP per impostazione predefinita. |
|
offset |
inputOffset |
|
radius |
locationBias o locationRestriction |
|
region |
regionCode |
|
stricbounds |
locationRestriction |
|
sessiontoken |
sessionToken |
|
types |
includedPrimaryTypes |
Limiti di utilizzo
Durante la release di anteprima, puoi eseguire un massimo di 600 query al minuto per progetto.
Opzioni di supporto per le release in anteprima
Sebbene Google non abbia alcun obbligo di fornire assistenza per le versioni in anteprima, le funzionalità o le funzionalità dei Servizi, valuteremo le richieste in queste fasi di sviluppo caso per caso.
- Le versioni di pre-release non sono coperte dallo SLA di Google Maps Platform.
- È consigliabile utilizzare meccanismi di fallback, soprattutto se usi una versione pre-release in un ambiente di produzione. Ecco alcuni esempi di situazioni di riserva: quota superata, latenza e codici di risposta imprevisti o risposte impreviste rispetto al completamento automatico esistente.
Puoi utilizzare Issue Tracker per richiedere nuove funzionalità o suggerire modifiche alle funzionalità esistenti. Descrivi la funzionalità specifica che vorresti che fosse aggiunta, oltre ai motivi per cui ritieni che sia importante. Se possibile, includi dettagli specifici sul tuo caso d'uso e sulle nuove opportunità che la funzionalità consentirebbe:
Per qualsiasi altra domanda sulle funzionalità, invia un'email all'indirizzo newplaceapi@google.com.
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 associato ai tipi Tabella A o 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. Un luogo deve corrispondere a uno dei valori di tipo primario specificati per essere incluso nella risposta.
La richiesta viene rifiutata con un errore
INVALID_REQUEST
se:- Sono stati specificati più di cinque tipi.
- 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 limitare i risultati di una richiesta di un determinato tipo, come elencato nella Tabella A e nella Tabella B. Puoi specificare un array di massimo cinque valori.
Se omesso, vengono restituiti tutti i tipi.
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 } } ] }