La función Nearby Search (heredada) te permite buscar lugares dentro de un área especificada. Puedes definir mejor tu solicitud de búsqueda proporcionando palabras clave o especificando el tipo de lugar que buscas.
Solicitudes de Nearby Search (heredada)
Una solicitud de Nearby Search (heredada) es una URL HTTP con el siguiente formato:
https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters
donde output puede ser cualquiera de los siguientes valores:
json(recomendado) indica el resultado en notación de objeto de JavaScript (JSON).xmlindica que el resultado es XML.
Se requieren ciertos parámetros para iniciar una solicitud de Nearby Search (heredada). Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&).
Parámetros obligatorios
-
ubicación
Es el punto alrededor del cual se recuperará la información del lugar. Se debe especificar como
latitude,longitude. -
radio
Define la distancia (en metros) dentro de la cual se deben mostrar los resultados de lugares. Puedes personalizar los resultados para un círculo específico si pasas los parámetros
locationyradius. Esto le indica al servicio Places que prefiera mostrar resultados dentro de ese círculo. Es posible que también se muestren resultados externos al área definida.El radio se limitará automáticamente a un valor máximo según el tipo de búsqueda y otros parámetros.
- Autocompletar: 50,000 metros
-
Nearby Search:
- con
keywordoname: 50,000 metros -
sin
keywordniname-
Hasta 50,000 metros, ajustado de forma dinámica según la densidad del área,
independientemente del parámetro
rankby. -
Cuando uses
rankby=distance, no se aceptará el parámetro de radio, lo que generará un errorINVALID_REQUEST.
-
Hasta 50,000 metros, ajustado de forma dinámica según la densidad del área,
independientemente del parámetro
- con
- Query Autocomplete: 50,000 metros
- Text Search: 50,000 metros
Parámetros opcionales
-
palabra clave
Es la cadena de texto en la que se basa la búsqueda, por ejemplo, "restaurante" o "calle principal 123". Debe ser el nombre de un lugar, una dirección o una categoría de establecimientos. Cualquier otro tipo de entrada puede generar errores y no se garantiza que devuelva resultados válidos. El servicio de Google Places devolverá posibles coincidencias en función de esta cadena y ordenará los resultados según la relevancia percibida.
Incluir explícitamente información de ubicación con este parámetro puede generar un conflicto con los parámetros location, radius y rankby, lo que puede producir resultados inesperados.
Si se omite este parámetro, no se mostrarán los lugares con un business_status de CLOSED_TEMPORARILY o CLOSED_PERMANENTLY.
-
idioma
Es el idioma en el que se devolverán los resultados.
- Consulta la lista de idiomas disponibles. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
-
Si no se proporciona
language, la API intenta usar el idioma preferido, como se especifica en el encabezadoAccept-Language. - 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, devuelve direcciones en el idioma local, transliteradas a una escritura legible por el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven 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 en el orden en que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles o los sinónimos que pueden ser válidos en un idioma, pero no en otro. Por ejemplo, utca y tér son sinónimos de calle en húngaro.
-
maxprice
Restringe los resultados a los lugares dentro del rango especificado. El rango de valores válidos se extiende de 0 (más asequible) a 4 (más costoso), inclusive. La cantidad exacta que indica un valor específico variará de una región a otra.
-
minprice
Restringe los resultados a los lugares dentro del rango especificado. El rango de valores válidos se extiende de 0 (más asequible) a 4 (más costoso), inclusive. La cantidad exacta que indica un valor específico variará de una región a otra.
-
nombre
Equivale a
keyword. Los valores de este campo se combinan con los del campokeywordy se pasan como parte de la misma cadena de búsqueda. -
opennow
Devuelve solo los lugares que están abiertos en el momento en que se envía la consulta. Los lugares que no especifican los horarios de atención en la base de datos de Google Places no se mostrarán si incluyes este parámetro en tu consulta.
-
pagetoken
Devuelve hasta 20 resultados de una búsqueda ejecutada anteriormente. Si configuras un parámetro
pagetoken, se ejecuta una búsqueda con los mismos parámetros que se usaron antes; se ignoran todos los parámetros que no seanpagetoken. -
rankby
Especifica el orden en el que se enumeran los resultados. Los valores posibles son:
-
prominence(predeterminado): Esta opción ordena los resultados según su importancia. La clasificación da prioridad a los lugares más relevantes dentro del radio establecido sobre los lugares cercanos que coinciden con la búsqueda pero son menos relevantes. La relevancia puede verse afectada por la clasificación de un lugar en el índice de Google, la popularidad global y otros factores. Cuando se especifica la prominencia, el parámetroradiuses obligatorio. -
distance. Esta opción sesga los resultados de la búsqueda en orden ascendente según su distancia desde la ubicación especificada. Cuando se especificadistance, se requieren uno o más objetoskeyword,nameotype, y no se permiteradius.
-
-
tipo
Restringe los resultados a los lugares que coinciden con el tipo especificado. Solo puedes especificar un tipo. Si proporcionas más de un tipo, la API ignorará todos los tipos que sigan a la primera entrada.
-
type=hospital|pharmacy|doctorse convierte entype=hospital type=hospital,pharmacy,doctorse ignora por completo.
Consulta la lista de tipos admitidos.
Nota: Agregarkeywordytypecon el mismo valor (keyword=cafe&type=cafeokeyword=parking&type=parking) puede generarZERO_RESULTS. -
Ejemplo de Nearby Search (heredado)
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'HTTP
https://maps.googleapis.com/maps/api/place/nearbysearch/json ?keyword=cruise &location=-33.8670522%2C151.1957362 &radius=1500 &type=restaurant &key=YOUR_API_KEY
Nota: En este ejemplo, debes reemplazar key por tu propia clave de API para que la solicitud funcione en tu aplicación.
Respuestas de Nearby Search (heredado)
En el siguiente ejemplo, se muestra una respuesta de Nearby Search (heredada).
JSON
{ "html_attributions": [], "results": [ { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8587323, "lng": 151.2100055 }, "viewport": { "northeast": { "lat": -33.85739847010727, "lng": 151.2112436298927 }, "southwest": { "lat": -33.86009812989271, "lng": 151.2085439701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png", "icon_background_color": "#FF9E67", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet", "name": "Cruise Bar", "opening_hours": { "open_now": false }, "photos": [ { "height": 608, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG", "width": 1080, }, ], "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI", "plus_code": { "compound_code": "46R6+G2 The Rocks, New South Wales", "global_code": "4RRH46R6+G2", }, "price_level": 2, "rating": 4, "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI", "scope": "GOOGLE", "types": ["bar", "restaurant", "food", "point_of_interest", "establishment"], "user_ratings_total": 1269, "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks", }, { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8675219, "lng": 151.2016502 }, "viewport": { "northeast": { "lat": -33.86614532010728, "lng": 151.2031259298927 }, "southwest": { "lat": -33.86884497989272, "lng": 151.2004262701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png", "icon_background_color": "#7B9EB0", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet", "name": "Sydney Harbour Dinner Cruises", "opening_hours": { "open_now": true }, "photos": [ { "height": 835, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7", "width": 1200, }, ], "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids", "plus_code": { "compound_code": "46J2+XM Sydney, New South Wales", "global_code": "4RRH46J2+XM", }, "rating": 4.8, "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids", "scope": "GOOGLE", "types": [ "tourist_attraction", "travel_agency", "restaurant", "food", "point_of_interest", "establishment", ], "user_ratings_total": 9, "vicinity": "32 The Promenade, Sydney", }, // ... ], "status": "OK", }
XML
<?xml version="1.0" encoding="UTF-8"?> <PlaceSearchResponse> <status>OK</status> <result> <name>Cruise Bar</name> <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity> <type>bar</type> <type>restaurant</type> <type>food</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8587323</lat> <lng>151.2100055</lng> </location> <viewport> <southwest> <lat>-33.8600981</lat> <lng>151.2085440</lng> </southwest> <northeast> <lat>-33.8573985</lat> <lng>151.2112436</lng> </northeast> </viewport> </geometry> <rating>4.0</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon> <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference> <opening_hours> <open_now>false</open_now> </opening_hours> <photo> <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference> <width>1080</width> <height>608</height> <html_attribution><a href="https://maps.google.com/maps/contrib/112582655193348962755">A Google User</a></html_attribution> </photo> <price_level>2</price_level> <user_ratings_total>1269</user_ratings_total> <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46R6+G2</global_code> <compound_code>46R6+G2 The Rocks, New South Wales</compound_code> </plus_code> <icon_background_color>#FF9E67</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri> </result> <result> <name>Sydney Harbour Dinner Cruises</name> <vicinity>32 The Promenade, Sydney</vicinity> <type>tourist_attraction</type> <type>restaurant</type> <type>food</type> <type>travel_agency</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8675219</lat> <lng>151.2016502</lng> </location> <viewport> <southwest> <lat>-33.8688450</lat> <lng>151.2004263</lng> </southwest> <northeast> <lat>-33.8661453</lat> <lng>151.2031259</lng> </northeast> </viewport> </geometry> <rating>4.8</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon> <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference> <width>1200</width> <height>835</height> <html_attribution><a href="https://maps.google.com/maps/contrib/109764923610545394994">A Google User</a></html_attribution> </photo> <user_ratings_total>9</user_ratings_total> <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46J2+XM</global_code> <compound_code>46J2+XM Sydney, New South Wales</compound_code> </plus_code> <icon_background_color>#7B9EB0</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri> </result> <!-- ... --> </PlaceSearchResponse>
PlacesNearbySearchResponse
| Campo | Obligatorio | Tipo | Descripción |
|---|---|---|---|
|
required | Array<string> |
Puede contener un conjunto de atribuciones sobre esta ficha que se deben mostrar al usuario (es posible que algunas fichas no tengan atribución). |
|
required | Array<Place> |
Contiene un array de lugares.
Las solicitudes de Place Search muestran un subconjunto de los campos que muestran las solicitudes de Place Details. Si Place Search no devuelve el campo que deseas, puedes usar esta función para obtener un
place_id y, luego, usar ese ID de lugar para realizar una solicitud de Place Details.
Consulta Lugar para obtener más información. |
|
required | PlacesSearchStatus |
Contiene el estado de la solicitud y puede incluir información de depuración para ayudarte a identificar el motivo del error en la solicitud. Consulta PlacesSearchStatus para obtener más información. |
|
opcional | string |
Cuando el servicio devuelve un código de estado que no es
|
|
opcional | Array<string> |
Cuando el servicio devuelve información adicional sobre la especificación de la solicitud, puede haber un campo |
|
opcional | string |
Contiene un token que se puede usar para mostrar hasta 20 resultados adicionales. No se devolverá un next_page_token si no hay resultados adicionales para mostrar. La cantidad máxima de resultados que se pueden mostrar es 60. Hay una pequeña demora entre el momento en que se emite un next_page_token y el momento en que se vuelve válido. |
PlacesSearchStatus
Códigos de estado que devuelve el servicio.
OK: Indica que la solicitud a la API se realizó correctamente.-
ZERO_RESULTSindica que la búsqueda se realizó correctamente, pero no se devolvieron resultados. Esto puede ocurrir si se pasó un valorlatlngen una ubicación remota a la búsqueda. -
INVALID_REQUEST: Indica que la solicitud a la API tenía un formato incorrecto, por lo general, debido a que faltaba un parámetro de consulta obligatorio (locationoradius). -
OVER_QUERY_LIMITque indique cualquiera de las siguientes opciones:- Superaste los límites de QPS.
- No se habilitó la facturación en tu cuenta.
- Se superó el crédito mensual de USD 200 o un límite de uso autoimpuesto.
- La forma de pago proporcionada ya no es válida (por ejemplo, una tarjeta de crédito venció).
-
REQUEST_DENIED: Indica que se rechazó tu solicitud, generalmente por los siguientes motivos:- Falta una clave de API en la solicitud.
- El parámetro
keyno es válido.
UNKNOWN_ERROR: Indica un error desconocido.
Lugar
Las respuestas de Place Search devuelven el siguiente subconjunto de los campos de Place. No todos los atributos están disponibles para todos los tipos de lugares. Para recuperar
los campos que Place Search no devuelve, como
address_components, formatted_phone_number,
reviews o website, pasa el
place_id devuelto en una
solicitud de Place Details (heredada). Para conocer la disponibilidad de los campos y los niveles de precios en los extremos, consulta
Campos de datos de Place (heredados).
| Campo | Tipo | Descripción |
|---|---|---|
business_status |
string |
Indica el estado operativo del lugar, si es una empresa:
OPERATIONAL, CLOSED_TEMPORARILY o
CLOSED_PERMANENTLY. Se omite si no existen datos de estado.
|
formatted_address |
string |
Es la dirección legible por humanos de este lugar. Se devuelve con Text Search (heredada) y Find Place (heredada). No analices la dirección con formato de manera programática; en su lugar, solicita address_components en Place Details (heredado).
|
geometry |
Geometry
|
Contiene el elemento location geocodificado con las coordenadas lat y lng, y el elemento viewport preferido con los límites northeast y southwest.
|
icon |
string |
Es la URL de un ícono sugerido que puedes mostrar cuando indicas este resultado en un mapa. |
icon_background_color
|
string |
Es el código de color hexadecimal predeterminado para la categoría del lugar. |
icon_mask_base_uri |
string |
Es la URL base de un ícono recomendado, sin la extensión de tipo de archivo SVG o PNG. |
name |
string |
Es el nombre legible por humanos del resultado que se muestra. Para los resultados de establishment, este valor suele ser el nombre canónico de la empresa.
|
opening_hours |
PlaceOpeningHours
|
Información sobre el horario de atención Los extremos de Place Search solo devuelven el subcampo booleano open_now. Solicita opening_hours en Place Details (heredado) para periods y weekday_text.
|
permanently_closed |
boolean |
Obsoleto: Usa business_status para verificar el estado operativo de una empresa.
|
photos |
Array<PlacePhoto>
|
Un array de objetos PlacePhoto, cada uno con un photo_reference, un height, un width y un html_attributions. Para obtener detalles de uso, consulta
Place Photos (heredado).
|
place_id |
string |
un identificador textual que identifica de forma exclusiva un sitio. Pasa este ID en el parámetro place_id de una solicitud de Place Details (heredada). Consulta la
descripción general del ID de lugar.
|
plus_code |
PlusCode
|
Es una referencia de ubicación codificada que se deriva de las coordenadas de latitud y longitud, y que contiene un global_code y un compound_code opcional.
|
price_level |
integer |
Es el nivel de precios del lugar en una escala de 0 a 4, de menos a más costoso. Consulta
price_level.
|
rating |
number |
Es la calificación del lugar, de 1.0 a 5.0, según las opiniones agregadas de los usuarios.
|
reference |
string |
Obsoleto: Usa place_id en su lugar.
|
scope |
string |
Obsoleto: Indica el alcance de place_id, que siempre es GOOGLE. Se devuelve con
Nearby Search (heredado).
|
types |
Array<string> |
Es un array de tipos de componentes que describen el resultado determinado. Consulta Tipos de lugar (heredados). |
user_ratings_total |
integer |
Es la cantidad total de calificaciones, con o sin texto de opinión, para este lugar. |
vicinity |
string |
Es una dirección simplificada del lugar, que incluye el nombre de la calle, el número y la localidad, pero no el estado o la provincia, el código postal ni el país. Se devuelve con la función Nearby Search (heredada). |
Cómo acceder a resultados adicionales
De forma predeterminada, cada respuesta devuelve hasta 20 resultados de establishment por consulta. Sin embargo, cada búsqueda puede arrojar hasta 60 resultados divididos en tres páginas. Si tu búsqueda devuelve más de
20 resultados, la respuesta incluirá
un valor adicional: next_page_token. Pasa el valor de
next_page_token al parámetro pagetoken de
una solicitud nueva para ver el siguiente conjunto de resultados.
- Si el
next_page_tokenes nulo o no se devuelve, no hay más resultados. - Si vuelves a intentar la solicitud con el mismo
next_page_token, se mostrará la siguiente página de resultados. - Si configuras
pagetoken, se ignorarán los demás parámetros. - Puedes solicitar una página nueva hasta dos veces después de la consulta original.
- Cada solicitud, incluida una que use
next_page_token, cuenta como una solicitud única para tus límites de uso y se cobra por separado. - Hay un retraso de unos segundos entre el momento en que se emite un
next_page_tokeny el momento en que se vuelve válido. Si solicitas la página siguiente antes de que esté disponible, se mostrará una respuestaINVALID_REQUEST. Las solicitudes connext_page_tokensiempre se cobran.
Por ejemplo, en la siguiente consulta, buscamos restaurantes cerca de Darling
Harbour, en Sídney, Australia, y clasificamos los resultados por distancia. Puedes ver
que la respuesta contiene una propiedad next_page_token.
{
"html_attributions" : [],
"next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
"results" : [...]
"status" : "OK"
}Para ver el siguiente conjunto de resultados, puedes enviar una consulta nueva y pasar el
resultado de next_page_token al parámetro
pagetoken. Por ejemplo:
https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY