Method: geocode.destinations.searchDestinations

Questo metodo esegue una ricerca delle destinazioni e restituisce un elenco di destinazioni.

Richiesta HTTP

POST https://geocode.googleapis.com/v4alpha/geocode/destinations

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
Campi
travelModes[]

enum (NavigationPoint.TravelMode)

Facoltativo. Le modalità di viaggio per cui filtrare i punti di navigazione. Questo influisce sul campo navigationPoints restituito nella risposta. Se vuoto, vengono restituiti i punti di navigazione di tutte le modalità di viaggio.
languageCode

string

Facoltativo. La lingua in cui devono essere restituiti i risultati.
regionCode

string

Facoltativo. Codice regione. Il codice regione, specificato come valore di due caratteri ccTLD ("dominio di primo livello"). Il parametro influisce sui risultati in base alla legge vigente. Questo parametro influisce anche sui risultati del servizio, ma non li limita completamente.

Query per la destinazione principale. Può essere un luogo, un indirizzo completo o una località LatLng. Alcuni luoghi e indirizzi con informazioni minime non potranno essere trasformati in una destinazione.

Le destinazioni vengono create in base alla query primaria specificata.

Nota: sono supportati solo i luoghi e gli indirizzi che possono avere una destinazione di navigazione. Ad esempio, un luogo che rappresenta una casa o un complesso di appartamenti può essere utilizzato come query principale, ma i luoghi che rappresentano una località o un'area amministrativa non possono essere utilizzati come query principale. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
place

string

Il nome della risorsa di un luogo, nel formato places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Indirizzo e numero civico.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Una posizione esatta.
Fine dei campi che si escludono a vicenda.

Corpo della risposta

Messaggio di risposta per DestinationService.SearchDestinations.

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

Rappresentazione JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Campi
destinations[]

object (Destination)

Un elenco di destinazioni.

Il servizio restituisce un risultato se è possibile identificare in modo univoco una destinazione principale dalla query principale. In caso contrario, il servizio potrebbe restituire più risultati per la disambiguazione o nessun risultato.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

La via che vuoi cercare. Specifica gli indirizzi in conformità al formato utilizzato dal servizio postale nazionale del paese interessato.

Rappresentazione JSON 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
Campi
La query dell'indirizzo. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
address

object (PostalAddress)

Un indirizzo via nel formato di indirizzo postale.
addressQuery

string

Un indirizzo formattato come singola riga.
Fine dei campi che si escludono a vicenda.

SearchDestinationsRequest.LocationQuery

Una query sulla posizione per identificare una destinazione principale nelle vicinanze.

Nota: se la query sulla località si trova all'interno di un edificio che contiene sottosedi, è possibile che il luogo principale restituito sia una sottosede. In questi casi, il campo containingPlaces includerà l'edificio.

Rappresentazione JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
Campi
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Facoltativo. Filtri da applicare ai candidati di destinazione.
La query sulla posizione. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
location

object (LatLng)

Una posizione LatLng precisa.
Fine dei campi che si escludono a vicenda.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Filtri da applicare ai candidati di destinazione.

Rappresentazione JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Campi
structureType

enum (PlaceView.StructureType)

Facoltativo. Se specificato, tutte le destinazioni avranno sicuramente un luogo principale con questo tipo di struttura. Ciò può comportare l'esclusione di alcune destinazioni o l'approssimazione/perfezionamento delle destinazioni restituite.

Ad esempio, se viene specificato GROUNDS, tutte le destinazioni restituite avranno un luogo principale con il tipo di struttura GROUNDS. Ciò può comportare l'esclusione di alcune destinazioni che non fanno parte di un terreno o l'approssimazione delle destinazioni restituite al livello del terreno.

Un altro utilizzo di questo campo è l'estrazione più semplice dei poligoni di visualizzazione degli edifici. Ad esempio, se viene specificato BUILDING, il poligono di visualizzazione del luogo principale sarà quello dell'edificio nella località specificata.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Facoltativo. Se specificato, restituisce solo le destinazioni che soddisfano i criteri di indirizzabilità corrispondenti.

PlaceView.StructureType

Il tipo di struttura rappresentato da questo luogo.

Enum
STRUCTURE_TYPE_UNSPECIFIED Non utilizzato.
POINT Una posizione puntuale.
SECTION Una sottosezione di un edificio.
BUILDING Un edificio.
GROUNDS Un'area di grandi dimensioni che in genere contiene più edifici, come un campus universitario, un complesso di appartamenti o un centro commerciale.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Definisce le opzioni per i filtri di indirizzabilità. In futuro potrebbero essere aggiunti nuovi valori.

