Il completamento automatico delle query (legacy) può essere utilizzato per fornire una previsione di query per le ricerche geografiche basate su testo, restituendo le query suggerite durante la digitazione.
Richieste Query Autocomplete (legacy)
Il completamento automatico delle query (legacy) fa parte dell'API Places (legacy) e condivide una chiave API e una quota con l'API Places (legacy).
Il completamento automatico delle query (legacy) ti consente di aggiungere previsioni di query geografiche al volo alla tua applicazione. Invece di cercare una posizione specifica, un utente può digitare una ricerca per categoria, ad esempio "pizza vicino a New York", e il servizio risponde con un elenco di query suggerite che corrispondono alla stringa. Poiché il completamento automatico delle query (legacy) può trovare corrispondenze sia per parole intere sia per sottostringhe, le applicazioni possono inviare query durante la digitazione dell'utente per fornire previsioni immediate.
Una richiesta di completamento automatico delle query (legacy) è un URL HTTP nel seguente formato:
https://maps.googleapis.com/maps/api/place/queryautocomplete/output?parameters
dove output può essere json o
xml.
Per avviare una richiesta di completamento automatico delle query (legacy), sono necessari determinati parametri.
Come di consueto negli URL, tutti i parametri sono separati dal carattere
e commerciale (&). L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.
Parametri obbligatori
-
immissione
La stringa di testo su cui eseguire la ricerca. Il servizio Place Autocomplete restituirà corrispondenze candidate in base a questa stringa e ordinerà i risultati in base alla loro pertinenza percepita.
Parametri facoltativi
-
language
La lingua in cui restituire i risultati.
- Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
-
Se
languagenon viene fornito, l'API tenta di utilizzare la lingua preferita specificata nell'intestazioneAccept-Language. - L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
- Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
- La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.
-
località
Definisce un punto, come coordinate
latitude,longitude, intorno al quale effettuare la ricerca. Il servizio Places utilizza la posizione per orientare la ricerca in modo da preferire la visualizzazione dei risultati nell'area definita dalocationeradius; i risultati al di fuori dell'area definita potrebbero comunque essere visualizzati.Il parametrolocationpotrebbe essere ignorato sequerycontiene una località esplicita comeMarket in Barcelona. L'utilizzo delle virgolette intorno alla query può anche influire sul peso assegnato alocationeradius. -
offset
La posizione, nel termine di input, dell'ultimo carattere che il servizio utilizza per trovare le corrispondenze delle previsioni. Ad esempio, se l'input è
Googlee l'offset è 3, il servizio troverà una corrispondenza conGoo. La stringa determinata dall'offset viene confrontata con solo la prima parola del termine di input. Ad esempio, se il termine di input èGoogle abce l'offset è 3, il servizio tenterà di trovare una corrispondenza conGoo abc. Se non viene fornito alcun offset, il servizio utilizzerà l'intero periodo. L'offset deve essere generalmente impostato sulla posizione del cursore di testo. -
raggio
Definisce la distanza (in metri) entro la quale restituire i risultati dei luoghi. Puoi orientare i risultati verso un cerchio specificato passando un parametro
locatione un parametroradius. In questo modo, il servizio Places preferisce mostrare i risultati all'interno di questo cerchio; i risultati al di fuori dell'area definita potrebbero comunque essere visualizzati.Il raggio verrà automaticamente limitato a un valore massimo a seconda del tipo di ricerca e di altri parametri.
- Completamento automatico: 50.000 metri
-
Nearby Search:
- con
keywordoname: 50.000 metri -
senza
keywordoname-
Fino a 50.000 metri, regolati dinamicamente in base alla densità dell'area,
indipendentemente dal parametro
rankby. -
Quando utilizzi
rankby=distance, il parametro raggio non verrà accettato e restituirà unINVALID_REQUEST.
-
Fino a 50.000 metri, regolati dinamicamente in base alla densità dell'area,
indipendentemente dal parametro
- con
- Query Autocomplete: 50.000 metri
- Ricerca testuale: 50.000 metri
Esempi di Query Autocomplete (legacy)
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'Una richiesta "Pizza vicino a Par", con risultati in francese:
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &language=fr &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'Tieni presente che dovrai sostituire la chiave API in questi esempi con la tua chiave.
Risposta di Query Autocomplete (legacy)
Le risposte al completamento automatico delle query (legacy) vengono restituite nel formato indicato dal
flag output all'interno del percorso della richiesta URL. I risultati riportati di seguito
vengono restituiti per una query con i seguenti parametri:
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'JSON
{ "predictions": [ { "description": "pizza near Paris, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Paris, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Paris" }, { "offset": 18, "value": "France" }, ], }, { "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Pari Chowk" }, { "offset": 23, "value": "NRI City" }, { "offset": 33, "value": "Omega II" }, { "offset": 43, "value": "Noida" }, { "offset": 50, "value": "Uttar Pradesh" }, { "offset": 65, "value": "India" }, ], }, { "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA", "secondary_text_matched_substrings": [{ "length": 3, "offset": 16 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Disneyland Park" }, { "offset": 28, "value": "Disneyland Drive" }, { "offset": 46, "value": "Anaheim" }, { "offset": 55, "value": "CA" }, { "offset": 59, "value": "USA" }, ], }, { "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 30 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" }, { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" }, { "offset": 83, "value": "Paris" }, { "offset": 90, "value": "France" }, ], }, { "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Paris Beauvais Airport" }, { "offset": 35, "value": "Route de l'Aéroport" }, { "offset": 56, "value": "Tillé" }, { "offset": 63, "value": "France" }, ], }, ], "status": "OK", }
XML
<AutocompletionResponse> <status>OK</status> <prediction> <description>pizza near Paris, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Paris</value> <offset>11</offset> </term> <term> <value>France</value> <offset>18</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Paris, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Pari Chowk</value> <offset>11</offset> </term> <term> <value>NRI City</value> <offset>23</offset> </term> <term> <value>Omega II</value> <offset>33</offset> </term> <term> <value>Noida</value> <offset>43</offset> </term> <term> <value>Uttar Pradesh</value> <offset>50</offset> </term> <term> <value>India</value> <offset>65</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Disneyland Park</value> <offset>11</offset> </term> <term> <value>Disneyland Drive</value> <offset>28</offset> </term> <term> <value>Anaheim</value> <offset>46</offset> </term> <term> <value>CA</value> <offset>55</offset> </term> <term> <value>USA</value> <offset>59</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>22</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>16</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Cathédrale Notre-Dame de Paris</value> <offset>11</offset> </term> <term> <value>Parvis Notre-Dame - place Jean-Paul-II</value> <offset>43</offset> </term> <term> <value>Paris</value> <offset>83</offset> </term> <term> <value>France</value> <offset>90</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>36</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>30</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Paris Beauvais Airport</value> <offset>11</offset> </term> <term> <value>Route de l'Aéroport</value> <offset>35</offset> </term> <term> <value>Tillé</value> <offset>56</offset> </term> <term> <value>France</value> <offset>63</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> </AutocompletionResponse>
Quando il servizio Places restituisce risultati JSON da una ricerca, li inserisce
all'interno di un array predictions. Anche se il servizio non restituisce
risultati (ad esempio se location è remoto),
restituisce comunque un array predictions vuoto. Le risposte XML sono costituite
da zero o più elementi <prediction>.
PlacesQueryAutocompleteResponse
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
obbligatorio | Array<PlaceAutocompletePrediction> |
Contiene un array di previsioni. Per saperne di più, consulta PlaceAutocompletePrediction. |
|
obbligatorio | PlacesAutocompleteStatus |
Contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a capire perché la richiesta non è andata a buon fine. Per ulteriori informazioni, consulta PlacesAutocompleteStatus. |
|
facoltativo | stringa |
Quando il servizio restituisce un codice di stato diverso da |
|
facoltativo | Array<stringa> |
Quando il servizio restituisce ulteriori informazioni sulla specifica della richiesta, potrebbe essere presente un campo |
PlacesAutocompleteStatus
Codici di stato restituiti dal servizio.
OKche indica che la richiesta API è andata a buon fine.-
ZERO_RESULTSche indica che la ricerca è andata a buon fine, ma non ha restituito risultati. Ciò può verificarsi se nella ricerca sono stati passati limiti in una posizione remota. -
INVALID_REQUESTche indica che la richiesta API non è formattata correttamente, in genere a causa del parametroinputmancante. -
OVER_QUERY_LIMITche indica uno dei seguenti elementi:- Hai superato i limiti di QPS.
- La fatturazione non è stata abilitata sul tuo account.
- Il credito mensile di 200 $o un limite di utilizzo autoimposto è stato superato.
- Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).
-
REQUEST_DENIEDche indica che la tua richiesta è stata rifiutata, in genere perché:- La richiesta non include una chiave API.
- Il parametro
keynon è valido.
UNKNOWN_ERRORche indica un errore sconosciuto.
Quando il servizio Places restituisce risultati JSON da una ricerca, li inserisce
in un array predictions. Anche se il servizio non restituisce
risultati (ad esempio se location è remoto),
restituisce comunque un array predictions vuoto. Le risposte XML sono costituite
da zero o più elementi <prediction>.
PlaceAutocompletePrediction
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
obbligatorio | stringa |
Contiene il nome leggibile del risultato restituito. Per
i risultati |
|
obbligatorio | Array<PlaceAutocompleteMatchedSubstring> |
Un elenco di sottostringhe che descrivono la posizione del termine inserito nel testo del risultato della previsione, in modo che il termine possa essere evidenziato se vuoi. Per ulteriori informazioni, consulta PlaceAutocompleteMatchedSubstring. |
|
obbligatorio | PlaceAutocompleteStructuredFormat |
Fornisce testo preformattato che può essere mostrato nei risultati del completamento automatico. Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico. Per ulteriori informazioni, consulta PlaceAutocompleteStructuredFormat. |
|
obbligatorio | Array<PlaceAutocompleteTerm> |
Contiene un array di termini che identificano ogni sezione della descrizione restituita (una sezione della descrizione termina generalmente con una virgola). Ogni voce dell'array ha un campo
Per ulteriori informazioni, consulta PlaceAutocompleteTerm. |
|
facoltativo | integer |
La distanza in linea retta in metri dall'origine. Questo campo viene restituito solo per le richieste effettuate con un |
|
facoltativo | stringa |
Un identificatore testuale che identifica in modo univoco un luogo. Per recuperare le informazioni sul luogo, passa questo identificatore nel campo placeId di una richiesta dell'API Places. Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo. |
|
facoltativo | stringa |
Vedi place_id. |
|
facoltativo | Array<stringa> |
Contiene un array di tipi che si applicano a questo luogo. Ad esempio:
|
PlaceAutocompleteMatchedSubstring
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
obbligatorio | numero |
Lunghezza della sottostringa corrispondente nel testo del risultato della previsione. |
|
obbligatorio | numero |
Posizione iniziale della sottostringa corrispondente nel testo del risultato della previsione. |
PlaceAutocompleteStructuredFormat
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
obbligatorio | stringa |
Contiene il testo principale di una previsione, solitamente il nome del luogo. |
|
obbligatorio | Array<PlaceAutocompleteMatchedSubstring> |
Contiene un array con il valore Per ulteriori informazioni, consulta PlaceAutocompleteMatchedSubstring. |
|
facoltativo | stringa |
Contiene il testo secondario di una previsione, in genere la posizione del luogo. |
|
facoltativo | Array<PlaceAutocompleteMatchedSubstring> |
Contiene un array con il valore Per ulteriori informazioni, consulta PlaceAutocompleteMatchedSubstring. |
PlaceAutocompleteTerm
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
obbligatorio | numero |
Definisce la posizione iniziale di questo termine nella descrizione, misurata in caratteri Unicode |
|
obbligatorio | stringa |
Il testo del termine. |