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 le 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 Plus 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 vuole. Puoi inviare una richiesta Place Details (Legacy) per ulteriori informazioni su uno dei luoghi restituiti.

Una richiesta Place Autocomplete (Legacy) è un URL HTTP nel 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 Place Autocomplete (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

componenti

Un raggruppamento di luoghi a cui vuoi limitare i risultati. Puoi utilizzare i componenti per filtrare in base a un massimo di 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 limita 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 limiterà i risultati ai luoghi negli Stati Uniti e nei relativi 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: Elenco dei codici paese ISO 3166 o sulla piattaforma di navigazione online ISO.

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à

Il punto attorno 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" potrebbe essere sostituito se la "query" contiene una località esplicita, ad esempio "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 viene specificato, l'API utilizza la priorità 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. Tieni presente che i valori est/ovest sono limitati all'intervallo -180, 180 e i valori nord/sud sono limitati all'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ù 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. Tieni presente che i valori est/ovest sono limitati all'intervallo -180, 180 e i valori nord/sud sono limitati all'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 termine. 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 viene istruito a preferire la visualizzazione dei risultati all'interno di quel 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.

  • Autocomplete: 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

regione

Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica 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 conclusa una sessione, il token non è più valido; l'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 Place Autocomplete e Place Details all'interno di una sessione appartengano allo stesso progetto della console Cloud.
  • Assicurati di passare un token di sessione univoco per ogni nuova sessione. Se utilizzi lo stesso token per più di una sessione, 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, non di una preferenza, 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 potrebbe essere restituito solo con types=lodging e non con types=restaurant.

Per il valore del parametro types puoi specificare:

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

    types=book_store|cafe

  • Qualsiasi singolo filtro 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.
  • Qualsiasi tipo della Tabella 1 o della Tabella 2 viene combinato con uno dei filtri della Tabella 3.

Esempi di Place Autocomplete (Legacy)

Una richiesta di attività contenenti la stringa "Amoeba" all'interno di un'area centrata a San Francisco, in California:

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
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 sempre restituito 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.

Di particolare interesse all'interno dei risultati sono gli elementi place_id, che possono essere utilizzati per richiedere dettagli più specifici sul luogo utilizzando una query separata. Consulta Richieste di Place Details (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. Consulta la sezione 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 una certa 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 è andata a buon fine.
  • ZERO_RESULTS per indicare 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 una delle seguenti condizioni:
    • 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é:
    • Nella richiesta manca 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 scelto.

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

main_text

required stringa

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

main_text_matched_substrings

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

Per saperne di più, consulta PlaceAutocompleteMatchedSubstring.

secondary_text

facoltativo stringa

Contiene il testo secondario di una previsione, in genere 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
required numero

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

required stringa

Il testo del termine.

Ottimizzazione di Place Autocomplete (Legacy)

Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete (Legacy).

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget Place Autocomplete (Legacy) dell'API Maps JavaScript, il widget Place Autocomplete (Legacy) di Places SDK for Android o il controllo UI Place Autocomplete (Legacy) di Places SDK for iOS.
  • Comprendi i campi di dati essenziali di Place Autocomplete (Legacy) fin dall'inizio.
  • I campi di polarizzazione e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che l'app si degradi correttamente se l'API restituisce un errore.
  • Assicurati che la tua app gestisca i casi in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo di utilizzo del servizio Place Autocomplete (Legacy), utilizza le maschere di campo 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 ai prezzi di SKU: Autocomplete - Per Request e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a 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 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 scegliere l'implementazione di Place Autocomplete (Legacy) più economica per la tua applicazione, individua nella tabella seguente la riga corrispondente alle esigenze della tua applicazione.
Cosa serve per la tua richiesta Media delle richieste di Place Autocomplete (Legacy) prima che un utente selezioni una previsione Implementazione consigliata
Place Details diversi dall'indirizzo e dalla posizione, ad esempio il nome del luogo, lo stato dell'attività o l'orario di apertura Qualsiasi numero Place Autocomplete basato su sessione (legacy) con Place Details (legacy)
Solo l'indirizzo e la latitudine/longitudine della previsione selezionata Quattro o meno Place Autocomplete (Legacy) per richiesta con l'API Geocoding
Solo l'indirizzo e la latitudine/longitudine della previsione selezionata Più di quattro Place Autocomplete basato su sessione (legacy) per applicazioni solo per indirizzi

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (Legacy) per la tua applicazione, a seconda delle prestazioni di 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 trovare il numero medio di richieste per la tabella, analizza quanti caratteri un utente digita in media prima di selezionare una previsione di Place Autocomplete (Legacy) nella tua applicazione.

Place Autocomplete (Legacy) basato su sessione con Place Details (Legacy)

Utilizza Place Autocomplete (Legacy) basato su sessione 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 (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione più gli SKU dei dati di Places applicabili, a seconda dei campi dei dati dei luoghi richiesti.1

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

Implementazione programmatica
Utilizza un token di sessione con le richieste 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 Place Autocomplete (Legacy)
  3. Il parametro fields che specifica i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno

Place Autocomplete (Legacy) per richiesta con l'API Geocoding

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

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora minore di caratteri.

Place Autocomplete basato su sessione (legacy) per applicazioni solo per indirizzi

Utilizza Place Autocomplete (Legacy) basato su sessione 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 Place Autocomplete (Legacy) sia la richiesta Place Details (Legacy) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le tue richieste 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 Place Autocomplete (Legacy)
  3. Il parametro fields che specifica i campi di dati Basic Data, come indirizzo e geometria

Valuta la possibilità di ritardare le richieste di Place Autocomplete (Legacy)
Puoi adottare strategie come ritardare una richiesta di Place Autocomplete (Legacy) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se effettui 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 poi seleziona una previsione per la quale effettui una richiesta API Geocoding, il costo totale sarà di 4 richieste Place Autocomplete (Legacy) Per Request + Geocoding.1

Se ritardando le richieste puoi ridurre la media delle richieste programmatiche a meno 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 nuova pressione di un tasto.

Valuta la possibilità di adottare le best practice per il rendimento 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 le prestazioni di Place Autocomplete (Legacy):

  • Aggiungi limitazioni in base al paese, località preferita e (per le implementazioni programmatiche) preferenza sulla lingua all'implementazione di Place Autocomplete (Legacy). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se Place Autocomplete (Legacy) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
  • In 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 in base al nome o all'indirizzo, utilizza una richiesta Place Details (Legacy). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
    Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
    • Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" genera 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à

Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Place Autocomplete (Legacy) preferisce mostrare i risultati all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. 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.