Enum
ADDRESSABILITY_UNSPECIFIED Se non viene specificato, il servizio sceglierà un valore predefinito ragionevole.
ANY L'indirizzabilità non è un criterio di filtro. Le destinazioni vengono restituite indipendentemente dalla loro indirizzabilità.
PRIMARY Tutte le destinazioni restituite avranno un luogo principale con un indirizzo o un nome a livello di via.
WEAK Tutte le destinazioni restituite avranno un luogo principale o una destinazione secondaria con un indirizzo o un nome a livello di via.

Destinazione

Una destinazione. Sono inclusi il luogo principale, i luoghi correlati, gli ingressi e i punti di navigazione.

Rappresentazione JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ],
  "parkingOptions": {
    object (Destination.ParkingOptions)
  },
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
Campi
primary

object (PlaceView)

Il luogo principale identificato da primary_query nella richiesta.
containingPlaces[]

object (PlaceView)

I luoghi meno precisi che contengono il luogo principale. Ad esempio, il complesso di appartamenti che contiene questo edificio.
subDestinations[]

object (PlaceView)

Sottodestinazioni più precise del luogo principale. Ad esempio, le unità contenute in un edificio.

Nota: rispetto al campo SubDestination restituito dall'API Places, questo elenco di destinazioni secondarie è più esaustivo e ogni destinazione secondaria contiene più informazioni.
landmarks[]

object (Landmark)

Punti di riferimento che possono essere utilizzati per comunicare dove si trova la destinazione o per facilitare l'arrivo.
entrances[]

object (Entrance)

Ingressi per questa destinazione.
navigationPoints[]

object (NavigationPoint)

Punti di navigazione per questa destinazione.
parkingOptions

object (Destination.ParkingOptions)

Opzioni di parcheggio per questa destinazione.
arrivalSummary

object (Destination.ArrivalSummary)

Riepilogo creato con l'AI dell'esperienza di arrivo presso la destinazione.

PlaceView

Rappresenta una visualizzazione di un luogo nell'API Places. Fornisce inoltre informazioni aggiuntive specifiche per le destinazioni, come il tipo di struttura e il poligono di visualizzazione.

In alcuni casi, un PlaceView con lo stesso ID luogo potrebbe differire da quello restituito dall'API Places per i campi types e displayName.

Rappresentazione JSON 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
Campi
place

string

Il nome della risorsa di questo luogo, nel formato places/{placeId}. Può essere utilizzato per cercare il luogo.
placeId

string

L'identificatore univoco di un luogo.
displayName

object (LocalizedText)

Descrizione del luogo leggibile. Ad esempio, "Gate B", "McDonalds"
primaryType

string

Il tipo di luogo principale di questo luogo. Consulta https://developers.google.com/maps/documentation/places/web-service/place-types per l'elenco dei valori possibili.

Nota: questo campo non viene sempre compilato. In questi casi, preparati a utilizzare il campo types.
types[]

string

Tutti i tipi di luoghi associati a questo luogo. Consulta https://developers.google.com/maps/documentation/places/web-service/place-types per l'elenco dei valori possibili.
formattedAddress

string

Indirizzo su una riga.
postalAddress

object (PostalAddress)

Indirizzo strutturato.
structureType

enum (PlaceView.StructureType)

Il tipo di struttura corrispondente a questo luogo.
location

object (LatLng)

La posizione di questo luogo. Per i luoghi con poligoni di visualizzazione, questo può rappresentare un buon punto per inserire un indicatore sulla mappa.
displayPolygon

object (Struct format)

Il contorno poligonale del luogo in formato GeoJSON, utilizzando il formato RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Nota: il formato RFC 7946 supporta i MultiPolygon, pertanto un oggetto displayPolygon può rappresentare più poligoni.
addressComponents[]

object (PlaceView.AddressComponent)

Componenti ripetuti per ogni livello di località.

PlaceView.AddressComponent

I componenti strutturati che formano l'indirizzo formattato, se queste informazioni sono disponibili.

Rappresentazione JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Campi
longText

string

La descrizione testuale completa o il nome del componente dell'indirizzo. Ad esempio, un componente dell'indirizzo per il paese Australia potrebbe avere il nome lungo "Australia".
shortText

string

Un nome testuale abbreviato per il componente dell'indirizzo, se disponibile. Ad esempio, un componente dell'indirizzo per l'Australia potrebbe avere il nome breve "AU".
types[]

string

Un array che indica i tipi di componenti dell'indirizzo.

Questi valori sono tratti dalla tabella dei tipi di indirizzo e dei tipi di componenti dell'indirizzo utilizzata dall'API Places: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
languageCode

string

La lingua utilizzata per formattare questo componente, in notazione CLDR.

Punto di riferimento

I punti di riferimento vengono utilizzati per comunicare dove si trova la destinazione o per aiutare a raggiungerla.

