Questa pagina è stata tradotta dall'API Cloud Translation.

Completamento automatico (novità)

Seleziona la piattaforma: Android iOS JavaScript Web Service

Il servizio Autocomplete (nuovo) è un servizio web che restituisce previsioni sui luoghi e sulle query in risposta a una richiesta HTTP. Nella richiesta, specifica una stringa di ricerca testuale e limiti geografici che controllano l'area di ricerca.

Il servizio Autocomplete (nuovo) può trovare corrispondenze con parole complete e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e plus code. Le applicazioni possono quindi inviare query man mano che l'utente digita le query, per fornire previsioni immediate e delle query.

La risposta dell'API Autocomplete (nuova) può contenere due tipi di previsioni:

Previsioni sui luoghi: luoghi, come attività, indirizzi e punti d'interesse, in base alla stringa di testo di input e all'area di ricerca specificate. Le previsioni sui luoghi vengono restituite per impostazione predefinita.
Previsioni sulle query: stringhe di query corrispondenti alla stringa di testo di input e all'area di ricerca. Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere previsioni delle query alla risposta.

Ad esempio, chiami l'API utilizzando come input una stringa che contiene un input parziale dell'utente, "Sicilian piz", con l'area di ricerca limitata a San Francisco, CA. La risposta contiene un elenco di previsioni sui luoghi corrispondenti alla stringa di ricerca e all'area di ricerca, come il ristorante "Sicilian Pizza Kitchen", insieme ai dettagli sul luogo.

Le previsioni dei luoghi restituite sono progettate per essere presentate all'utente per aiutarlo a selezionare il luogo desiderato. Puoi inviare una richiesta Dettagli luogo (nuova) per ottenere ulteriori informazioni su una delle previsioni di un luogo restituite.

La risposta può anche contenere un elenco di previsioni delle query corrispondenti alla stringa di ricerca e all'area di ricerca, ad esempio "Pizza e pasta alla siciliana". Ogni previsione di query nella risposta include il campo text contenente una stringa di ricerca testuale consigliata. Utilizza la stringa come input per la ricerca testuale (nuova) al fine di eseguire una ricerca più dettagliata.

Explorer API ti consente di effettuare richieste in tempo reale per acquisire familiarità con le opzioni API e API:

Prova!

Richieste di completamento automatico (nuove)

Una richiesta Autocomplete (Nuova) è una richiesta POST HTTP a un URL nel formato:

https://places.googleapis.com/v1/places:autocomplete

Passa tutti i parametri nel corpo della richiesta JSON o nelle intestazioni come parte della richiesta POST. Ad esempio:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Informazioni sulla risposta

Autocomplete (New) restituisce un oggetto JSON come risposta. Nella risposta:

L'array suggestions contiene tutti i luoghi e le query previsti in ordine in base alla loro pertinenza percepita. Ogni luogo è rappresentato da un campo placePrediction e ogni query è rappresentata da un campo queryPrediction.
Un campo placePrediction contiene informazioni dettagliate sulla previsione di un singolo luogo, tra cui l'ID luogo e la descrizione testuale.
Un campo queryPrediction contiene informazioni dettagliate su una singola previsione di query.

Nota: il completamento automatico (nuova) restituisce cinque previsioni totali, come placePredictions, queryPredictions o una combinazione di entrambi, a seconda della richiesta. Ad esempio, se la richiesta non imposta includeQueryPredictions, il corpo della risposta include fino a cinque placePredictions. Se la richiesta imposta includeQueryPredictions, il corpo della risposta include fino a cinque previsioni in una combinazione di placePredictions e queryPredictions.

L'oggetto JSON completo ha il seguente formato:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Parametri obbligatori

input

La stringa di testo in cui eseguire la ricerca. Specifica parole e sottostringhe complete, nomi di luoghi, indirizzi e plus code. Il servizio di completamento automatico (nuovo) restituisce le corrispondenze dei candidati in base a questa stringa e ordina i risultati in base alla pertinenza percepita.

Parametri facoltativi

includedPrimaryTypes

Un luogo può avere un solo singolo tipo principale tra i tipi elencati nella Tabella A o nella Tabella B. Ad esempio, il tipo principale potrebbe essere "mexican_restaurant" o "steak_house".

Per impostazione predefinita, l'API restituisce tutte le posizioni in base al parametro input, a prescindere dal valore del tipo principale associato al luogo. Limita i risultati in modo che siano di un determinato tipo o tipo primario passando il parametro includedPrimaryTypes.

Utilizza questo parametro per specificare fino a cinque valori di tipo da Tabella A o Tabella B. Una località deve corrispondere a uno dei valori di tipo principale specificati da includere nella risposta.

