Query Autocomplete (Legacy) può essere utilizzato per fornire una previsione della query per le ricerche geografiche basate su testo, restituendo query suggerite durante la digitazione.
Richieste Query Autocomplete (Legacy)
Query Autocomplete (Legacy) fa parte dell'API Places (Legacy) e condivide una chiave API e una quota con l'API Places (Legacy).
Query Autocomplete (Legacy) ti consente di aggiungere previsioni di query geografiche on the fly alla tua applicazione. Anziché cercare una località 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 corrispondenti alla stringa. Poiché Query Autocomplete (Legacy) può trovare corrispondenze sia con parole intere sia con sottostringhe, le applicazioni possono inviare query mentre l'utente digita per fornire previsioni in tempo reale.
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 alcuni parametri.
Come di consueto negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&). L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.
Parametri obbligatori
-
input
La stringa di testo in cui cercare. Il servizio Place Autocomplete restituirà le 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 leggibile sia per l'utente sia per le persone del posto. Per raggiungere questo obiettivo, restituisce gli indirizzi nella lingua locale, traslitterati in un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua, che viene 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 eseguire la ricerca. Il servizio Places utilizza la posizione per influenzare 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 sostituito sequerycontiene una località esplicita, ad esempioMarket in Barcelona. L'utilizzo delle virgolette intorno alla query può anche influenzare il peso assegnato alocationeradius. -
offset
La posizione, nel termine di input, dell'ultimo carattere utilizzato dal servizio per trovare le previsioni corrispondenti. Ad esempio, se l'input è
Googlee l'offset è 3, il servizio corrisponderà aGoo. La stringa determinata dall'offset viene confrontata solo con 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 termine. In genere, l'offset deve essere impostato sulla posizione del cursore del testo. -
raggio
Definisce la distanza (in metri) entro la quale restituire i risultati dei luoghi. Puoi influenzare i risultati in base a un cerchio specificato passando un parametro
locatione un parametroradius. In questo modo, il servizio Places viene istruito a preferire la visualizzazione dei 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 radius non verrà accettato e verrà generato un erroreINVALID_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 di Query Autocomplete (Legacy) vengono restituite nel formato indicato dal flag output nel percorso della richiesta dell'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 i risultati JSON di 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>.
PlacesQueryAutocompleteResponse
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
required | Array<PlaceAutocompletePrediction> |
Contiene un array di previsioni. Per saperne di più, consulta PlaceAutocompletePrediction. |
|
required | PlacesAutocompleteStatus |
Contiene lo stato della richiesta e può contenere informazioni di debug per aiutarti a individuare il motivo per cui 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<string> |
Quando il servizio restituisce informazioni aggiuntive sulla specifica della richiesta, potrebbe essere presente un campo |
PlacesAutocompleteStatus
Codici di stato restituiti dal servizio.
OK, che indica che la richiesta API è andata a buon fine.-
ZERO_RESULTSche indica che la ricerca è andata a buon fine, ma non ha restituito risultati. Questo può accadere se alla ricerca sono stati passati dei limiti in una località remota. -
INVALID_REQUESTindica che la richiesta API non è corretta, 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.
- È stato superato il credito mensile di 200 $o un limite di utilizzo autoimposto.
- 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 contiene una chiave API.
- Il parametro
keynon è valido.
UNKNOWN_ERRORindica un errore sconosciuto.
Quando il servizio Places restituisce i risultati JSON di 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 |
|---|---|---|---|
|
required | stringa |
Contiene il nome leggibile del risultato restituito. Per i risultati di |
|
required | 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 lo si desidera. Per saperne di più, consulta PlaceAutocompleteMatchedSubstring. |
|
required | PlaceAutocompleteStructuredFormat |
Fornisce testo preformattato che può essere mostrato nei risultati di completamento automatico. Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico. Per ulteriori informazioni, consulta PlaceAutocompleteStructuredFormat. |
|
required | Array<PlaceAutocompleteTerm> |
Contiene un array di termini che identificano ogni sezione della descrizione restituita (una sezione della descrizione è generalmente terminata con una virgola). Ogni voce dell'array ha un campo Per saperne di più, consulta PlaceAutocompleteTerm. |
|
facoltativo | integer |
La distanza in linea retta in metri dal punto di partenza. 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 informazioni sul luogo, passa questo identificatore nel campo placeId di una richiesta API Places. Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo. |
|
facoltativo | stringa |
Vedi place_id. |
|
facoltativo | Array<string> |
Contiene un array di tipi che si applicano a questo luogo. Ad esempio:
|
PlaceAutocompleteMatchedSubstring
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
required | numero |
Lunghezza della sottostringa corrispondente nel testo del risultato della previsione. |
|
required | numero |
Posizione iniziale della sottostringa corrispondente nel testo del risultato della previsione. |
PlaceAutocompleteStructuredFormat
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
required | stringa |
Contiene il testo principale di una previsione, in genere il nome del luogo. |
|
required | Array<PlaceAutocompleteMatchedSubstring> |
Contiene un array con il valore Per saperne di più, 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 saperne di più, consulta PlaceAutocompleteMatchedSubstring. |
PlaceAutocompleteTerm
| Campo | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
|
required | numero |
Definisce la posizione iniziale di questo termine nella descrizione, misurata in caratteri Unicode |
|
required | stringa |
Il testo del termine. |