Rappresentazione JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
Campi
relationalDescription

object (LocalizedText)

Una descrizione leggibile della relazione tra la destinazione e il punto di riferimento. Ad esempio: "Vicino all'Empire State Building" o "Di fronte alla Casa Bianca".
tags[]

enum (Landmark.Tag)

Tag che descrivono come il punto di riferimento può essere utilizzato nel contesto della destinazione.
straightLineDistanceMeters

number

Solo output. La distanza in linea retta da questo punto di riferimento alla destinazione in metri.
travelDistanceMeters

number

Solo output. La distanza a piedi da questo punto di riferimento alla destinazione in metri.
Il punto di riferimento. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
place

object (PlaceView)

Il luogo che rappresenta questo punto di riferimento.
Fine dei campi che si escludono a vicenda.

Landmark.Tag

L'elenco di tutti i possibili tag che descrivono come un punto di riferimento può essere utilizzato nel contesto di una destinazione.

Se un indirizzo ha entrambi i tag ADDRESS e ARRIVAL, significa che il punto di riferimento è sia importante a livello locale sia vicino alla destinazione.

Enum
TAG_UNSPECIFIED Non utilizzato.
ADDRESS Un luogo di rilievo locale che può essere utilizzato per identificare la posizione generica della destinazione. In genere, entro poche centinaia di metri dalla destinazione. Questi sono simili ai punti di riferimento restituiti dalla funzionalità Descrittori degli indirizzi dell'API Geocoding: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Un luogo che può essere utilizzato per raggiungere la destinazione. Utile per la navigazione quando sei vicino alla destinazione. Ad esempio, questo punto di riferimento potrebbe essere un luogo che si trova dall'altra parte della strada rispetto alla destinazione. Un punto di riferimento con questo tag è in genere più vicino alla destinazione rispetto ai punti di riferimento con il tag ADDRESS.

Ingresso

Un ingresso è una singola coppia di coordinate di latitudine/longitudine che definisce la posizione di un punto di ingresso e di uscita per un luogo.

Rappresentazione JSON 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
Campi
displayName

object (LocalizedText)

Nome leggibile, ad esempio "Gate B", "Ingresso sud", "Ingresso 5th Ave".
location

object (LatLng)

La posizione dell'ingresso.
tags[]

enum (Entrance.Tag)

Un elenco di tag che descrivono l'ingresso.
place

string

La struttura in cui si trova fisicamente l'ingresso, nel formato places/{placeId}.
streetViewThumbnail

object (StreetViewThumbnail)

Immagine in miniatura di Street View che mostra l'ingresso. L'immagine può essere richiesta dall'API Street View Static. Consulta la pagina https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

Annotazione dell'ingresso sul streetViewThumbnail restituito sopra.

Entrance.Tag

Caratteristiche che descrivono un ingresso.

Enum
TAG_UNSPECIFIED Non utilizzato.
PREFERRED

L'ingresso probabilmente fornisce l'accesso fisico al luogo principale nella destinazione restituita. Un luogo può avere più ingressi preferiti. Se un ingresso non ha questo tag, significa che si trova fisicamente nello stesso edificio del luogo principale, ma non fornisce necessariamente l'accesso al luogo.

Ad esempio, se il luogo principale è un ristorante in un centro commerciale, gli ingressi "PREFERRED" saranno quelli che probabilmente conducono al ristorante stesso, mentre gli altri ingressi restituiti saranno altri ingressi dell'edificio, ad esempio quelli di altri ristoranti del centro commerciale.

Se il luogo principale è un edificio, gli ingressi PREFERRED saranno quelli che conducono alla parte "principale" dell'edificio. Ad esempio, in un centro commerciale gli ingressi PREFERRED saranno quelli che consentono l'accesso all'area dell'atrio principale, ma se un ingresso consente l'accesso solo a un negozio sul lato dell'edificio, non sarà un ingresso PREFERRED.

Nota: un ingresso PREFERRED potrebbe non fornire l'accesso al luogo principale e un ingresso non PREFERRED potrebbe fornire l'accesso al luogo principale.

StreetViewThumbnail

Parametri per la rappresentazione di una miniatura di Google Street View. Questi parametri possono essere utilizzati per richiedere un'immagine di Street View dall'API Street View Static. Consulta la pagina https://developers.google.com/maps/documentation/streetview/request-streetview.

Rappresentazione JSON 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
Campi
pano

string

Un ID panorama specifico.
widthPx

integer

Larghezza dell'immagine in miniatura di output in pixel. Nota: quando richiedi le annotazioni insieme alla miniatura, questi valori di altezza e larghezza devono essere utilizzati nella richiesta dell'API Street View per garantire che le coordinate delle annotazioni siano allineate correttamente all'immagine.
heightPx

integer

