Method: geocode.destinations.searchDestinations

Esse método faz uma pesquisa de destino e retorna uma lista de destinos.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
Campos
travelModes[]

enum (NavigationPoint.TravelMode)

Opcional. Os meios de transporte para filtrar os pontos de navegação. Isso influencia o campo navigationPoints retornado na resposta. Se estiver vazio, os pontos de navegação de todos os modos de viagem serão retornados.
languageCode

string

Opcional. Idioma em que os resultados devem ser retornados.
regionCode

string

Opcional. Código da região. O código regional, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. O parâmetro afeta os resultados com base na legislação aplicável. Esse parâmetro também influencia, mas não restringe totalmente, os resultados do serviço.

Campo de união primary_query. Consulte o destino principal. Pode ser um lugar, um endereço totalmente especificado ou um local LatLng. Alguns lugares e endereços com informações mínimas não podem ser transformados em destinos.

Os destinos são criados com base na consulta principal especificada.

Observação: só é possível usar lugares e endereços que podem ter um destino de navegação. Por exemplo, um lugar que representa uma casa ou um complexo de apartamentos pode ser usado como a consulta principal, mas lugares que representam uma região administrativa ou uma área político-administrativa não podem ser usados como a consulta principal. primary_query pode ser apenas de um dos tipos a seguir:
place

string

O nome do recurso de um lugar, no formato places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Um endereço.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Um local exato.

Corpo da resposta

Mensagem de resposta para DestinationService.SearchDestinations.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Campos
destinations[]

object (Destination)

Uma lista de destinos.

O serviço retorna um resultado se um destino principal puder ser identificado de forma inequívoca na consulta principal. Caso contrário, o serviço poderá retornar vários resultados para desambiguação ou nenhum resultado.

Escopos de autorização

Requer um dos seguintes escopos do 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

O endereço que você quer pesquisar. Especifique endereços de acordo com o formato usado pelo serviço postal do país em questão.

Representação JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
Campos
Campo de união kind. A consulta de endereço. kind pode ser apenas de um dos tipos a seguir:
address

object (PostalAddress)

Um endereço no formato de endereço postal.
addressQuery

string

Um endereço formatado como uma única linha.

SearchDestinationsRequest.LocationQuery

Uma consulta de local para identificar um destino principal próximo.

Observação: se a consulta de local estiver em um edifício que contém subinstalações, é possível que o lugar principal retornado seja uma subinstalação. Nesses casos, o campo containingPlaces vai incluir o prédio.

Representação JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
Campos
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Opcional. Filtros a serem aplicados aos candidatos de destino.
Campo de união kind. A consulta de local. kind pode ser apenas de um dos tipos a seguir:
location

object (LatLng)

Um local LatLng exato.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Filtros a serem aplicados aos candidatos de destino.

Representação JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Campos
structureType

enum (PlaceView.StructureType)

Opcional. Se especificado, todos os destinos terão um lugar principal com esse tipo de estrutura. Isso pode resultar na filtragem de alguns destinos ou na simplificação/refinamento dos destinos retornados.

Por exemplo, se GROUNDS for especificado, todos os destinos retornados terão um lugar principal com o tipo de estrutura GROUNDS. Isso pode resultar na filtragem de alguns destinos que não fazem parte de um campus ou na simplificação dos destinos retornados para o nível do campus.

Outro uso desse campo é extrair com mais facilidade os polígonos de exibição de edifícios. Por exemplo, se BUILDING for especificado, o polígono de exibição do lugar principal será o do edifício no local especificado.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Opcional. Se especificado, retorna apenas os destinos que atendem aos critérios de endereçamento correspondentes.

PlaceView.StructureType

O tipo de estrutura que esse lugar representa.

