Una solicitud de Nearby Search (nuevo) toma uno o más tipos de lugares y muestra una lista de lugares coincidentes dentro del área especificada. Se requiere una máscara de campo que especifique uno o más tipos de datos. Nearby Search (nuevo) solo admite solicitudes POST.
El Explorador de APIs te permite realizar solicitudes en tiempo real para que puedas familiarizarte con la API y sus opciones:
PruébalaSolicitudes de Nearby Search (nuevo)
Una solicitud de Nearby Search (nuevo) es una solicitud HTTP POST a una URL que tiene el siguiente formato:
https://places.googleapis.com/v1/places:searchNearby
Pasa todos los parámetros en el cuerpo de la solicitud JSON o en los encabezados como parte de la solicitud POST. Por ejemplo:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Respuestas de Nearby Search (nuevo)
Nearby Search (nuevo) muestra un objeto JSON como respuesta. En la respuesta, figura lo siguiente:
- El array
places
contiene todos los lugares coincidentes. - Cada lugar del array se representa con un objeto
Place
. El objetoPlace
contiene información detallada sobre un solo lugar. - La FieldMask pasada en la solicitud especifica la lista de campos que se muestran en el objeto
Place
.
El objeto JSON completo tiene el siguiente formato:
{ "places": [ { object (Place) } ] }
Parámetros obligatorios
-
FieldMask
Especifica la lista de campos que se mostrarán en la respuesta. Para ello, crea una máscara de campo de respuesta. Pasa la máscara de campo de respuesta al método mediante el parámetro de URL
$fields
ofields
, o bien con el encabezado HTTPX-Goog-FieldMask
. No hay una lista predeterminada de los campos que se muestran en la respuesta. Si omites la máscara de campo, el método mostrará un error.El enmascaramiento de campo es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación innecesarios.
Especifica una lista separada por comas de los tipos de datos de lugar que se mostrarán. Por ejemplo, para recuperar el nombre visible y la dirección del lugar.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Usa
*
para recuperar todos los campos.X-Goog-FieldMask: *
Especifica uno o más de los siguientes campos:
Los siguientes campos activan el SKU de Nearby Search (Basic):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* El campoplaces.name
contiene el nombre de recurso del lugar expresado de la siguiente forma:places/PLACE_ID
. Utilizaplaces.displayName
para acceder al nombre del lugar en forma de texto.Los siguientes campos activan el SKU de Nearby Search (Advanced):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Los siguientes campos activan el SKU de Nearby Search (Preferred):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.servesBreakfast
/{2,}/{2,}/{2,}/places.servesBeer
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
La región en la que se va a buscar especificada como un círculo, que se define por el punto central y el radio en metros. El radio debe ser de entre 0.0 y 50,000.0, inclusive. El radio predeterminado es 0.0. Debes establecerlo en tu solicitud en un valor superior a 0.0.
Por ejemplo:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Parámetros opcionales
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Te permite especificar una lista de tipos de los tipos de la Tabla A que se usan para filtrar los resultados de la búsqueda. Se pueden especificar hasta 50 tipos en cada categoría de restricción de tipo.
Un lugar solo puede tener un tipo principal asociado a los tipos de la Tabla A. Por ejemplo, el tipo principal podría ser
"mexican_restaurant"
o"steak_house"
. UtilizaincludedPrimaryTypes
yexcludedPrimaryTypes
para filtrar los resultados según el tipo principal de un lugar.Un lugar también puede tener varios valores de tipo de tipos de la Tabla A asociados. Por ejemplo, un restaurante podría tener los siguientes tipos:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
y"establishment"
. UtilizaincludedTypes
yexcludedTypes
para filtrar los resultados en la lista de tipos asociados con un lugar.Si se especifica una búsqueda con varias restricciones de tipo, solo se mostrarán los lugares que cumplan con todas las restricciones. Por ejemplo, si especificas
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, los lugares que se muestran proporcionan servicios relacionados con"restaurant"
, pero no operan principalmente como"steak_house"
.includedTypes
Es una lista separada por comas de los tipos de lugares de la Tabla A que se deben buscar. Si se omite este parámetro, se muestran lugares de todos los tipos.
excludedTypes
Lista de los tipos de lugares separados por comas de la Tabla A que se deben excluir de una búsqueda.
Si especificas el
includedTypes
( como"school"
) y elexcludedTypes
(como"primary_school"
) en la solicitud, la respuesta incluirá lugares categorizados como"school"
, pero no como"primary_school"
. La respuesta incluye lugares que coinciden con al menos uno de losincludedTypes
y ninguno de de losexcludedTypes
.Si hay algún tipo en conflicto, como un tipo que aparece en
includedTypes
yexcludedTypes
, se muestra un errorINVALID_REQUEST
.includedPrimaryTypes
Es una lista separada por comas de los tipos de lugares principales de la Tabla A que se deben incluir en una búsqueda.
excludedPrimaryTypes
Es una lista separada por comas de los tipos de lugares principales de la Tabla A que se excluyen de una búsqueda.
Si hay tipos principales en conflicto, como un tipo que aparece en
includedPrimaryTypes
yexcludedPrimaryTypes
, se muestra un errorINVALID_ARGUMENT
. -
languageCode
El idioma en el que se mostrarán los resultados.
- Consulta la lista de idiomas compatibles. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
- Si no se proporciona
languageCode
, el valor predeterminado de la API esen
. Si especificas un código de idioma no válido, la API mostrará un errorINVALID_ARGUMENT
. - La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los locales. Para lograr ese objetivo, muestra las direcciones en el idioma local, transliteradas en una secuencia de comandos que el usuario puede leer si es necesario, teniendo en cuenta el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de dirección se muestran en el mismo idioma, que se elige a partir del primer componente.
- Si un nombre no está disponible en el idioma preferido, la API usa la coincidencia más cercana.
- El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y el orden en el que se muestran. El geocodificador interpreta las abreviaturas de forma diferente según el idioma; por ejemplo, las abreviaturas para los tipos de calles o los sinónimos que pueden ser válidos en un idioma, pero no en otro.
-
maxResultCount
Especifica la cantidad máxima de resultados de lugares que se mostrarán. Debe ser un valor entre 1 y 20 (predeterminado) inclusive.
-
rankPreference
El tipo de clasificación que se usará. Si se omite este parámetro, los resultados se clasifican por popularidad. Puede ser uno de los siguientes:
POPULARITY
(predeterminado): Ordena los resultados según su popularidad.DISTANCE
: Ordena los resultados en orden ascendente según su distancia desde la ubicación especificada.
-
regionCode
El código regional que se usa para dar formato a la respuesta, especificado como un valor de código CLDR de dos caracteres. No hay un valor predeterminado.
Si el nombre del país del campo
formattedAddress
en la respuesta coincide conregionCode
, el código de país se omite deformattedAddress
. Este parámetro no tiene efecto enadrFormatAddress
, que siempre incluye el nombre del país, ni enshortFormattedAddress
, que nunca lo incluye.La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad de "Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la ley aplicable.
Ejemplos de Nearby Search (nuevo)
Buscar lugares de un tipo
En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para los nombres visibles de todos los restaurantes dentro de un radio de 500 metros, definidos por circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Ten en cuenta que el encabezado X-Goog-FieldMask
especifica que la respuesta contiene los siguientes campos de datos: places.displayName
.
La response tiene el siguiente formato:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Agrega más tipos de datos a la máscara de campo para mostrar información adicional.
Por ejemplo, agrega places.formattedAddress,places.types,places.websiteUri
para incluir la dirección, el tipo y la dirección web del restaurante en la respuesta:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
La response ahora tiene el siguiente formato:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Encuentra lugares de varios tipos
En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para los nombres visibles de todos los minimercados y las tiendas de licores dentro de un radio de 1,000 metros del circle
especificado:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyEn este ejemplo, se agregan
places.primaryType
y places.types
a la máscara de campo para que la respuesta incluya información de tipo sobre cada lugar, lo que facilita la selección del lugar apropiado de los resultados.
Cómo excluir un tipo de lugar de una búsqueda
En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para todos los lugares de tipo "school"
, excepto todos los lugares de tipo "primary_school"
, que clasifica los resultados por distancia:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Busca todos los lugares cercanos a un área, clasificándolos por distancia
En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para lugares cercanos a un punto en el centro de San Francisco. En este ejemplo, se incluye el parámetro rankPreference
para clasificar los resultados por distancia:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Pruébalo
El Explorador de APIs te permite realizar solicitudes de muestra para que puedas familiarizarte con la API y sus opciones.
- Selecciona el ícono de la API, , a la derecha de la página.
- De manera opcional, expande Mostrar parámetros estándar y establece el parámetro
fields
en la máscara de campo. - De manera opcional, edita el Cuerpo de la solicitud.
- Selecciona el botón Ejecutar. En la ventana emergente, elige la cuenta que deseas usar para realizar la solicitud.
En el panel del Explorador de API, selecciona el ícono de expansión, , para expandir la ventana del Explorador de API.