Method: places.autocomplete

Restituisce previsioni per l'input specificato.

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string
}
Campi
input

string

obbligatorio. La stringa di testo in cui eseguire la ricerca.

locationBias

object (LocationBias)

Campo facoltativo. Risultati con bias per una località specificata.

Deve essere impostato al massimo un valore tra locationBias o locationRestriction. Se nessuno dei due è impostato, i risultati saranno influenzati dall'indirizzo IP, il che significa che l'indirizzo IP verrà mappato a una posizione imprecisa e utilizzato come segnale di differenziazione.

locationRestriction

object (LocationRestriction)

Campo facoltativo. Limita i risultati a una località specificata.

Deve essere impostato al massimo un valore tra locationBias o locationRestriction. Se nessuno dei due è impostato, i risultati saranno influenzati dall'indirizzo IP, il che significa che l'indirizzo IP verrà mappato a una posizione imprecisa e utilizzato come segnale di differenziazione.

includedPrimaryTypes[]

string

Campo facoltativo. Tipo di luogo principale incluso (ad esempio, "ristorante" o "gas_station") da https://developers.google.com/maps/documentation/places/web-service/place-types. Un luogo viene restituito solo se il suo tipo principale è incluso nell'elenco. È possibile specificare fino a 5 valori. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi di luogo.

includedRegionCodes[]

string

Campo facoltativo. Includi solo i risultati nelle regioni specificate, specificate con un massimo di 15 codici regione a due caratteri CLDR. Un set vuoto non limiterà i risultati. Se locationRestriction e includedRegionCodes sono impostati, i risultati si troveranno nell'area di intersezione.

languageCode

string

Campo facoltativo. La lingua in cui restituire i risultati. Il valore predefinito è en-US. I risultati possono essere in lingue miste se la lingua usata in input è diversa da quella in languageCode o se il luogo restituito non ha una traduzione dalla lingua locale in languageCode.

regionCode

string

Campo facoltativo. Il codice regione specificato come codice regione a due caratteri CLDR. Questo influisce sulla formattazione dell'indirizzo, sul ranking dei risultati e può influenzare i risultati restituiti. I risultati non vengono limitati alla regione specificata. Per limitare i risultati a una regione, utilizza region_code_restriction.

origin

object (LatLng)

Campo facoltativo. Il punto di origine da cui calcolare la distanza geodetica dalla destinazione (restituito come distanceMeters). Se questo valore viene omesso, la distanza geodetica non verrà restituita.

inputOffset

integer

Campo facoltativo. Un offset di caratteri Unicode in base zero di input che indica la posizione del cursore in input. La posizione del cursore può influire sulle previsioni che vengono restituite.

Se vuoto, il valore predefinito è input.

includeQueryPredictions

boolean

Campo facoltativo. Se true, la risposta includerà sia le previsioni di luogo sia quelle delle query. In caso contrario, la risposta restituirà solo previsioni Place.

sessionToken

string

Campo facoltativo. Una stringa che identifica una sessione di completamento automatico ai fini della fatturazione. Deve essere una stringa Base64 sicura per URL e nome file con al massimo 36 caratteri ASCII. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

La sessione inizia quando l'utente inizia a digitare una query e si conclude quando seleziona un luogo e viene effettuata una chiamata a Place Details o Address Validation. Ogni sessione può includere più query, seguite da una richiesta Dettagli luogo o Convalida indirizzo. Le credenziali utilizzate per ogni richiesta all'interno di una sessione devono appartenere allo stesso progetto della console Google Cloud. Al termine di una sessione, il token non è più valido; l'app deve generare un token nuovo 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 un token di sessione (ogni richiesta viene fatturata separatamente).

Consigliamo le seguenti linee guida:

  • Utilizza i token di sessione per tutte le chiamate a Place Autocomplete.
  • Genera un nuovo token per ogni sessione. Si consiglia di utilizzare un UUID versione 4.
  • Assicurati che le credenziali utilizzate per tutte le richieste di Place Autocomplete, Place Details e Address Validation 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ù sessioni, ogni richiesta verrà fatturata singolarmente.

Corpo della risposta

Protocollo di risposta per places.autocomplete.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
Campi
suggestions[]

object (Suggestion)

Contiene un elenco di suggerimenti in ordine decrescente in base alla pertinenza.

LocationBias

La regione in cui cercare. I risultati potrebbero essere influenzati dalla regione specificata.

Rappresentazione JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Campi

Campo di unione type.

type può essere solo uno dei seguenti:

rectangle

object (Viewport)

Un'area visibile definita da un angolo nord-est e da un angolo sud-ovest.

circle

object (Circle)

Un cerchio definito da un punto centrale e un raggio.

LocationRestriction

La regione in cui cercare. I risultati verranno limitati alla regione specificata.

Rappresentazione JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Campi

Campo di unione type.

type può essere solo uno dei seguenti:

rectangle

object (Viewport)

Un'area visibile definita da un angolo nord-est e da un angolo sud-ovest.

circle

object (Circle)

Un cerchio definito da un punto centrale e un raggio.

Suggerimento

Risultato del suggerimento di completamento automatico.

Rappresentazione JSON
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
Campi

Campo di unione kind.

kind può essere solo uno dei seguenti:

placePrediction

object (PlacePrediction)

Una previsione per un luogo.

queryPrediction

object (QueryPrediction)

Una previsione per una query.

PlacePrediction