Altezza dell'immagine in miniatura di output in pixel. Nota: quando richiedi le annotazioni insieme alla miniatura, questi valori di altezza e larghezza devono essere utilizzati nella richiesta dell'API Street View per garantire che le coordinate delle annotazioni siano allineate correttamente all'immagine.
headingDegree

number

Orientamento orizzontale della videocamera in gradi. Intervallo [0, 360). 0 indica il nord e 90 indica l'est.
pitchDegree

number

Orientamento verticale della videocamera in gradi. Intervallo [-90, 90]. 0 è l'orizzonte, +90 è dritto verso l'alto, -90 è dritto verso il basso.
fovDegree

number

Campo visivo orizzontale in gradi. Intervallo (0, 180]. Controlla il livello di zoom. Un FOV più piccolo indica uno zoom maggiore.

ImageAnnotation

Un'annotazione su una miniatura dell'immagine, ad esempio un poligono che delinea un ingresso.

Rappresentazione JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
Campi
coordinates[]

object (ImageAnnotation.Coordinate)

Un elenco di coordinate che formano un poligono sull'immagine. Le coordinate sono ordinate in senso antiorario.

ImageAnnotation.Coordinate

Coordinata pixel di un punto sull'immagine. L'origine (0,0) è l'angolo in alto a sinistra del pixel in alto a sinistra dell'immagine, con l'asse x rivolto verso destra e l'asse y rivolto verso il basso.

Rappresentazione JSON 
{
  "xPx": number,
  "yPx": number
}
Campi
xPx

number

Coordinata X.
yPx

number

Coordinata Y.

Destination.ParkingOptions

Informazioni sulle opzioni di parcheggio per la destinazione.

Rappresentazione JSON 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "parkingFacilities": [
    {
      object (Destination.ParkingOptions.ParkingFacility)
    }
  ],
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
Campi
availability

enum (Destination.ParkingOptions.Availability)

La disponibilità di parcheggio per questa destinazione.
parkingFacilities[]

object (Destination.ParkingOptions.ParkingFacility)

I parcheggi per questa destinazione.
onsiteParking

boolean

È disponibile un parcheggio in loco presso la destinazione.
freeParkingLot

boolean

Offre parcheggi gratuiti.
paidParkingLot

boolean

Offre parcheggi a pagamento.
freeStreetParking

boolean

Offre parcheggio in strada senza costi
paidStreetParking

boolean

Offre un parcheggio in strada a pagamento.
valetParking

boolean

Offre il servizio di ritiro e riconsegna auto.
freeGarageParking

boolean

Offre il parcheggio in garage incluso nel prezzo.
paidGarageParking

boolean

Offre un garage a pagamento.

Destination.ParkingOptions.Availability

Una misura aggregata di quanto sia difficile trovare parcheggio quando si visita questo luogo.

In futuro potrebbero essere aggiunti nuovi valori.

Enum
AVAILABILITY_UNSPECIFIED La disponibilità di parcheggio non è disponibile.
PLENTY È disponibile un ampio parcheggio.
SOMEWHAT_DIFFICULT È abbastanza difficile trovare parcheggio.
DIFFICULT È molto difficile trovare parcheggio.

Destination.ParkingOptions.ParkingFacility

Un'opzione di parcheggio individuale e distinta (ad es. un parcheggio o un garage specifico) associata alla destinazione. In questo modo vengono fornite informazioni dettagliate su un parcheggio specifico, mentre il messaggio principale ParkingOptions fornisce un riepilogo aggregato di tutti i parcheggi disponibili.

Rappresentazione JSON 
{
  "place": {
    object (PlaceView)
  },
  "onsite": boolean,
  "popular": boolean,
  "straightLineDistanceMeters": number
}
Campi
place

object (PlaceView)

La rappresentazione del luogo di questo parcheggio specifico.
onsite

boolean

Indica se il parcheggio si trova in loco presso la destinazione principale. Se questo campo non è impostato, lo stato on-site è sconosciuto.
popular

boolean

Indica se questo parcheggio è una scelta popolare per i visitatori che si recano alla destinazione principale. Se questo campo non è impostato, lo stato di popolarità è sconosciuto.
straightLineDistanceMeters

number

La distanza in linea d'aria in metri dalla destinazione principale a questo parcheggio.

Destination.ArrivalSummary

Riepilogo creato con l'AI dell'esperienza di arrivo presso la destinazione.

Rappresentazione JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Campi
text

object (LocalizedText)

Il riepilogo dell'esperienza di arrivo a destinazione.
flagContentUrl

string

Un link in cui gli utenti possono segnalare un problema con il riepilogo.
disclosureText

object (LocalizedText)

Solo output. Contiene il testo dell'informativa per il riepilogo dell'arrivo.