Place Details (nuevo)

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

Introducción

Una vez que tengas un ID de lugar, puedes solicitar más detalles sobre un establecimiento o punto de interés en particular iniciando una solicitud de Place Details (nuevo). Una solicitud de Place Details (nuevo) devuelve información más completa sobre el lugar indicado, como su dirección completa, número de teléfono, calificación y opiniones de los usuarios.

Hay muchas formas de obtener un ID de lugar. Puedes usar:

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

Solicitudes de Place Details (nuevo)

Una solicitud de Place Details (nuevo) es una solicitud HTTP GET con el siguiente formato:

https://places.googleapis.com/v1/places/PLACE_ID

Pasa todos los parámetros como parámetros de URL o en encabezados como parte de la solicitud GET. Por ejemplo:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

O en un comando curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Respuestas de Place Details (nuevo)

Place Details (nuevo) devuelve un objeto JSON como respuesta. En la respuesta, figura lo siguiente:

  • La respuesta se representa con un objeto Place. El objeto Place contiene información detallada sobre el 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:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

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: displayName,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 Place Details Essentials IDs Only:

      attributions
      id
      name*
      photos

      * El campo name contiene el nombre de recurso del lugar con el siguiente formato: places/PLACE_ID. Para obtener el nombre del lugar en forma de texto, solicita el campo displayName en el SKU Pro.

    • Los siguientes campos activan el SKU de Place Details Essentials:

      addressComponents
      addressDescriptor*
      adrFormatAddress
      formattedAddress
      location
      plusCode
      postalAddress
      shortFormattedAddress
      types
      viewport

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

    • Los siguientes campos activan el SKU de Place Details Pro:

      accessibilityOptions
      businessStatus
      containingPlaces
      displayName
      googleMapsLinks
      googleMapsUri
      iconBackgroundColor
      iconMaskBaseUri
      primaryType
      primaryTypeDisplayName
      pureServiceAreaBusiness
      subDestinations
      utcOffsetMinutes

    • Los siguientes campos activan el SKU de Place Details Enterprise:

      currentOpeningHours
      currentSecondaryOpeningHours
      internationalPhoneNumber
      nationalPhoneNumber
      priceLevel
      priceRange
      rating
      regularOpeningHours
      regularSecondaryOpeningHours
      userRatingCount
      websiteUri

    • Los siguientes campos activan el SKU de Place Details Enterprise + Atmosphere:

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

      * Solo para Text Search y Nearby Search

  • placeId

    Es un identificador textual que identifica un lugar de forma única y que se devuelve desde una búsqueda de Text Search (nuevo) o Nearby Search (nuevo). Para obtener más información sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.

    La cadena places/PLACE_ID también se denomina nombre del recurso de lugar. En la respuesta de una solicitud de Place Details (nuevo), Nearby Search (nuevo) y Text Search (nuevo), esta cadena se incluye en el campo name de la respuesta. El ID de lugar independiente se encuentra en el campo id de la respuesta.

Parámetros opcionales

  • 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 legible para el usuario si es necesario, y observa 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 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.

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

  • sessionToken

    Los tokens de sesión son cadenas generadas por el usuario que hacen un seguimiento de las llamadas a Autocomplete (nuevo) como "sesiones". Autocomplete (nuevo) usa tokens de sesión para agrupar las fases de consulta y selección de lugares de una búsqueda con autocompletado del usuario en una sesión discreta para fines de facturación. Los tokens de sesión se pasan a las llamadas de Place Details (nuevo) que siguen a las llamadas de Autocomplete (nuevo). Para obtener más información, consulta Tokens de sesión.

Ejemplo de Place Details (nuevo)

En el siguiente ejemplo, se solicitan los detalles de un lugar por medio de placeId:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Ten en cuenta que el encabezado X-Goog-FieldMask especifica que la respuesta contiene los siguientes campos de datos: id,displayName. Luego, la respuesta tendrá el siguiente formato:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Agrega más tipos de datos a la máscara de campo para devolver información adicional. Por ejemplo, agrega formattedAddress,plusCode para incluir la dirección y el código Plus en la respuesta:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

La respuesta ahora tiene el siguiente formato:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

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 Place Details (nuevo) para una tienda departamental en un centro comercial de San José. En este ejemplo, incluyes addressDescriptors en la máscara de campo:

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

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:

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "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": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "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": "WITHIN"
        }
      ]
    }
  }

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.