Il servizio Autocomplete (nuovo) è un servizio web che restituisce luoghi e previsioni di query in risposta a una richiesta HTTP. Nella richiesta, specifica un testo stringa di ricerca e confini geografici che controllano l'area di ricerca.
Il servizio Autocomplete (New) può trovare corrispondenze con parole complete e sottostringhe dell'input, risolvendo i nomi dei luoghi, gli indirizzi plus code. Le applicazioni possono quindi inviare automaticamente durante la digitazione, per fornire previsioni immediate e sulle query.
La risposta dell'API Autocomplete (new) può contenere due tipi delle previsioni:
- Previsioni sui luoghi: luoghi, come attività, indirizzi e punti di l'interesse, in base alla stringa di testo di input e all'area di ricerca specificate. Le previsioni sui luoghi sono vengono restituiti per impostazione predefinita.
- Previsioni sulle query: stringhe di query corrispondenti alla stringa di testo di input e
nell'area di ricerca. Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza la
Parametro di richiesta
includeQueryPredictions
per aggiungere previsioni della query al la risposta corretta.
Ad esempio, chiami l'API utilizzando come input una stringa che contiene un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, California. La risposta contiene quindi elenco di previsioni dei luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, come intitolato "Sicilian Pizza Kitchen", insieme a informazioni dettagliate sul luogo.
Le previsioni del luogo restituite sono progettate per essere presentate all'utente per aiutare selezionando il luogo desiderato. Puoi creare un Dettagli del luogo (novità) richiedere ulteriori informazioni sulle previsioni dei luoghi restituite.
La risposta può anche contenere un elenco di previsioni della query corrispondenti
stringa di ricerca e area di ricerca, ad esempio "Pizza Siciliana & pasta". Ogni previsione della query nel
la risposta include il campo text
contenente una stringa di ricerca testuale consigliata. Usalo
stringa come input
Ricerca testuale (novità)
per eseguire una ricerca più dettagliata.
Explorer API ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e Opzioni API:
Prova!Richieste di completamento automatico (nuove)
Una richiesta Autocomplete (Nuova) è una richiesta POST HTTP a un URL in il modulo:
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
Autocomplete (New) restituisce un oggetto JSON come risposta. Nella risposta:
- L'array
suggestions
contiene tutti i luoghi e le query previsti in ordine in base alla percezione della loro pertinenza. Ogni luogo è rappresentato da unplacePrediction
campo e ogni query è rappresentata da un campoqueryPrediction
. - Un campo
placePrediction
contiene informazioni dettagliate su una singola la previsione del luogo, inclusi l'ID luogo e la descrizione testuale. - Un campo
queryPrediction
contiene informazioni dettagliate su una singola la previsione delle 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 plus code. Il servizio Autocomplete (nuovo) restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base a la loro pertinenza percepita.
Parametri facoltativi
-
includedPrimaryTypes
Un luogo può avere un solo unico tipo principale tra i tipi elencati in Tabella A oppure 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 del valore del tipo principale associato al luogo. Limita i risultati a un determinato di tipo primario o di tipo primario passando il parametroincludedPrimaryTypes
.Utilizza questo parametro per specificare fino a cinque valori di tipo dalla Tabella A o Tabella B. Un luogo deve corrisponde a uno dei valori di tipo principale specificati da includere nella risposta.
Questo parametro può anche includere, invece, uno dei seguenti valori:
(regions)
o(cities)
. La raccolta di tipi(regions)
applica filtri per aree o divisioni, come quartieri e codici postali. La raccolta dei tipi di(cities)
applica un filtro ai luoghi che Google identifica come città.La richiesta viene rifiutata con un errore
INVALID_REQUEST
se:- Sono specificati più di cinque tipi.
- Viene specificato qualsiasi tipo oltre a
(cities)
o(regions)
. - Vengono specificati tipi non riconosciuti.
-
includeQueryPredictions
Se
true
, la risposta include previsioni sia sul luogo sia sulla query. Il valore predefinito èfalse
, il che significa che la risposta include solo le previsioni sui luoghi. -
includedRegionCodes
Includi solo i risultati dell'elenco di regioni specificate, specificate come un array di massimo 15 ccTLD ("dominio di primo livello") valori a due caratteri. 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 Unicode su base zero che indica la posizione del cursore in
input
. La posizione del cursore può influire sulle previsioni restituite. Se vuoto, viene utilizzato il valore predefinito lunghezza diinput
. -
languageCode
La lingua preferita in cui restituire i risultati. I risultati potrebbero essere in lingue diverse se la lingua usata in
input
è diversa dal valore specificato dalanguageCode
o se il luogo restituito non dispone di una traduzione dal lingua locale alanguageCode
.- Devi utilizzare IETF Codici lingua BCP-47 per specificare la lingua preferita.
-
Se
languageCode
non viene specificato, l'API utilizza il valore specificato nel campo IntestazioneAccept-Language
. Se nessuno dei due è specificato, il valore predefinito èen
. Se specifichi un codice lingua non valido, l'API restituisce unINVALID_ARGUMENT
errore. - La lingua preferita ha una piccola influenza sull'insieme di risultati che che l'API sceglie di restituire e l'ordine in cui vengono restituiti. Ciò influisce anche sulla capacità dell'API di correggere gli errori ortografici.
-
L'API cerca di fornire un indirizzo stradale che sia leggibile sia per l'utente che per
popolazione locale, riflettendo al contempo l'input dell'utente. Le previsioni sui luoghi sono
formattati in modo diverso a seconda dell'input dell'utente in ciascuna richiesta.
-
I termini corrispondenti nel parametro
input
vengono scelti per primi e utilizzano i nomi allineati con la preferenza di lingua indicata dal parametrolanguageCode
quando disponibili, utilizzando al contrario i nomi che meglio corrispondono all'input dell'utente. -
Gli indirizzi vengono formattati nella lingua locale, in uno script leggibile dall'utente
quando possibile, solo dopo aver scelto i termini corrispondenti ai termini
Parametro
input
. -
Tutti gli altri indirizzi vengono restituiti nella lingua preferita, dopo che i termini corrispondenti sono stati
scelto in modo che corrisponda ai termini nel parametro
input
. Se il nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più simile.
-
I termini corrispondenti nel parametro
locationBias o locationRestriction
Puoi specificare
locationBias
olocationRestriction
, ma non entrambi, per definire l'area di ricerca. ConsideralocationRestriction
come una specifica regione in cui devono trovarsi i risultati elocationBias
che specifica la regione alla quale i risultati devono essere vicini, ma che possono essere al di fuori della zona.locationBias
Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, che significa è possibile restituire risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.
locationRestriction
Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non sono restituito.
Specifica la regione
locationBias
olocationRestriction
come area visibile rettangolare o come un cerchio.Un cerchio viene definito dal centro e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50000,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 viene restituita nessun 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 diagonalmente opposta a
low
e punti più alti. Un'area visibile è considerata un regione chiusa, ovvero include il confine. I limiti di latitudine deve essere compreso tra -90 e 90 gradi inclusi e i limiti di longitudine deve essere compreso 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 è 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 vuoto. 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 alla destinazione (restituita come
distanceMeters
). Se questo valore è omessa, la distanza in linea retta non verrà restituita. Deve essere specificato come coordinate di latitudine e longitudine:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Il codice regione utilizzato per formattare la risposta, specificato come ccTLD ("dominio di primo livello") a due caratteri. La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk) mentre il codice ISO 3166-1 è "gb" (tecnicamente per persona giuridica del "Regno Unito di Gran Bretagna e Irlanda del Nord").
Se specifichi un codice regione non valido, l'API restituisce un
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 il completamento automatico (Novità) chiamate come "sessioni". Il completamento automatico (novità) utilizza i token di sessione per le fasi di query e selezione di una ricerca con completamento automatico da parte di un utente in una sessione discreta per ai fini della fatturazione. Per ulteriori informazioni, vedi Token di sessione.
Esempi di completamento automatico (nuovi)
Utilizza locationRestriction e locationBias
L'API utilizza per impostazione predefinita la differenziazione IP per controllare l'area di ricerca. Con la differenziazione per IP, l'API utilizza
Indirizzo IP del dispositivo per differenziazione dei risultati. Se vuoi, puoi utilizzare
locationRestriction
o locationBias
, ma non entrambi, per specificare un'area in cui eseguire la ricerca.
locationRestriction
specifica l'area in cui eseguire la ricerca. Risultati al di fuori dell'area specificata
e non vengono restituiti. Nell'esempio seguente, viene utilizzato locationRestriction
per limitare il
richiesta a un cerchio di 5000 metri di 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, che indica che i risultati relativi a:
è possibile restituire la posizione specificata, compresi i risultati al di fuori dell'area specificata. Nei prossimi
Ad esempio, 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 altri elementi, inclusi i risultati 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" ] } }, ... ] }
Usa includiPrincipalType
Utilizza il parametro includedPrimaryTypes
per specificare fino a cinque valori di tipo da
Tabella A,
Tabella B,
o solo (regions)
o solo (cities)
. Un luogo deve corrispondere a uno dei
valori di tipo primario da includere nella risposta.
Nell'esempio seguente, specifichi una stringa input
di
"Calcio" e utilizza il parametro includedPrimaryTypes
per limitare i risultati a
strutture 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
locali di un tipo che non vuoi, come "athletic_field"
.
Richiedi previsioni per le query
Le previsioni delle query non vengono restituite per impostazione predefinita. Usa includeQueryPredictions
per aggiungere previsioni della 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 dei luoghi sia quelle delle query
come mostrato sopra in Informazioni sulla risposta. Previsione di ogni query
include il campo text
contenente una stringa di ricerca testuale consigliata. Puoi creare un
Ricerca testuale (novità)
per ottenere maggiori informazioni sulle previsioni delle query restituite.
Usa origine
In questo esempio, includi nella richiesta origin
sotto forma di coordinate di latitudine e longitudine.
Se includi origin
, l'API include il campo distanceMeters
nella
risposta che contiene la distanza in linea retta tra origin
alla destinazione.
Questo esempio imposta l'origine in base al 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 ti consente di effettuare richieste di esempio di acquisire familiarità con le opzioni dell'API e delle API.
- Seleziona l'icona dell'API
. sul lato destro della pagina.
- Se vuoi, espandi Mostra parametri standard e imposta
il parametro
fields
alla maschera del campo. - Se vuoi, modifica il corpo della richiesta.
- Seleziona il pulsante Esegui. Nella finestra popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona Espandi,
, per espandere la finestra Explorer API.