Nearby Search (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web
Desarrolladores del Espacio Económico Europeo (EEE)

Introducción

Una solicitud de Nearby Search (nueva) toma uno o más tipos de lugar y devuelve 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 cercana (nueva) solo admite solicitudes POST.

El Explorador de APIs te permite realizar solicitudes en vivo para que te familiarices con la API y sus opciones:

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

Solicitudes de Nearby Search (nuevo)

Una solicitud de Nearby Search (nuevo) 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) devuelve un objeto JSON como respuesta. En la respuesta, figura lo siguiente:

  • El array places contiene todos los lugares coincidentes.
  • Cada lugar del array está representado por un objeto Place. El objeto Place contiene información detallada sobre un solo lugar.
  • El objeto FieldMask que se pasa en la solicitud especifica la lista de campos que se devuelven 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 devolverán en la respuesta creando 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 bien con el encabezado HTTP X-Goog-FieldMask. No hay una lista predeterminada de campos devueltos en la respuesta. Si omites la máscara de campo, el método mostrará un error.

    El uso de campos enmascarados 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 adicionales.

    Especifica una lista separada por comas de los tipos de datos de lugar que se devolverá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 Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      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.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Los descriptores de direcciones están disponibles de forma general para los clientes de la India y son experimentales en otros lugares.

      ** El campo places.name contiene el nombre de recurso del lugar con el siguiente formato: places/PLACE_ID. Utiliza places.displayName para acceder al nombre del lugar en forma de texto.

    • Los siguientes campos activan el SKU de Nearby Search Enterprise:

      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 Nearby Search Enterprise + Atmosphere:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Solo para Text Search y Nearby Search

  • locationRestriction

    Es la región de búsqueda especificada como un círculo, definida por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50,000.0, ambos inclusive. El radio predeterminado es 0.0. Debes establecerlo en tu solicitud en un valor mayor que 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 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.

    Un lugar solo puede tener un solo tipo principal de los tipos de la Tabla A asociados a él. 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 de los tipos de la Tabla A asociados a él. Por ejemplo, un restaurante podría tener los siguientes tipos: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Usa includedTypes y excludedTypes para filtrar los resultados en 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 que se especificó. Por ejemplo, especificas que se incluya un tipo principal de "restaurant". 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 devuelven los lugares que satisfacen todas las restricciones. Por ejemplo, si especificas {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, los lugares devueltos proporcionan servicios relacionados con "restaurant", pero no operan principalmente como "steak_house".

    includedTypes

    Es una lista separada por comas de los tipos de lugar 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 lugar separados por comas de la Tabla A que se deben excluir de una búsqueda.

    Si especificas tanto includedTypes ( como "school") como excludedTypes (como "primary_school") en la solicitud, la respuesta incluirá lugares que se categorizan 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 un tipo que aparece en includedTypes y excludedTypes, se devuelve un error INVALID_REQUEST.

    includedPrimaryTypes

    Es una lista separada por comas de los tipos de lugar principales de la Tabla A que se incluirán en una búsqueda.

    excludedPrimaryTypes

    Es una lista separada por comas de los tipos de lugar principales de la Tabla A que se deben excluir de una búsqueda.

    Si hay tipos principales en conflicto, como un tipo que aparece en includedPrimaryTypes y excludedPrimaryTypes, se devuelve un error de INVALID_ARGUMENT.

  • languageCode

    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 exhaustiva.
    • Si no se proporciona languageCode, la API usará en de forma predeterminada. Si especificas un código de idioma no válido, la API devuelve un error INVALID_ARGUMENT.
    • La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los residentes locales. Para lograr ese objetivo, devuelve direcciones de calles en el idioma local, transliteradas a una escritura que el usuario pueda leer si es necesario, y observa el idioma preferido. Todas las demás direcciones se muestran 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 elige la API para devolver y en el orden en que se devuelven. 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.

  • maxResultCount

    Especifica la cantidad máxima de resultados de lugares que se devolverán. Debe estar entre 1 y 20 (valor predeterminado), ambos incluidos.

  • 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 (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

    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 regionCode, se omite el código de país de formattedAddress. Este parámetro no afecta a adrFormatAddress, que siempre incluye el nombre del país, ni a shortFormattedAddress, que nunca lo incluye.

    La mayoría de los códigos de 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 "El Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la legislación aplicable.

Ejemplos de Nearby Search (nuevo)

Cómo encontrar lugares de un tipo

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para los nombres visibles de todos los restaurantes en 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 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 devolver 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"
      }
    },
...
}

Encuentra lugares de varios tipos

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para los nombres visibles de todas las tiendas de conveniencia y licorerías en 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 adecuado entre los resultados.

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para todos los lugares de tipo "school", excluyendo todos los lugares de tipo "primary_school" y clasificando 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 cercanos a un área y ordenarlos 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 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

Obtén descriptores de direcciones

Los descriptores de dirección proporcionan información relacional sobre la ubicación de un lugar, incluidos los puntos de referencia cercanos y las áreas que lo contienen.

En el siguiente ejemplo, se muestra una solicitud de Nearby Search (nuevo) para lugares cercanos a un centro comercial en San José. En este ejemplo, incluyes addressDescriptors en la máscara de campo:

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

La respuesta incluye el lugar especificado en la solicitud, una lista de puntos de referencia cercanos y su distancia desde el lugar, y una lista de áreas y su relación de contención con el lugar:

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
              "displayName": {
                "text": "Nordstrom",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "department_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "straightLineDistanceMeters": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "areas": [
            {
              "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
              "displayName": {
                "text": "Westfield Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
              "displayName": {
                "text": "Valley Fair",
                "languageCode": "en"
              },
              "containment": "WITHIN"
            },
            {
              "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
              "displayName": {
                "text": "Central San Jose",
                "languageCode": "en"
              },
              "containment": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Pruébalo

El Explorador de APIs te permite realizar solicitudes de ejemplo para que te familiarices con la API y sus opciones.

  1. Selecciona el ícono de la API api en el lado derecho de la página.

  2. De manera opcional, edita los parámetros de la solicitud.

  3. Selecciona el botón Ejecutar. En el diálogo, elige la cuenta que deseas usar para realizar la solicitud.

  4. En el panel del Explorador de APIs, selecciona el ícono de pantalla completa fullscreen para expandir la ventana del Explorador de APIs.