Completamento automatico delle query (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

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 language non viene fornito, l'API tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-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 da location e radius; i risultati al di fuori dell'area definita potrebbero comunque essere visualizzati.

    Il parametro location potrebbe essere sostituito se query contiene una località esplicita, ad esempio Market in Barcelona. L'utilizzo delle virgolette intorno alla query può anche influenzare il peso assegnato a location e radius.
  • offset

    La posizione, nel termine di input, dell'ultimo carattere utilizzato dal servizio per trovare le previsioni corrispondenti. Ad esempio, se l'input è Google e l'offset è 3, il servizio corrisponderà a Goo. La stringa determinata dall'offset viene confrontata solo con la prima parola del termine di input. Ad esempio, se il termine di input è Google abc e l'offset è 3, il servizio tenterà di trovare una corrispondenza con Goo 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 location e un parametro radius. 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 keyword o name: 50.000 metri
      • senza keyword o name
        • 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 errore INVALID_REQUEST.
    • 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 OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto della risposta. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato. Questo campo non viene restituito sempre e i suoi contenuti sono soggetti a modifiche.

facoltativo Array<string>

Quando il servizio restituisce informazioni aggiuntive sulla specifica della richiesta, potrebbe essere presente un campo info_messages aggiuntivo all'interno dell'oggetto della risposta. Questo campo viene restituito solo per le richieste andate a buon fine. Potrebbe non essere sempre restituito e i suoi contenuti sono soggetti a modifiche.

PlacesAutocompleteStatus

Codici di stato restituiti dal servizio.

  • OK, che indica che la richiesta API è andata a buon fine.
  • ZERO_RESULTS che 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_REQUEST indica che la richiesta API non è corretta, in genere a causa del parametro input mancante.
  • OVER_QUERY_LIMIT che 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).
    Per saperne di più su come risolvere questo errore, consulta le Domande frequenti su Maps.
  • REQUEST_DENIED che indica che la tua richiesta è stata rifiutata, in genere perché:
    • La richiesta non contiene una chiave API.
    • Il parametro key non è valido.
  • UNKNOWN_ERROR indica 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 establishment, di solito si tratta del nome dell'attività. Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.

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 value, contenente il testo del termine, e un campo offset, che definisce la posizione iniziale di questo termine nella descrizione, misurata in caratteri Unicode.

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 origin.

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: [ "political", "locality" ] o [ "establishment", "geocode", "beauty_salon" ]. L'array può contenere più valori. Scopri di più sui tipi di luoghi.

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 offset e length. Questi 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.

facoltativo stringa

Contiene il testo secondario di una previsione, in genere la posizione del luogo.

facoltativo Array<PlaceAutocompleteMatchedSubstring>

Contiene un array con il valore offset e length. Questi 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.

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.