Risultati della previsione per una previsione di Place Autocomplete.

Rappresentazione JSON
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
Campi
place

string

Il nome della risorsa del luogo suggerito. Questo nome può essere utilizzato in altre API che accettano i nomi dei luoghi.

placeId

string

L'identificatore univoco del luogo suggerito. Questo identificatore può essere utilizzato in altre API che accettano gli ID luogo.

text

object (FormattableText)

Contiene il nome leggibile per il risultato restituito. Per i risultati relativi all'attività, di solito si tratta del nome e dell'indirizzo dell'attività.

L'app text è consigliata per gli sviluppatori che vogliono mostrare un singolo elemento UI. Gli sviluppatori che vogliono mostrare due elementi UI separati ma correlati possono usare invece structuredFormat. Sono due modi diversi per rappresentare una previsione di luogo. Gli utenti non devono provare ad analizzare structuredFormat in text e viceversa.

Questo testo potrebbe essere diverso dal valore displayName restituito da places.get.

Può essere disponibile in lingue miste se le richieste input e languageCode sono in lingue diverse o se il luogo non dispone di una traduzione dalla lingua locale a languageCode.

structuredFormat

object (StructuredFormat)

Un'analisi della previsione di Place nel testo principale contenente il nome del luogo e un testo secondario contenente ulteriori elementi distintivi (come una città o una regione).

L'app structuredFormat è consigliata per gli sviluppatori che vogliono mostrare due elementi UI separati ma correlati. Gli sviluppatori che vogliono mostrare un singolo elemento dell'interfaccia utente potrebbero voler usare invece text. Sono due modi diversi per rappresentare una previsione di luogo. Gli utenti non devono provare ad analizzare structuredFormat in text e viceversa.

types[]

string

Elenco dei tipi applicabili a questo luogo dalla tabella A o dalla tabella B alla pagina https://developers.google.com/maps/documentation/places/web-service/place-types.

Un tipo è una categorizzazione di un luogo. I luoghi con tipi condivisi avranno caratteristiche simili.

distanceMeters

integer

La lunghezza della geodetica in metri da origin, se origin è specificato. Alcune previsioni, come le route, potrebbero non essere compilate in questo campo.

FormattableText

Testo che rappresenta una previsione di luogo o query. Il testo può essere utilizzato così com'è o formattato.

Rappresentazione JSON
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
Campi
text

string

Testo che può essere utilizzato così com'è o formattato con matches.

matches[]

object (StringRange)

Un elenco di intervalli di stringhe che identificano i punti in cui la richiesta di input corrisponde in text. Gli intervalli possono essere utilizzati per formattare parti specifiche di text. Le sottostringhe potrebbero non corrispondere esattamente a input se la corrispondenza è stata determinata in base a criteri diversi dalla corrispondenza delle stringhe (ad esempio, correzioni ortografiche o traslitterazioni).

Questi valori sono offset di caratteri Unicode di text. L'ordine degli intervalli è garantito in base a valori di offset crescenti.

StringRange

Identifica una sottostringa all'interno di un determinato testo.

Rappresentazione JSON
{
  "startOffset": integer,
  "endOffset": integer
}
Campi
startOffset

integer

Offset in base zero del primo carattere Unicode della stringa (incluso).

endOffset

integer

Offset in base zero dell'ultimo carattere Unicode (escluso).

StructuredFormat

Contiene una suddivisione di un luogo o di una previsione di query in testo principale e testo secondario.

Per le previsioni dei luoghi, il testo principale contiene il nome specifico del luogo. Per le previsioni delle query, il testo principale contiene la query.

Il testo secondario contiene ulteriori elementi che chiariscono la tua ambiguità (ad esempio una città o una regione) per identificare ulteriormente il luogo o perfezionare la query.

Rappresentazione JSON
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
Campi
mainText

object (FormattableText)

Rappresenta il nome del luogo o della query.

secondaryText

object (FormattableText)

Rappresenta ulteriori elementi distintivi (ad esempio una città o una regione) per identificare ulteriormente il luogo o perfezionare la query.

QueryPrediction

Risultati della previsione per una previsione di completamento automatico delle query.

Rappresentazione JSON
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
Campi
text

object (FormattableText)

Il testo previsto. Questo testo non rappresenta un luogo, ma una query di testo che potrebbe essere utilizzata in un endpoint di ricerca (ad esempio, ricerca testuale).

L'app text è consigliata per gli sviluppatori che vogliono mostrare un singolo elemento UI. Gli sviluppatori che vogliono mostrare due elementi UI separati ma correlati possono usare invece structuredFormat. Esistono due modi diversi per rappresentare una previsione delle query. Gli utenti non devono provare ad analizzare structuredFormat in text e viceversa.

Può essere disponibile in lingue miste se le richieste input e languageCode sono in lingue diverse o se parte della query non ha una traduzione dalla lingua locale in languageCode.

structuredFormat

object (StructuredFormat)

Un'analisi della previsione della query in testo principale contenente la query e testo secondario contenente ulteriori elementi di disambiguazione (ad esempio una città o una regione).

L'app structuredFormat è consigliata per gli sviluppatori che vogliono mostrare due elementi UI separati ma correlati. Gli sviluppatori che vogliono mostrare un singolo elemento dell'interfaccia utente potrebbero voler usare invece text. Esistono due modi diversi per rappresentare una previsione delle query. Gli utenti non devono provare ad analizzare structuredFormat in text e viceversa.