Questo parametro può anche includere, invece, uno dei seguenti valori: (regions) o (cities). La raccolta di tipi (regions) applica filtri per aree o divisioni, come quartieri e codici postali. La raccolta dei tipi di (cities) applica un filtro ai luoghi che Google identifica come città.

La richiesta viene rifiutata con un errore INVALID_REQUEST se:
- Sono specificati più di cinque tipi.
- Viene specificato qualsiasi tipo oltre a (cities) o (regions).
- Vengono specificati tipi non riconosciuti.
Nota: il parametro includedPrimaryTypes funziona solo per il tipo principale del luogo, non per tutti i tipi associati al luogo. Sebbene ogni località abbia un tipo principale, non tutti i tipi principali sono supportati dall'API Places (novità). I tipi supportati includono quelli elencati nella Tabella A o nella Tabella B.
includeQueryPredictions

Se true, la risposta include previsioni sia sul luogo sia sulla query. Il valore predefinito è false, il che significa che la risposta include solo le previsioni dei luoghi.
includedRegionCodes

Includi solo i risultati dell'elenco di regioni specificate, specificate come un array di un massimo di 15 ccTLD ("dominio di primo livello") a due caratteri. Se omesso, non vengono applicate limitazioni alla risposta. Ad esempio, per limitare le regioni a Germania e Francia:
```
    "includedRegionCodes": ["de", "fr"]
```
Se specifichi sia locationRestriction sia includedRegionCodes, i risultati si trovano nell'area di intersezione delle due impostazioni.
inputOffset

L'offset Unicode su base zero che indica la posizione del cursore in input. La posizione del cursore può influire sulle previsioni restituite. Se vuoto, il valore predefinito è la lunghezza di input.

Nota: nella release di anteprima privata iniziale, questa proprietà era chiamata predictionTermOffset.
languageCode

La lingua preferita in cui restituire i risultati. I risultati potrebbero essere in lingue miste se la lingua utilizzata in input è diversa dal valore specificato da languageCode o se il luogo restituito non dispone di una traduzione dalla lingua locale in languageCode.
- Devi utilizzare i codici lingua IETF BCP-47 per specificare la lingua preferita.
- Se languageCode non viene specificato, l'API utilizza il valore specificato nell'intestazione Accept-Language. Se nessuno dei due è specificato, il valore predefinito è en. Se specifichi un codice lingua non valido, l'API restituisce un errore INVALID_ARGUMENT.
- La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Ciò influisce anche sulla capacità dell'API di correggere gli errori ortografici.
- L'API tenta di fornire un indirizzo che sia leggibile sia per l'utente sia per la popolazione locale, rispecchiando allo stesso tempo l'input dell'utente. Le previsioni dei luoghi vengono formattate in modo diverso a seconda dell'input dell'utente in ogni richiesta.
  - I termini corrispondenti nel parametro input vengono scelti per primi utilizzando i nomi allineati alla preferenza della lingua indicata dal parametro languageCode se disponibile, altrimenti utilizzando i nomi che corrispondono meglio all'input dell'utente.
  - Gli indirizzi vengono formattati nella lingua locale, in uno script leggibile dall'utente quando possibile, solo dopo che i termini corrispondenti sono stati scelti in modo che corrispondano a quelli nel parametro input.
  - Tutti gli altri indirizzi vengono restituiti nella lingua preferita, dopo che i termini corrispondenti sono stati scelti in modo che corrispondano ai termini nel parametro input. Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più simile.
locationBias o locationRestriction

Puoi specificare locationBias o locationRestriction, ma non entrambi, per definire l'area di ricerca. Pensa a locationRestriction come a specificare la regione in cui devono trovarsi i risultati, mentre a locationBias a specificare la regione vicina ai risultati che possono essere al di fuori dell'area.

Nota: se ometti sia locationBias sia locationRestriction, l'API utilizza la differenziazione degli IP per impostazione predefinita. Con la differenziazione per IP, l'API utilizza l'indirizzo IP del dispositivo per differenziazione dei risultati.
- locationBias
  
  Specifica un'area in cui eseguire la ricerca. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, compresi quelli al di fuori dell'area specificata.
- locationRestriction
  
  Specifica un'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti.
Specifica la regione locationBias o locationRestriction come area visibile rettangolare o circolare.
- Un cerchio viene definito dal centro e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0,0. Per locationRestriction, devi impostare il raggio su un valore maggiore di 0,0. In caso contrario, la richiesta non restituisce alcun risultato.
  
  Ad esempio:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti alti e low opposti diagonalmente. Un'area visibile è considerata una regione chiusa, ovvero include il proprio confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre quelli di longitudine devono essere compresi tra -180 e 180 gradi inclusi:
  - Se low = high, l'area visibile è composta da quel singolo punto.
  - Se low.longitude > high.longitude, l'intervallo di longitudine viene invertito (l'area visibile supera la linea di longitudine di 180 gradi).
  - Se low.longitude = -180 gradi e high.longitude = 180 gradi, l'area visibile include tutte le longitudini.
  - Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.
  È necessario compilare entrambi i campi low e high e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.
  
  Ad esempio, questa area visibile racchiude completamente New York City:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
