Place Autocomplete (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

Place Autocomplete (Legacy) è un servizio web che restituisce previsioni relative ai luoghi in risposta a una richiesta HTTP. La richiesta specifica una stringa di ricerca testuale e limiti geografici facoltativi. Il servizio può essere utilizzato per fornire la funzionalità di completamento automatico per le ricerche geografiche basate su testo, restituendo luoghi come attività, indirizzi e punti d'interesse durante la digitazione dell'utente.

Richieste Place Autocomplete (Legacy)

Place Autocomplete (legacy) fa parte dell'API Places e condivide una chiave API e quote con l'API Places.

Place Autocomplete (legacy) può trovare corrispondenze con parole intere e sottostringhe, risolvendo nomi di luoghi, indirizzi e Plus Code. Le applicazioni possono quindi inviare query mentre l'utente digita, per fornire previsioni dei luoghi in tempo reale.

Devi formattare correttamente i plus code. Ciò significa che devi eseguire l'escape dell'URL del segno più in %2B e degli spazi in %20.

  • Un codice globale è un prefisso di quattro caratteri e un codice locale di almeno sei caratteri. Ad esempio, il codice globale di escape dell'URL 849VCWC8+R9 è 849VCWC8%2BR9.
  • Un codice composto è un codice locale di almeno sei caratteri con una posizione esplicita. Ad esempio, il codice composto con escape URL CWC8+R9 Mountain View, CA, USA è CWC8%2BR9%20Mountain%20View%20CA%20USA.

Le previsioni restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo che desidera. Puoi inviare una richiesta Dettagli luogo (legacy) per ottenere maggiori informazioni su uno qualsiasi dei luoghi restituiti.

Una richiesta Place Autocomplete (legacy) è un URL HTTP del seguente formato:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

dove output può essere uno dei seguenti valori:

  • json (consigliato) indica l'output in JavaScript Object Notation (JSON)
  • xml indica l'output in formato XML

Per avviare una richiesta di Place Autocomplete (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

  • input

    La stringa di testo in cui eseguire la ricerca. 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

  • componenti

    Un raggruppamento di luoghi a cui vuoi limitare i risultati. Puoi utilizzare i componenti per filtrare fino a 5 paesi. I paesi devono essere trasmessi come codice paese di due caratteri compatibile con ISO 3166-1 Alpha-2. Ad esempio: components=country:fr limiterebbe i risultati ai luoghi in Francia. Più paesi devono essere trasmessi come più filtri country:XX, con il carattere barra verticale | come separatore. Ad esempio: components=country:us|country:pr|country:vi|country:gu|country:mp limiterebbe i risultati ai luoghi all'interno degli Stati Uniti e dei loro territori organizzati non incorporati.

    Nota: se ricevi risultati imprevisti con un codice paese, verifica di utilizzare un codice che includa i paesi, i territori dipendenti e le aree speciali di interesse geografico che intendi utilizzare. Puoi trovare informazioni sui codici su Wikipedia: List of ISO 3166 country codes o sulla ISO Online Browsing Platform.

  • language

    La lingua in cui restituire i risultati.

    • Consulta l'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, quindi 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 che per gli abitanti del luogo. 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 via in ungherese.

  • località

    Il punto intorno al quale recuperare le informazioni sul luogo. Deve essere specificato come latitude,longitude. Quando specifichi una località, devi fornire anche il parametro radius. Se radius non viene fornito, il parametro location viene ignorato.

    Quando utilizzi l'API Ricerca testuale, il parametro `location` può essere sostituito se la `query` contiene una località esplicita come `Mercato a Barcellona`.

  • locationbias

    Preferisci i risultati in un'area specificata, indicando un raggio più latitudine/longitudine o due coppie di latitudine/longitudine che rappresentano i punti di un rettangolo. Se questo parametro non è specificato, l'API utilizza la ponderazione dell'indirizzo IP per impostazione predefinita.

    • IP bias: indica all'API di utilizzare il biasing degli indirizzi IP. Passa la stringa ipbias (questa opzione non ha parametri aggiuntivi).
    • Circolare: una stringa che specifica il raggio in metri, più latitudine/longitudine in gradi decimali. Utilizza il formato seguente: circle:radius@lat,lng.
    • Rettangolare: una stringa che specifica due coppie di latitudine/longitudine in gradi decimali, che rappresentano i punti sud/ovest e nord/est di un rettangolo. Utilizza il seguente formato:rectangle:south,west|north,east. Nota che i valori est/ovest sono inclusi nell'intervallo -180, 180 e i valori nord/sud sono inclusi nell'intervallo -90, 90.

  • locationrestriction

    Limita i risultati a un'area specificata, indicando un raggio più latitudine/longitudine o due coppie di latitudine/longitudine che rappresentano i punti di un rettangolo.

    • Circolare: una stringa che specifica il raggio in metri, più lat/lng in gradi decimali. Utilizza il formato seguente: circle:radius@lat,lng.
    • Rettangolare: una stringa che specifica due coppie di lat/lng in gradi decimali, che rappresentano i punti sud/ovest e nord/est di un rettangolo. Utilizza il seguente formato:rectangle:south,west|north,east. Nota che i valori est/ovest sono inclusi nell'intervallo -180, 180 e i valori nord/sud sono inclusi nell'intervallo -90, 90.

  • 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 troverà una corrispondenza con 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 periodo. In genere, l'offset deve essere impostato sulla posizione del cursore del testo.

  • origine

    Il punto di origine da cui calcolare la distanza in linea retta fino alla destinazione (restituita come distance_meters). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Deve essere specificato come latitude,longitude.

  • 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 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 verrà restituito un INVALID_REQUEST.
    • Completamento automatico delle query: 50.000 metri
    • Ricerca testuale: 50.000 metri

  • regione

    Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk" (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

  • sessiontoken

    Una stringa casuale che identifica una sessione di completamento automatico ai fini della fatturazione.

    La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo e viene effettuata una chiamata a Place Details. Ogni sessione può avere più query, seguite dalla selezione di un luogo. Le chiavi API utilizzate per ogni richiesta all'interno di una sessione devono appartenere allo stesso progetto della console Google Cloud. Una volta terminata una sessione, il token non è più valido; la tua app deve generare un nuovo token per ogni sessione. Se il parametro sessiontoken viene omesso o se riutilizzi un token di sessione, la sessione viene addebitata come se non fosse stato fornito alcun token di sessione (ogni richiesta viene fatturata separatamente).

    Ti consigliamo di seguire queste linee guida:

    • Utilizza i token di sessione per tutte le sessioni di completamento automatico.
    • Genera un nuovo token per ogni sessione. Si consiglia l'uso di UUID versione 4.
    • Assicurati che le chiavi API utilizzate per tutte le richieste di Place Autocomplete e Place Details all'interno di una sessione appartengano allo stesso progetto della console Cloud.
    • Assicurati di trasmettere un token di sessione univoco per ogni nuova sessione. Se utilizzi lo stesso token per più sessioni, ogni richiesta verrà fatturata singolarmente.

  • strictbounds

    Restituisce solo i luoghi che si trovano rigorosamente all'interno della regione definita da location e radius. Si tratta di una limitazione, piuttosto che di un bias, il che significa che i risultati al di fuori di questa regione non verranno restituiti anche se corrispondono all'input dell'utente.

  • tipi

    Puoi limitare i risultati di una richiesta di Place Autocomplete a un determinato tipo passando il parametro types. Questo parametro specifica un tipo o una raccolta di tipi, come elencato in Tipi di luoghi. Se non viene specificato nulla, vengono restituiti tutti i tipi.

    Un luogo può avere un solo tipo principale tra quelli elencati nella tabella 1 o nella tabella 2. Ad esempio, un hotel in cui viene servito cibo può essere restituito solo con types=lodging e non con types=restaurant.

    Per il valore del parametro types puoi specificare:

    • Fino a cinque valori da Tabella 1 o Tabella 2. Se hai più valori, separali con una barra verticale |. Ad esempio:

      types=book_store|cafe

    • Qualsiasi filtro singolo supportato nella Tabella 3. Non puoi combinare raccolte di tipi diversi.

    La richiesta verrà rifiutata con un errore INVALID_REQUEST se:

    • Sono stati specificati più di cinque tipi.
    • Sono presenti tipi non riconosciuti.
    • Tutti i tipi di Tabella 1 o Tabella 2 vengono combinati con uno qualsiasi dei filtri della Tabella 3.

Esempi di Place Autocomplete (legacy)

Una richiesta di attività contenenti la stringa "Amoeba" in un'area centrata su San Francisco, CA:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

La stessa richiesta, limitata ai risultati entro 500 metri da Ashbury St e Haight St, San Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Una richiesta di indirizzi contenenti "Vict" con risultati in francese:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Una richiesta di città contenenti "Vict" con risultati in portoghese brasiliano:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Tieni presente che dovrai sostituire la chiave API in questi esempi con la tua chiave.

Risposta di Place Autocomplete (legacy)

Le risposte di Place Autocomplete (legacy) vengono restituite nel formato indicato dal flag output nel percorso dell'URL della richiesta. I risultati riportati di seguito sono indicativi di ciò che potrebbe essere restituito per una query con i seguenti parametri:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Campo Obbligatorio Tipo Descrizione
obbligatorio Array<PlaceAutocompletePrediction>

Contiene un array di previsioni.

Per saperne di più, consulta PlaceAutocompletePrediction.

elemento 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 saperne di più, 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 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 il suo contenuto è soggetto a modifiche.

All'interno dei risultati, sono particolarmente interessanti gli elementi place_id, che possono essere utilizzati per richiedere dettagli più specifici sul luogo utilizzando una query separata. Consulta le richieste Dettagli luogo (legacy).

Una risposta XML è costituita da un singolo elemento <AutocompletionResponse> con due tipi di elementi secondari:

  • Un singolo elemento <status> contiene i metadati della richiesta. Vedi Codici di stato di seguito.
  • Zero o più elementi <prediction>, ciascuno contenente informazioni su un singolo luogo. Per informazioni su questi risultati, consulta Risultati di Place Autocomplete (Legacy). L'API Places restituisce fino a 5 risultati.

Ti consigliamo di utilizzare json come flag di output preferito a meno che la tua applicazione non richieda xml per qualche motivo. L'elaborazione degli alberi XML richiede attenzione, in modo da fare riferimento ai nodi e agli elementi corretti. Per assistenza con l'elaborazione di XML, consulta Elaborazione di XML con XPath.

PlacesAutocompleteStatus

Codici di stato restituiti dal servizio.

  • OK che indica che la richiesta API è stata eseguita correttamente.
  • 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 contiene una chiave API.
    • Il parametro key non è valido.
  • UNKNOWN_ERROR che 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
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 in modo programmatico l'indirizzo formattato.

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

Per saperne di più, consulta PlaceAutocompleteMatchedSubstring.

elemento obbligatorio PlaceAutocompleteStructuredFormat

Fornisce testo preformattato che può essere mostrato nei risultati del completamento automatico. Questi contenuti devono essere letti così come sono. Non analizzare in modo programmatico l'indirizzo formattato.

Per ulteriori informazioni, consulta PlaceAutocompleteStructuredFormat.

elemento 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 saperne di più, 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 informazioni sul luogo, passa questo identificatore nel campo placeId di una richiesta dell'API Places. Per saperne di più sugli ID località, consulta la panoramica degli ID località.

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

main_text

obbligatorio stringa

Contiene il testo principale di una previsione, di solito il nome del luogo.

main_text_matched_substrings

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

Per saperne di più, consulta PlaceAutocompleteMatchedSubstring.

secondary_text

facoltativo stringa

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

secondary_text_matched_substrings

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

Per saperne di più, consulta PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

Campo Obbligatorio Tipo Descrizione
obbligatorio numero

Definisce la posizione iniziale di questo termine nella descrizione, misurata in caratteri Unicode

elemento obbligatorio stringa

Il testo del termine.

Ottimizzazione di Place Autocomplete (legacy)

Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio Place Autocomplete (Legacy).

Ecco alcune linee guida generali:

Best practice per l'ottimizzazione dei costi

Ottimizzazione di base dei costi

Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete (legacy), utilizza le maschere dei campi nei widget Place Details (legacy) e Place Autocomplete (legacy) per restituire solo i campi di dati di Place Autocomplete (legacy) di cui hai bisogno.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica di Place Autocomplete (legacy) per accedere a SKU: Autocomplete - Per Request pricing e richiedi i risultati dell'API Geocoding sul luogo selezionato anziché su Place Details (legacy). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:

  • Se hai bisogno solo della latitudine e della longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata a Place Details (legacy).
  • Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di Place Autocomplete (Legacy), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.
Per assistenza nella scelta dell'implementazione di Place Autocomplete (legacy) più adatta alle tue esigenze, seleziona la scheda corrispondente alla risposta alla seguente domanda.

La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?

Sì, sono necessari ulteriori dettagli

Utilizza Place Autocomplete basato sulla sessione (legacy) con Place Details (legacy).
Poiché la tua applicazione richiede Place Details (legacy), come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Place Autocomplete (legacy) deve utilizzare un token di sessione (a livello di programmazione o integrato nei widget JavaScript, Android o iOS) per sessione, oltre agli SKU di dati Places applicabili, a seconda dei campi di dati sui luoghi che richiedi.1

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste di Place Autocomplete (legacy) sia le richieste di Place Details (legacy) nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi dati di Place Autocomplete (legacy) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste di Place Autocomplete (Legacy). Quando richiedi Place Details (legacy) sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta di Place Autocomplete (legacy)
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete (Legacy)
  3. Il parametro fields che specifica i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno

No, sono necessari solo indirizzo e posizione

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (legacy) per la tua applicazione, a seconda del rendimento dell'utilizzo di Place Autocomplete (legacy). L'efficienza di Place Autocomplete (legacy) di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza quanti caratteri digita in media un utente prima di selezionare una previsione di Place Autocomplete (Legacy) nella tua applicazione.

In media, i tuoi utenti selezionano una previsione di Place Autocomplete (legacy) in quattro o meno richieste?

Sì

Implementa Place Autocomplete (legacy) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionato.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'esecuzione di quattro richieste Autocomplete - Per Request più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato costa meno di Place Autocomplete (legacy) per sessione.1

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con ancora meno caratteri.

No

Utilizza Place Autocomplete basato sulla sessione (legacy) con Place Details (legacy).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Place Autocomplete (Legacy) supera il costo dei prezzi per sessione, la tua implementazione di Place Autocomplete (Legacy) deve utilizzare un token di sessione sia per le richieste di Place Autocomplete (Legacy) sia per la richiesta di Place Details (Legacy) associata per sessione. 1

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste di Place Autocomplete (legacy) sia le richieste di Place Details (legacy) nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi necessari.

Implementazione programmatica
Utilizza un token di sessione con le richieste di Place Autocomplete (Legacy). Quando richiedi i dettagli dei luoghi (legacy) relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta di Place Autocomplete (legacy)
  2. Il token di sessione utilizzato nella richiesta di Place Autocomplete (legacy)
  3. Il parametro fields che specifica i campi Dati di base come indirizzo e geometria

Valuta la possibilità di ritardare le richieste di Place Autocomplete (legacy)
Puoi utilizzare strategie come il ritardo di una richiesta di Place Autocomplete (legacy) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione effettui meno richieste. Ad esempio, effettuare richieste di Place Autocomplete (legacy) per ogni carattere dopo che l'utente ha digitato il terzo carattere significa che se l'utente digita sette caratteri e seleziona un suggerimento per il quale effettui una richiesta dell'API Geocoding, il costo totale sarà per 4 Place Autocomplete (legacy) per richiesta + geocodifica.1

Se ritardando le richieste puoi ridurre la media delle richieste di programmazione al di sotto di quattro, puoi seguire le indicazioni per l'implementazione di Place Autocomplete (Legacy) con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere le previsioni a ogni nuovo tasto premuto.

Valuta la possibilità di adottare le best practice per le prestazioni per aiutare gli utenti a ottenere la previsione che stanno cercando con meno caratteri.

  1. Per i costi, consulta i listini prezzi di Google Maps Platform.

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Place Autocomplete (legacy):

  • Aggiungi limitazioni in base al paese, bias di località, e (per le implementazioni programmatiche) preferenza della lingua all'implementazione di Place Autocomplete (legacy). La preferenza della lingua non è necessaria con i widget, in quanto questi scelgono le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
  • Se Place Autocomplete (Legacy) è accompagnato da una mappa, puoi impostare la preferenza per la località in base all'area visibile della mappa.
  • Nelle situazioni in cui un utente non sceglie una delle previsioni di Place Autocomplete (Legacy), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserisca query per un luogo specifico per nome o indirizzo, utilizza una richiesta Dettagli luogo (legacy). Se i risultati sono previsti solo in una regione specifica, utilizza la ponderazione della località.
    Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
    • Gli utenti che inseriscono indirizzi di sottosedi, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" produce una previsione parziale in Place Autocomplete (legacy).
    • Utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Bias di località

Inclina i risultati verso un'area specificata passando un parametro location e un parametro radius. In questo modo, Place Autocomplete (legacy) preferisce mostrare i risultati all'interno dell'area definita. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.

Limitazione della località

Limita i risultati a un'area specificata passando un parametro locationRestriction.

Puoi anche limitare i risultati alla regione definita da location e da un parametro radius aggiungendo il parametro strictbounds. In questo modo, Place Autocomplete (legacy) restituisce solo i risultati all'interno di quella regione.