Method: geocode.destinations.searchDestinations

Este método realiza una búsqueda de destinos y devuelve una lista de destinos.

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación de gRPC.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,
  "effort": enum (SearchDestinationsRequest.Effort),

  // 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.
}
Campos
travelModes[]

enum (NavigationPoint.TravelMode)

Opcional. Son los medios de transporte para los que se filtrarán los puntos de navegación. Esto influye en el campo navigationPoints que se muestra en la respuesta. Si está vacío, se devuelven los puntos de navegación de todos los medios de transporte.
languageCode

string

Opcional. Es el idioma en el que se deben mostrar los resultados.
regionCode

string

Opcional. Es el código de la región. Es el código de región, especificado como un valor ccTLD ("dominio de nivel superior") de dos caracteres. El parámetro afecta los resultados según la legislación aplicable. Este parámetro también influye en los resultados del servicio, pero no los restringe por completo.
effort

enum (SearchDestinationsRequest.Effort)

Opcional. Es el nivel de esfuerzo que solicita el cliente.

Consulta el destino principal. Puede ser un lugar, una dirección completamente especificada o una ubicación de LatLng. Algunos lugares y direcciones con información mínima no se podrán convertir en un destino.

Los destinos se crean en torno a la consulta principal especificada.

Nota: Solo se admiten lugares y direcciones que puedan tener un destino de navegación. Por ejemplo, un lugar que representa una casa o un complejo de departamentos se puede usar como consulta principal, pero los lugares que representan una localidad o un área administrativa no se pueden usar como consulta principal. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
place

string

Es el nombre del recurso de un lugar, en formato places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Una dirección.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Una ubicación precisa
Fin de los campos mutuamente excluyentes.

Cuerpo de la respuesta

Mensaje de respuesta para DestinationService.SearchDestinations.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Campos
destinations[]

object (Destination)

Una lista de destinos.

El servicio devuelve un resultado si se puede identificar un destino principal de forma inequívoca a partir de la consulta principal. De lo contrario, el servicio podría devolver varios resultados para eliminar la ambigüedad o ningún resultado.

Permisos de autorización

Se necesita uno de los siguientes permisos de 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

Es la dirección que quieres buscar. Especifica una dirección conforme al formato usado por el servicio postal nacional del país en cuestión.

Representación 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.
}
Campos
Es la consulta de dirección. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
address

object (PostalAddress)

Es una dirección en formato de dirección postal.
addressQuery

string

Es una dirección con formato de una sola línea.
Fin de los campos mutuamente excluyentes.

SearchDestinationsRequest.LocationQuery

Una consulta de ubicación para identificar un destino principal cercano.

Nota: Si la consulta de ubicación se encuentra dentro de un edificio que contiene sublocales, es posible que el lugar principal que se devuelva sea un sublocal. En estos casos, el campo containingPlaces incluirá el edificio.

Representación 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.
}
Campos
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Opcional. Son los filtros que se aplicarán a los candidatos de destino.
Es la consulta de ubicación. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
location

object (LatLng)

Una ubicación precisa de LatLng.
Fin de los campos mutuamente excluyentes.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Son los filtros que se aplicarán a los candidatos de destino.

Representación JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Campos
structureType

enum (PlaceView.StructureType)

Opcional. Si se especifica, se garantiza que todos los destinos tengan un lugar principal con este tipo de estructura. Esto puede provocar que se filtren algunos destinos o que se amplíen o acoten los destinos que se devuelven.

Por ejemplo, si se especifica GROUNDS, todos los destinos devueltos tendrán un lugar principal con el tipo de estructura GROUNDS. Esto puede provocar que se filtren algunos destinos que no forman parte de un terreno o que se simplifiquen los destinos devueltos al nivel del terreno.

Otro uso de este campo es extraer con mayor facilidad los polígonos de visualización de edificios. Por ejemplo, si se especifica BUILDING, el polígono de visualización del lugar principal será el del edificio en la ubicación especificada.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Opcional. Si se especifica, solo se devuelven los destinos que cumplen con los criterios de direccionabilidad correspondientes.

PlaceView.StructureType

Es el tipo de estructura que representa este lugar.

Enums
STRUCTURE_TYPE_UNSPECIFIED No se usa.
POINT Una ubicación de punto.
SECTION Es una subsección de un edificio.
BUILDING Un edificio.
GROUNDS Es un área grande que suele contener varios edificios, como un campus universitario, un complejo de departamentos o un centro comercial.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Define las opciones para el filtrado de direccionabilidad. Es posible que se agreguen valores nuevos en el futuro.