Tipos enumerados
STRUCTURE_TYPE_UNSPECIFIED Não utilizado.
POINT Um local de ponto.
SECTION Uma subseção de um edifício.
BUILDING Um edifício.
GROUNDS Uma área grande que normalmente contém vários edifícios, como um campus universitário, um condomínio de apartamentos ou um shopping center.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Define opções para filtragem de endereçamento. Novos valores podem ser adicionados no futuro.

Tipos enumerados
ADDRESSABILITY_UNSPECIFIED Quando não especificado, o serviço escolhe um padrão adequado.
ANY A capacidade de endereçamento não é um critério de filtragem. Os destinos são retornados independentemente da capacidade de endereçamento.
PRIMARY Todos os destinos retornados terão um lugar principal com um endereço ou nome de rua.
WEAK Todos os destinos retornados terão um lugar principal ou um subdestino com um endereço ou nome de rua.

Destino

Um destino. Isso inclui o lugar principal, lugares relacionados, entradas e pontos de navegação.

Representação 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)
  }
}
Campos
primary

object (PlaceView)

O lugar principal identificado pelo primary_query na solicitação.
containingPlaces[]

object (PlaceView)

Os lugares menos precisos que contêm o lugar principal. Por exemplo, o condomínio de apartamentos que contém esse prédio.
subDestinations[]

object (PlaceView)

Subdestinos mais precisos do lugar principal. Por exemplo, unidades contidas em um prédio.

Observação: em comparação com o SubDestination retornado pela API Places, essa lista de subdestinos é mais completa, e cada subdestino contém mais informações.
landmarks[]

object (Landmark)

Pontos de referência que podem ser usados para informar onde fica o destino ou ajudar na chegada.
entrances[]

object (Entrance)

Entradas para este destino.
navigationPoints[]

object (NavigationPoint)

Pontos de navegação para este destino.
parkingOptions

object (Destination.ParkingOptions)

Opções de estacionamento para este destino.
arrivalSummary

object (Destination.ArrivalSummary)

Resumo gerado com IA da experiência de chegada ao destino.

PlaceView

Representa uma visualização de um Place na API Places. Ele também fornece outras informações específicas sobre destinos, como o tipo de estrutura e o polígono de exibição.

Em alguns casos, um PlaceView com o mesmo ID de lugar pode ser diferente do que é retornado pela API Places para os campos types e displayName.

Representação JSON 
{
  "place": 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)
    }
  ]
}
Campos
place

string

O nome do recurso do lugar, no formato places/{placeId}. Pode ser usado para procurar o lugar.
placeId

string

O identificador exclusivo de um lugar.
displayName

object (LocalizedText)

Descrição do lugar legível por humanos. Por exemplo, "Portão B", "McDonald's"
primaryType

string

O tipo principal desse lugar. Consulte https://developers.google.com/maps/documentation/places/web-service/place-types para ver a lista de valores possíveis.

Observação: esse campo nem sempre é preenchido. Esteja preparado para usar o campo types nessas situações.
types[]

string

Todos os tipos de lugar associados a este lugar. Consulte https://developers.google.com/maps/documentation/places/web-service/place-types para ver a lista de valores possíveis.
formattedAddress

string

Endereço de uma linha.
postalAddress

object (PostalAddress)

Endereço estruturado.
structureType

enum (PlaceView.StructureType)

O tipo de estrutura correspondente a este lugar.
location

object (LatLng)

O local desse lugar. Para lugares com polígonos de exibição, isso pode representar um bom ponto para colocar um marcador no mapa.
displayPolygon

object (Struct format)

O contorno do polígono do lugar no formato GeoJSON, usando o formato RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Observação: o formato RFC 7946 é compatível com MultiPolygons, então um objeto displayPolygon pode representar vários polígonos.
addressComponents[]

object (PlaceView.AddressComponent)

Componentes repetidos para cada nível de localidade.

PlaceView.AddressComponent

Os componentes estruturados que formam o endereço formatado, se essas informações estiverem disponíveis.

Representação JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Campos
longText

string