origine

Il punto di partenza dal quale calcolare la distanza in linea retta dalla destinazione (restituito come distanceMeters). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Devono essere specificate come coordinate di latitudine e longitudine:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

Il codice regione utilizzato per formattare la risposta, specificato come valore a 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 codice ISO 3166-1 è"gb " (tecnicamente per l'entità "The United Kingdom of Gran Bretagna e Irlanda del Nord").

Se specifichi un codice regione non valido, l'API restituisce un errore INVALID_ARGUMENT. Il parametro può influire sui risultati in base alla legge vigente.
sessionToken

I token di sessione sono stringhe generate dall'utente che tracciano le chiamate di completamento automatico (nuove) come "sessioni". Autocomplete (Nuovo) utilizza i token di sessione per raggruppare le fasi di query e selezione della ricerca di completamento automatico di un utente in una sessione distinta ai fini della fatturazione. Per maggiori informazioni, consulta Token di sessione.

Esempi di completamento automatico (nuovi)

Utilizza locationRestriction e locationBias

L'API utilizza per impostazione predefinita la differenziazione IP per controllare l'area di ricerca. Con la differenziazione per IP, l'API utilizza l'indirizzo IP del dispositivo per differenziazione dei risultati. Facoltativamente, puoi utilizzare locationRestriction o locationBias, ma non entrambi, per specificare un'area in cui eseguire la ricerca.

locationRestriction specifica l'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti. Nell'esempio seguente, utilizzi locationRestriction per limitare la richiesta a un cerchio di 5000 metri di raggio centrato su San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tutti i risultati all'interno delle aree specificate sono contenuti nell'array suggestions:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Con locationBias, la località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, compresi quelli al di fuori dell'area specificata. Nell'esempio successivo, modifichi la richiesta per utilizzare locationBias:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

I risultati ora contengono molti altri elementi, inclusi i risultati al di fuori del raggio di 5000 metri:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Usa includiPrincipalType

Utilizza il parametro includedPrimaryTypes per specificare fino a cinque valori di tipo da Tabella A, Tabella B, solo (regions) o solo (cities). Una località deve corrispondere a uno dei valori di tipo principale specificati da includere nella risposta.

Nell'esempio seguente, specifichi una stringa input di "Calcio" e utilizzi il parametro includedPrimaryTypes per limitare i risultati a stabilimenti di tipo "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Se ometti il parametro includedPrimaryTypes, i risultati possono includere stabilimenti di un tipo che non vuoi, come "athletic_field".

Richiedi previsioni per le query

Le previsioni delle query non vengono restituite per impostazione predefinita. Utilizza il parametro di richiesta includeQueryPredictions per aggiungere previsioni delle query alla risposta. Ad esempio:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

L'array suggestions ora contiene sia le previsioni dei luoghi sia quelle delle query come mostrato sopra in Informazioni sulla risposta. Ogni previsione della query include il campo text contenente una stringa di ricerca testuale consigliata. Puoi effettuare una richiesta di Ricerca testuale (nuova) per ottenere ulteriori informazioni su una qualsiasi delle previsioni delle query restituite.

Nota: le previsioni delle query non vengono restituite quando è impostato il parametro includedRegionCodes.

Usa origine

In questo esempio, includi nella richiesta origin sotto forma di coordinate di latitudine e longitudine. Se includi origin, l'API include nella risposta il campo distanceMeters, che contiene la distanza in linea retta tra origin alla destinazione. Questo esempio imposta l'origine in base al centro di San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

La risposta ora include distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Prova.

Explorer API consente di effettuare richieste di esempio, per acquisire familiarità con le opzioni API e API.

Seleziona l'icona dell'API sul lato destro della pagina.
Se vuoi, espandi Mostra parametri standard e imposta il parametro fields sulla maschera del campo.
Se vuoi, modifica il corpo della richiesta.
Seleziona il pulsante Esegui. Nella finestra popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona Espandi, , per espandere la finestra di Explorer API.

Completamento automatico (novità)

Richieste di completamento automatico (nuove)

Informazioni sulla risposta

Parametri obbligatori

input

Parametri facoltativi

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias o locationRestriction

locationBias

locationRestriction

origine

regionCode

sessionToken

Esempi di completamento automatico (nuovi)

Utilizza locationRestriction e locationBias

Usa includiPrincipalType

Richiedi previsioni per le query

Usa origine

Prova.