Enums
ADDRESSABILITY_UNSPECIFIED Cuando no se especifica, el servicio elegirá un valor predeterminado razonable.
ANY La direccionabilidad no es un criterio de filtrado. Los destinos se devuelven independientemente de su direccionabilidad.
PRIMARY Todos los destinos que se devuelvan tendrán un lugar principal con una dirección o un nombre a nivel de la calle.
WEAK Todos los destinos que se devuelvan tendrán un lugar principal o un subdestino con una dirección o un nombre a nivel de la calle.

SearchDestinationsRequest.Effort

Es el nivel de esfuerzo asignado para resolver los destinos.

Enums
EFFORT_UNSPECIFIED Valor predeterminado
LOW Optimiza los tiempos de respuesta más rápidos. Realiza una búsqueda directa del destino sin un recorrido jerárquico extendido ni una desambiguación compleja de lugares.
MEDIUM Equilibra la velocidad y la exactitud. La mayoría de las solicitudes se devuelven con una latencia baja estándar. En el caso de consultas ambiguas, sitios con varios edificios o ubicaciones difíciles, el servicio aplica un procesamiento adicional para resolver los destinos y el contexto jerárquico, con una latencia limitada que puede tardar hasta unos segundos. Se recomienda para flujos de trabajo interactivos en los que los usuarios pueden tolerar una breve pausa.
HIGH Maximiza la precisión y la integridad de la resolución de destinos para ubicaciones complejas, informales o extensas (como campus grandes o complejos de departamentos). Los tiempos de respuesta podrían ser significativamente más largos. Se recomienda para flujos de trabajo de enrutamiento previo de logística, despacho, lotes o segundo plano.

Destino

Un destino Esto incluye el lugar principal, los lugares relacionados, las entradas y los puntos de navegación.

Representación 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)

Es el lugar principal que identifica el primary_query en la solicitud.
containingPlaces[]

object (PlaceView)

Son los lugares menos precisos que contienen el lugar principal. Por ejemplo, el complejo de departamentos que contiene este edificio.
subDestinations[]

object (PlaceView)

Son destinos secundarios más precisos del lugar principal. Por ejemplo, las unidades que contiene un edificio.

Nota: En comparación con el objeto SubDestination que devuelve la API de Places, esta lista de destinos secundarios es más exhaustiva, y cada destino secundario contiene más información.
landmarks[]

object (Landmark)

Son puntos de referencia que se pueden usar para comunicar dónde se encuentra el destino o ayudar con la llegada.
entrances[]

object (Entrance)

Son las entradas de este destino.
navigationPoints[]

object (NavigationPoint)

Son los puntos de navegación de este destino.
parkingOptions

object (Destination.ParkingOptions)

Son las opciones de estacionamiento para este destino.
arrivalSummary

object (Destination.ArrivalSummary)

Resumen generado por IA de la experiencia de llegada al destino.

PlaceView

Representa una vista de un lugar en la API de Places. También proporciona información adicional específica de los destinos, como el tipo de estructura y el polígono de visualización.

En algunos casos, un PlaceView con el mismo ID de lugar puede diferir de lo que devuelve la API de Places para los campos types y displayName.

Representación 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)
    }
  ]
}
Campos
place

string

Es el nombre del recurso de este lugar, en formato places/{placeId}. Se puede usar para buscar el lugar.
placeId

string

Es el identificador único de un lugar.
displayName

object (LocalizedText)

Descripción del lugar legible por humanos. Por ejemplo, "Puerta B", "McDonalds"
primaryType

string

Es el tipo de lugar principal de este lugar. Consulta https://developers.google.com/maps/documentation/places/web-service/place-types para ver la lista de valores posibles.

Nota: Este campo no siempre se completa. Prepárate para usar el campo types en esas situaciones.
types[]

string

Todos los tipos de lugar asociados con este lugar. Consulta https://developers.google.com/maps/documentation/places/web-service/place-types para ver la lista de valores posibles.
formattedAddress

string

Dirección de una línea.
postalAddress

object (PostalAddress)

Dirección estructurada.
structureType

enum (PlaceView.StructureType)

Es el tipo de estructura que corresponde a este lugar.
location

object (LatLng)

Es la ubicación de este lugar. En el caso de los lugares con polígonos de visualización, esto puede representar un buen punto para colocar un marcador en el mapa.
displayPolygon

object (Struct format)

Es el contorno del polígono del lugar en formato GeoJSON, con el formato RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Nota: El formato RFC 7946 admite MultiPolygons, por lo que un objeto displayPolygon puede representar varios polígonos.
addressComponents[]

object (PlaceView.AddressComponent)

Componentes repetidos para cada nivel de localidad.

PlaceView.AddressComponent

Son los componentes estructurados que forman la dirección con formato, si esta información está disponible.

Representación JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Campos
longText

string