A descrição completa em texto ou o nome do componente do endereço. Por exemplo, um componente de endereço para o país Austrália pode ter o nome longo "Austrália".
shortText

string

Um nome abreviado, no formato de texto, para o componente de endereço, se estiver disponível. Por exemplo, um componente de endereço para o país Austrália pode ter o nome abreviado "AU".
types[]

string

Uma matriz que indica os tipos do componente de endereço.

Consulte https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types para mais detalhes.
languageCode

string

O idioma usado para formatar esse componente, na notação CLDR.

Ponto de referência

Os pontos de referência são usados para comunicar onde fica o destino ou ajudar a chegar lá.

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

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
Campos
relationalDescription

object (LocalizedText)

Uma descrição legível por humanos de como o destino se relaciona com o ponto de referência. Por exemplo: "Perto do Empire State Building" ou "Em frente à Casa Branca".
tags[]

enum (Landmark.Tag)

Tags que descrevem como o ponto de referência pode ser usado no contexto do destino.
straightLineDistanceMeters

number

Apenas saída. A distância em linha reta do ponto de referência até o destino, em metros.
travelDistanceMeters

number

Apenas saída. A distância a pé desse ponto de referência até o destino, em metros.
Campo de união landmark. O ponto de referência. landmark pode ser apenas de um dos tipos a seguir:
place

object (PlaceView)

O lugar que representa esse ponto de referência.

Landmark.Tag

A lista de todas as tags possíveis que descrevem como um ponto de referência pode ser usado no contexto de um destino.

Se um endereço tiver as tags ADDRESS e ARRIVAL, isso significa que o ponto de referência é proeminente localmente e fica perto do destino.

Tipos enumerados
TAG_UNSPECIFIED Não utilizado.
ADDRESS Um lugar de destaque local que pode ser usado para identificar a localização geral do destino. Normalmente, a poucos metros do destino. Eles são semelhantes aos pontos de referência retornados pelo recurso de descritores de endereço da API Geocoding: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Um lugar que pode ser usado para ajudar a chegar ao destino. Útil para navegação quando você está perto do destino. Por exemplo, esse ponto de referência pode ser um lugar que fica do outro lado da rua do destino. Um ponto de referência com essa tag geralmente está mais perto do destino do que pontos com a tag ADDRESS.

Entrada

Uma entrada é um único par de coordenadas de latitude/longitude que define o local de um ponto de entrada e saída de um lugar.

Representação JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
Campos
location

object (LatLng)

O local da entrada.
tags[]

enum (Entrance.Tag)

Uma lista de tags que descrevem a entrada.
place

string

A estrutura em que essa entrada está localizada fisicamente, no formato places/{placeId}.
streetViewThumbnail

object (StreetViewThumbnail)

Imagem em miniatura do Street View que mostra a entrada. A imagem pode ser solicitada à API Street View Static. Consulte https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

Anotação da entrada no streetViewThumbnail retornado acima.

Entrance.Tag

Características que descrevem uma entrada.

Tipos enumerados
TAG_UNSPECIFIED Não utilizado.
PREFERRED

A entrada provavelmente fornece acesso físico ao local principal no destino retornado. Um lugar pode ter várias entradas preferenciais. Se uma entrada não tiver essa tag, significa que ela está fisicamente no mesmo edifício que o lugar principal, mas não necessariamente dá acesso a ele.

Por exemplo, se o lugar principal for um restaurante em um shopping, as entradas "PREFERRED" serão aquelas que provavelmente levam ao restaurante, enquanto as outras entradas retornadas serão outras entradas do prédio, como as de outros restaurantes no shopping.

Se o lugar principal for um prédio, as entradas PREFERRED serão as que levam à parte "principal" dele. Por exemplo, em um shopping center, as entradas PREFERRED são aquelas que dão acesso ao saguão principal. Se uma entrada só dá acesso a uma loja na lateral do prédio, ela não é PREFERRED.

