Il servizio Autocomplete (nuovo) è un servizio web che restituisce previsioni sui luoghi e sulle query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca testuale e limiti geografici che controllano l'area di ricerca.
Il servizio Autocomplete (nuovo) può trovare corrispondenze con parole complete e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e plus code. Le applicazioni possono quindi inviare query man mano che l'utente digita le query, per fornire previsioni immediate e delle query.
La risposta dell'API Autocomplete (nuova) può contenere due tipi di previsioni:
- Previsioni sui 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 sui luoghi vengono restituite per impostazione predefinita.
- Previsioni sulle query: stringhe di query corrispondenti alla stringa di testo di input e all'area di ricerca. Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il
parametro di richiesta
includeQueryPredictions
per aggiungere previsioni delle query alla risposta.
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, CA. La risposta contiene un elenco di previsioni sui luoghi corrispondenti alla stringa di ricerca e all'area di ricerca, come il ristorante "Sicilian Pizza Kitchen", insieme ai dettagli sul luogo.
Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo desiderato. Puoi inviare una richiesta Dettagli luogo (nuova) per ottenere ulteriori informazioni su una delle previsioni di un 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 alla siciliana". Ogni previsione di query nella risposta include il campo text
contenente una stringa di ricerca testuale consigliata. Utilizza la stringa come input per la ricerca testuale (nuova) al fine di eseguire una ricerca più dettagliata.
Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con le opzioni API e API:
Prova!Richieste di completamento automatico (nuove)
Una richiesta Autocomplete (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
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 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 un singolo luogo, tra cui 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 e sottostringhe complete, nomi di luoghi, indirizzi e plus code. Il servizio di completamento automatico (nuovo) restituisce le corrispondenze dei 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 i tipi 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
, a prescindere dal valore del tipo principale associato al luogo. Limita i risultati in modo che siano di un determinato tipo o tipo primario passando il parametroincludedPrimaryTypes
.Utilizza questo parametro per specificare fino a cinque valori di tipo da Tabella A o Tabella B. Una località deve corrispondere 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 dei luoghi. -
includedRegionCodes
Includi solo i risultati dell'elenco di regioni specificate, specificate come un array di un massimo di 15 ccTLD ("dominio di primo livello") 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, il valore predefinito è la lunghezza diinput
. -
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 dispone di una traduzione dalla lingua locale inlanguageCode
.- Devi utilizzare i codici lingua IETF BCP-47 per specificare la lingua preferita.
-
Se
languageCode
non viene specificato, 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. Ciò 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 sia per la popolazione locale, rispecchiando allo stesso tempo l'input dell'utente. Le previsioni dei luoghi vengono
formattate in modo diverso a seconda dell'input dell'utente in ogni richiesta.
-
I termini corrispondenti nel parametro
input
vengono scelti per primi utilizzando i nomi allineati alla preferenza della lingua indicata dal parametrolanguageCode
se disponibile, altrimenti utilizzando i nomi che corrispondono meglio all'input dell'utente. -
Gli indirizzi vengono formattati nella lingua locale, in uno script leggibile dall'utente quando possibile, solo dopo che i termini corrispondenti sono stati scelti in modo che corrispondano a quelli nel 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 nel parametro
input
. Se un 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. Pensa alocationRestriction
come a specificare la regione in cui devono trovarsi i risultati, mentre alocationBias
a specificare la regione vicina ai risultati che possono essere al di fuori dell'area.locationBias
Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, compresi quelli al di fuori dell'area specificata.
locationRestriction
Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti.
Specifica la regione
locationBias
olocationRestriction
come area visibile rettangolare o circolare.Un cerchio viene definito dal centro 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 punti alti e
low
opposti diagonalmente. Un'area visibile è considerata una regione chiusa, ovvero include il proprio confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre quelli 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 supera 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 partenza dal quale 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 a 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à "The United Kingdom of 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 tracciano le chiamate di completamento automatico (nuove) come "sessioni". Autocomplete (Nuovo) utilizza i token di sessione per raggruppare le fasi di query e selezione della ricerca di completamento automatico di un utente in una sessione distinta ai fini della fatturazione. Per maggiori informazioni, consulta 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
l'indirizzo IP del dispositivo per differenziazione dei risultati. Facoltativamente, 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. I risultati al di fuori dell'area specificata
non vengono restituiti. Nell'esempio seguente, utilizzi locationRestriction
per limitare la 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, il che significa che possono essere restituiti risultati relativi alla località specificata, compresi quelli al di fuori dell'area specificata. Nell'esempio successivo, modifichi la richiesta per utilizzare 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,
solo (regions)
o solo (cities)
. Una località deve corrispondere a uno dei valori di tipo principale specificati da includere nella risposta.
Nell'esempio seguente, specifichi una stringa input
di
"Calcio" e utilizzi il parametro includedPrimaryTypes
per limitare i risultati a
stabilimenti 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
stabilimenti di un tipo che non vuoi, come "athletic_field"
.
Richiedi previsioni per le query
Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions
per aggiungere previsioni delle 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. Ogni previsione della query include il campo text
contenente una stringa di ricerca testuale consigliata. Puoi effettuare una richiesta di Ricerca testuale (nuova) per ottenere ulteriori informazioni su una qualsiasi delle 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 nella risposta il campo distanceMeters
, 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 consente di effettuare richieste di esempio, per 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 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 di Explorer API.