Es la descripción textual completa o el nombre del componente de la dirección. Por ejemplo, un componente de dirección para el país Australia puede tener el nombre largo "Australia".
shortText

string

Es un nombre textual abreviado para el componente de la dirección si está disponible. Por ejemplo, un componente de dirección para el país Australia puede tener el nombre corto "AU".
types[]

string

Es un array que indica los tipos de componentes de la dirección.

Estos valores se extraen de la tabla de tipos de direcciones y tipos de componentes de dirección que usa la API de Places: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
languageCode

string

Es el idioma que se usa para dar formato a este componente, en notación CLDR.

Punto de referencia

Los puntos de referencia se usan para comunicar dónde está el destino o ayudar a llegar a él.

Representación 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.
}
Campos
relationalDescription

object (LocalizedText)

Es una descripción legible por humanos de cómo se relaciona el destino con el punto de referencia. Por ejemplo: "Cerca del edificio Empire State" o "Frente a la Casa Blanca".
tags[]

enum (Landmark.Tag)

Son etiquetas que describen cómo se puede usar el punto de referencia en el contexto del destino.
straightLineDistanceMeters

number

Solo salida. Es la distancia en línea recta desde este punto de referencia hasta el destino, en metros.
travelDistanceMeters

number

Solo salida. Es la distancia a pie desde este punto de referencia hasta el destino, en metros.
Es el punto de referencia. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
place

object (PlaceView)

Es el lugar que representa este punto de referencia.
Fin de los campos mutuamente excluyentes.

Landmark.Tag

Es la lista de todas las etiquetas posibles que describen cómo se puede usar un punto de referencia en el contexto de un destino.

Si una dirección tiene las etiquetas ADDRESS y ARRIVAL, significa que el punto de referencia es destacado a nivel local y está cerca del destino.

Enums
TAG_UNSPECIFIED No se usa.
ADDRESS Un lugar destacado a nivel local que se puede usar para identificar la ubicación general del destino. Por lo general, a unos cientos de metros del destino. Son similares a los puntos de referencia que devuelve la función de descriptores de direcciones de la API de Geocoding: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Es un lugar que se puede usar para ayudar a llegar al destino. Es útil para la navegación una vez que estás cerca del destino. Por ejemplo, este punto de referencia podría ser un lugar que se encuentra cruzando la calle desde el destino. Un punto de referencia con esta etiqueta suele estar más cerca del destino que los puntos de referencia con la etiqueta ADDRESS.

Entrada

Una entrada es un par de coordenadas de latitud y longitud que define la ubicación de un punto de entrada y salida de un lugar.

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

object (LocalizedText)

Nombre legible por humanos, p.ej., "Puerta B", "Entrada sur", "Entrada de la 5ª avenida".
location

object (LatLng)

La ubicación de la entrada.
tags[]

enum (Entrance.Tag)

Es una lista de etiquetas que describen la entrada.
place

string

Es la estructura en la que se encuentra físicamente esta entrada, en formato places/{placeId}.
streetViewThumbnail

object (StreetViewThumbnail)

Imagen en miniatura de Street View que muestra la entrada. La imagen se puede solicitar a la API de Street View Static. Consulta https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

Anotación de la entrada en el streetViewThumbnail que se devolvió anteriormente.

Entrance.Tag

Características que describen una entrada.

Enums
TAG_UNSPECIFIED No se usa.
PREFERRED

Es probable que la entrada proporcione acceso físico al lugar principal en el destino que se muestra. Un lugar puede tener varias entradas preferidas. Si una entrada no tiene esta etiqueta, significa que se encuentra físicamente en el mismo edificio que el lugar principal, pero no necesariamente proporciona acceso a él.

Por ejemplo, si el lugar principal es un restaurante en un centro comercial, las entradas "PREFERRED" serán las que probablemente lleven al restaurante, mientras que las otras entradas devueltas serán otras entradas del edificio, como las entradas a otros restaurantes del centro comercial.

Si el lugar principal es un edificio, las entradas PREFERRED serán las que conducen a la parte "principal" del edificio. Por ejemplo, en un centro comercial, las entradas PREFERRED serán las que permitan acceder al vestíbulo principal, pero si una entrada solo permite acceder a una tienda en el lateral del edificio, no será una entrada PREFERRED.

Nota: Es posible que una entrada PREFERRED no proporcione acceso al lugar principal y que una entrada que no sea PREFERRED sí lo haga.

StreetViewThumbnail

Son los parámetros para representar una miniatura de Google Street View. Estos parámetros se pueden usar para solicitar una imagen de Street View a la API de Street View Static. Consulta https://developers.google.com/maps/documentation/streetview/request-streetview.

Representación JSON 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
Campos
pano

string

Un ID de panorámica específico
widthPx

integer

