Se usó la API de Cloud Translation para traducir esta página.

Nearby Search (nueva)

Selecciona la plataforma: Android iOS JavaScript Servicio web

Una solicitud de Nearby Search (nueva) 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. La Búsqueda de lugares cercanos (nueva) 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ébalo

Prueba la demostración interactiva para ver los resultados de la Búsqueda cercana (nueva) en un mapa.

Solicitudes de Nearby Search (nuevo)

Una solicitud de Búsqueda de lugares cercanos (nueva) es una solicitud HTTP POST a una URL con 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)

La Búsqueda cercana (nueva) muestra un objeto JSON como respuesta. En la respuesta, figura lo siguiente:

El array places contiene todos los lugares que coinciden.
Cada lugar del array está representado por un objeto Place. El objeto Place 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 con el parámetro de URL $fields o fields, o con el encabezado HTTP X-Goog-FieldMask. No hay una lista predeterminada de 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 deseas que se muestren. Por ejemplo, para recuperar el nombre visible y la dirección del lugar.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Nota: No se permiten espacios en ninguna parte de la lista de campos.

Usa * para recuperar todos los campos.
```
X-Goog-FieldMask: *
```
El comodín “*” selecciona todos los campos. Sin embargo, si bien es adecuado usar ese comodín en el desarrollo, Google desaconseja el uso de la máscara de campo de respuesta comodín (*) en producción debido a la gran cantidad de datos que se pueden mostrar.

Puedes encontrar más orientación para usar places.iconMaskBaseUri y places.iconBackgroundColor en la sección Íconos de lugares.

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.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* El campo places.googleMapsLinks se encuentra en la etapa de vista previa de la fase previa a la DG y no se cobra, lo que significa que la facturación es de USD 0 por el uso durante la vista previa.
  
  ^** El campo places.name contiene el nombre de recurso del lugar con el siguiente formato: places/PLACE_ID. Usa places.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.priceRange, 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.routingSummaries,^* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout
  
  ^* Solo Búsqueda de texto y Búsqueda cercana
locationRestriction

La región que se debe buscar especificada como un círculo, definido por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. El valor predeterminado es 0.0. Debes configurarlo 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

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Te permite especificar una lista de tipos de los tipos de la Tabla A que se usa para filtrar los resultados de la búsqueda. Se pueden especificar hasta 50 tipos en cada categoría de restricción de tipos.

Nota: Los valores de la Tabla B solo se muestran en la respuesta. No puedes usar los valores de la Tabla B como filtro.

Un lugar solo puede tener asociado un tipo principal de los tipos de la Tabla A. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house". Usa includedPrimaryTypes y excludedPrimaryTypes para filtrar los resultados según el tipo principal de un lugar.

Un lugar también puede tener varios valores de tipo asociados a los tipos de la Tabla A. Por ejemplo, un restaurante podría tener los siguientes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest" y "establishment". Usa includedTypes y excludedTypes para filtrar los resultados de la lista de tipos asociados con un lugar.

Cuando especificas un tipo principal general, como "restaurant" o "hotel", la respuesta puede contener lugares con un tipo principal más específico que el especificado. Por ejemplo, especificas que se incluya un tipo principal de "restaurant". Luego, la respuesta puede contener lugares con un tipo principal de "restaurant", pero también puede contener lugares con un tipo principal más específico, como "chinese_restaurant" o "seafood_restaurant".

Si se especifica una búsqueda con varias restricciones de tipo, solo se muestran los lugares que satisfacen todas las restricciones. Por ejemplo, si especificas {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, los lugares que se muestran proporcionan servicios relacionados con "restaurant", pero no funcionan principalmente como "steak_house".

Si omites includedTypes, excludedTypes, includedPrimaryTypes y excludedPrimaryTypes de la solicitud, la búsqueda muestra lugares de todos los tipos dentro de los límites de restricción de ubicación.

includedTypes

Es una lista separada por comas de los tipos de lugares de la Tabla A que se buscarán. Si se omite este parámetro, se devuelven lugares de todos los tipos.

excludedTypes

Es una lista de tipos de lugares de la Tabla A separados por comas que se deben excluir de una búsqueda.

Si especificas includedTypes ( como "school") y excludedTypes (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 los includedTypes y ninguno de los excludedTypes.

Si hay tipos en conflicto, como uno que aparece en includedTypes y excludedTypes, se muestra un error INVALID_REQUEST.

includedPrimaryTypes

Es una lista separada por comas de los tipos de lugares principales de la Tabla A para incluir en una búsqueda.

excludedPrimaryTypes

Una lista separada por comas de los tipos de lugares principales de la Tabla A que se excluirán de una búsqueda.

Si hay tipos principales en conflicto, como uno que aparece en includedPrimaryTypes y excludedPrimaryTypes, se muestra un error INVALID_ARGUMENT.
languageCode

Es el idioma en el que se mostrarán los resultados.
- Consulta la lista de idiomas admitidos. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea completa.
- Si no se proporciona languageCode, la API se establece de forma predeterminada en en. Si especificas un código de idioma no válido, la API muestra un error INVALID_ARGUMENT.
- La API hace todo lo posible para proporcionar una dirección que sea legible para el usuario y los locales. Para alcanzar este objetivo, muestra las direcciones en el idioma local transliterada en una secuencia de comandos legible para el usuario, si es necesario, que respete el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. 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 poco efecto en el conjunto de resultados que la API selecciona para mostrar y el orden en el que se muestran. El geocodificador interpreta las abreviaturas de forma diferente según el idioma, como las abreviaturas para tipos de calle o 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 estar comprendido entre 1 y 20 (valor predeterminado) inclusive.
rankPreference

Es 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 (predeterminada): Ordena los resultados según su popularidad.
- DISTANCE Ordena los resultados en orden ascendente según su distancia desde la ubicación especificada.
regionCode

Es el código de región 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 con el regionCode, se omite el código de país de formattedAddress. Este parámetro no tiene efecto en adrFormatAddress, que siempre incluye el nombre del país, ni en shortFormattedAddress, 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)

Cómo encontrar lugares de un tipo

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nueva) para los nombres visibles de todos los restaurantes dentro de un radio de 500 metros, definido 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 respuesta 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 respuesta 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"
      }
    },
...
}

Cómo encontrar lugares de varios tipos

En el siguiente ejemplo, se muestra una solicitud de Búsqueda cercana (nueva) para los nombres visibles de todas las tiendas de conveniencia y licorerías 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:searchNearby

En 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 en los resultados.

Cómo excluir un tipo de lugar de una búsqueda

En el siguiente ejemplo, se muestra una solicitud de Búsqueda de lugares cercanos (nueva) para todos los lugares de tipo "school", que excluye todos los lugares de tipo "primary_school" y 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

Buscar todos los lugares cerca de un área, ordenados por distancia

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nueva) para lugares cercanos a un punto del centro de San Francisco. En este ejemplo, incluyes el parámetro rankPreference para ordenar 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 te familiarices con la API y sus opciones.

Selecciona el ícono de la API, , en el lado derecho 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.

Nearby Search (nueva)

Solicitudes de Nearby Search (nuevo)

Respuestas de Nearby Search (nuevo)

Parámetros obligatorios

FieldMask

locationRestriction

Parámetros opcionales

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

Ejemplos de Nearby Search (nuevo)

Cómo encontrar lugares de un tipo

Cómo encontrar lugares de varios tipos

Cómo excluir un tipo de lugar de una búsqueda

Buscar todos los lugares cerca de un área, ordenados por distancia

Pruébalo