Completamento automatico delle query (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

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 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 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 da location e radius; i risultati al di fuori dell'area definita potrebbero comunque essere visualizzati.

    Il parametro location potrebbe essere ignorato se query contiene una località esplicita come Market in Barcelona. L'utilizzo delle virgolette intorno alla query può anche influire sul peso assegnato a location e radius.
  • 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 è Google e l'offset è 3, il servizio troverà una corrispondenza con Goo. La stringa determinata dall'offset viene confrontata con solo 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 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 location e un parametro radius. 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 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 raggio non verrà accettato e restituirà un 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 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 OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto di risposta. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato. Questo campo non viene sempre restituito e il suo contenuto è soggetto a modifiche.

facoltativo Array<stringa>

Quando il servizio restituisce ulteriori informazioni 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 riuscite. Potrebbe non essere sempre restituito e il suo contenuto è soggetto 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. Ciò può verificarsi se nella ricerca sono stati passati limiti in una posizione remota.
  • INVALID_REQUEST che indica che la richiesta API non è formattata correttamente, 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.
    • 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).
    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 include una chiave API.
    • Il parametro key non è valido.
  • UNKNOWN_ERROR che 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 establishment, in genere si tratta del nome dell'attività. Questi contenuti devono essere letti così come sono. Non analizzare l'indirizzo formattato in modo programmatico.

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

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: [ "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
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 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 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 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 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.