Es el ancho de la imagen de la miniatura de salida en píxeles. Nota: Cuando solicites anotaciones junto con la miniatura, estos valores de altura y ancho se deben usar en la solicitud a la API de Street View para garantizar que las coordenadas de la anotación se alineen correctamente con la imagen.
heightPx

integer

Es la altura de la imagen de la miniatura de salida en píxeles. Nota: Cuando solicites anotaciones junto con la miniatura, estos valores de altura y ancho se deben usar en la solicitud a la API de Street View para garantizar que las coordenadas de la anotación se alineen correctamente con la imagen.
headingDegree

number

Es la orientación horizontal de la cámara en grados. Rango [0, 360). El 0 indica el norte y el 90, el este.
pitchDegree

number

Es la orientación vertical de la cámara en grados. Rango [-90, 90]. 0 es el horizonte, +90 es hacia arriba y -90 es hacia abajo.
fovDegree

number

Es el campo visual horizontal en grados. Rango (0, 180]. Controla el nivel de zoom. Un FOV más pequeño significa más zoom.

ImageAnnotation

Es una anotación en una miniatura de imagen, como un polígono que delimita una entrada.

Representación JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
Campos
coordinates[]

object (ImageAnnotation.Coordinate)

Es una lista de coordenadas que forman un polígono en la imagen. Las coordenadas se ordenan en el sentido contrario a las manecillas del reloj.

ImageAnnotation.Coordinate

Coordenada de píxel de un punto de la imagen. El origen (0,0) es la esquina superior izquierda del píxel superior izquierdo de la imagen, con el eje X apuntando hacia la derecha y el eje Y apuntando hacia abajo.

Representación JSON 
{
  "xPx": number,
  "yPx": number
}
Campos
xPx

number

Coordenada de X.
yPx

number

Coordenada de Y.

Destination.ParkingOptions

Información sobre las opciones de estacionamiento para el destino.

Representación 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
}
Campos
availability

enum (Destination.ParkingOptions.Availability)

La disponibilidad de estacionamiento para este destino.
parkingFacilities[]

object (Destination.ParkingOptions.ParkingFacility)

Las instalaciones de estacionamiento de este destino.
onsiteParking

boolean

Hay estacionamiento en el destino.
freeParkingLot

boolean

Ofrece estacionamiento gratuito.
paidParkingLot

boolean

Ofrece estacionamientos pagados.
freeStreetParking

boolean

Ofrece estacionamiento gratuito en la calle.
paidStreetParking

boolean

Ofrece estacionamiento pagado en la calle.
valetParking

boolean

Ofrece servicio de estacionamiento.
freeGarageParking

boolean

Ofrece estacionamiento gratuito en cochera.
paidGarageParking

boolean

Ofrece estacionamiento en cochera de pago.

Destination.ParkingOptions.Availability

Es una medición agregada de la dificultad para encontrar estacionamiento cuando se visita este lugar.

Es posible que se agreguen valores nuevos en el futuro.

Enums
AVAILABILITY_UNSPECIFIED La disponibilidad de estacionamiento no está disponible.
PLENTY Hay mucho espacio de estacionamiento disponible.
SOMEWHAT_DIFFICULT Es un poco difícil encontrar estacionamiento.
DIFFICULT Es muy difícil encontrar estacionamiento.

Destination.ParkingOptions.ParkingFacility

Es una opción de estacionamiento individual y discreta (p.ej., un estacionamiento o un lote específicos) asociada con el destino. Este mensaje proporciona información detallada sobre un estacionamiento específico, mientras que el mensaje ParkingOptions superior proporciona un resumen de todos los estacionamientos disponibles.

Representación JSON 
{
  "place": {
    object (PlaceView)
  },
  "onsite": boolean,
  "popular": boolean,
  "straightLineDistanceMeters": number
}
Campos
place

object (PlaceView)

Es la representación del lugar de este estacionamiento específico.
onsite

boolean

Indica si este estacionamiento se encuentra en las instalaciones del destino principal. Si no se configura este campo, se desconoce el estado en las instalaciones.
popular

boolean

Indica si este estacionamiento es una opción popular para los visitantes que viajan al destino principal. Si no se establece este campo, se desconoce el estado de popularidad.
straightLineDistanceMeters

number

Es la distancia en línea recta en metros desde el destino principal hasta este estacionamiento.

Destination.ArrivalSummary

Resumen generado por IA de la experiencia de llegada al destino.

Representación JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Campos
text

object (LocalizedText)

Es el resumen de la experiencia de llegada al destino.
flagContentUrl

string

Un vínculo en el que los usuarios pueden marcar un problema con el resumen
disclosureText

object (LocalizedText)

Solo salida. Contiene el texto de divulgación del resumen de llegada.