Observação: uma entrada PREFERRED pode não dar acesso ao local principal, e uma entrada não PREFERRED pode dar acesso ao local principal.

StreetViewThumbnail

Parâmetros para representar uma miniatura do Google Street View. Esses parâmetros podem ser usados para solicitar uma imagem do Street View da API Street View Static. Consulte https://developers.google.com/maps/documentation/streetview/request-streetview.

Representação JSON 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
Campos
pano

string

Um ID de panorama específico.
widthPx

integer

Largura da imagem em miniatura de saída em pixels. Observação: ao solicitar anotações com a miniatura, esses valores de altura e largura precisam ser usados na solicitação de API do Street View para garantir que as coordenadas da anotação estejam alinhadas corretamente com a imagem.
heightPx

integer

Altura da imagem de miniatura de saída em pixels. Observação: ao solicitar anotações junto com a miniatura, esses valores de altura e largura precisam ser usados na solicitação de API do Street View para garantir que as coordenadas da anotação se alinhem corretamente com a imagem.
headingDegree

number

Orientação horizontal da câmera em graus. Intervalo [0, 360). 0 indica Norte e 90 indica Leste.
pitchDegree

number

Orientação vertical da câmera em graus. Intervalo [-90, 90]. 0 é o horizonte, +90 é para cima, -90 é para baixo.
fovDegree

number

Campo de visão horizontal em graus. Intervalo (0, 180]. Controla o nível de zoom. Um FOV menor significa mais zoom.

ImageAnnotation

Uma anotação em uma miniatura de imagem, como um polígono que contorna uma entrada.

Representação JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
Campos
coordinates[]

object (ImageAnnotation.Coordinate)

Uma lista de coordenadas que formam um polígono na imagem. As coordenadas são ordenadas no sentido anti-horário.

ImageAnnotation.Coordinate

Coordenada de pixel de um ponto na imagem. A origem (0,0) é o canto superior esquerdo do pixel superior esquerdo da imagem, com o eixo x apontando para a direita e o eixo y apontando para baixo.

Representação JSON 
{
  "xPx": number,
  "yPx": number
}
Campos
xPx

number

Coordenada X.
yPx

number

Coordenada Y.

Destination.ParkingOptions

Informações sobre as opções de estacionamento no destino.

Representação JSON 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
Campos
availability

enum (Destination.ParkingOptions.Availability)

A disponibilidade de estacionamento para esse destino.
onsiteParking

boolean

Há estacionamento no local de destino.
freeParkingLot

boolean

Oferece estacionamento gratuito.
paidParkingLot

boolean

Oferece estacionamentos pagos.
freeStreetParking

boolean

Oferece estacionamento público sem custo financeiro.
paidStreetParking

boolean

Oferece estacionamento público pago.
valetParking

boolean

Oferece estacionamento com manobrista.
freeGarageParking

boolean

Oferece estacionamento coberto incluído.
paidGarageParking

boolean

Oferece garagem de estacionamento paga.

Destination.ParkingOptions.Availability

Uma medida agregada de como é difícil encontrar estacionamento ao visitar este lugar.

Novos valores podem ser adicionados no futuro.

Tipos enumerados
AVAILABILITY_UNSPECIFIED A disponibilidade de estacionamento não está disponível.
PLENTY Há muitas vagas de estacionamento disponíveis.
SOMEWHAT_DIFFICULT É um pouco difícil encontrar estacionamento.
DIFFICULT É muito difícil encontrar uma vaga de estacionamento.

Destination.ArrivalSummary

Resumo gerado com IA da experiência de chegada ao destino.

Representação JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Campos
text

object (LocalizedText)

O resumo da experiência de chegada ao destino.
flagContentUrl

string

Um link em que os usuários podem sinalizar um problema com o resumo.
disclosureText

object (LocalizedText)

Apenas saída. Contém o texto de divulgação do resumo da chegada.