Place Photos (nuevo)

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

Introducción

El servicio Place Photos (nuevo) es una API de solo lectura que te permite agregar contenido fotográfico de alta calidad a tu aplicación. Place Photos (nuevo) te brinda acceso a los millones de fotos almacenadas en la base de datos de Places.

Cuando obtienes información sobre lugares con una solicitud de Place Details (nuevo), Nearby Search (nuevo) o Text Search (nuevo), también puedes solicitar recursos de fotos para el contenido fotográfico pertinente. Con Place Photos (nuevo), puedes acceder a las fotos de referencia y cambiar el tamaño de la imagen al más adecuado para tu aplicación.

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

Solicitudes de Place Photos (nuevo)

Una solicitud de Place Photos (nuevo) es una solicitud HTTP GET a una URL con el siguiente formato: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Se requieren los siguientes parámetros:

  • NAME contiene el nombre del recurso de la foto.
  • API_KEY contiene la clave de API.
  • PARAMETERS contiene el parámetro maxHeightPx, el parámetro maxWidthPx o ambos.

A continuación, se describe la lista completa de parámetros obligatorios y opcionales.

Parámetros obligatorios

Nombre de la foto

Es un identificador de cadena que identifica de forma única una foto. Los nombres de las fotos se devuelven desde una solicitud de Place Details (nuevo), Nearby Search (nuevo) o Text Search (nuevo) en la propiedad name de cada elemento del array photos[].

Para ver un ejemplo, consulta Cómo obtener el nombre de una foto.

maxHeightPx y maxWidthPx

Especifica la altura y el ancho máximos previstos de la imagen en píxeles. Si la imagen es más pequeña que los valores especificados, se devolverá la imagen original. Si la imagen es más grande en cualquiera de las dimensiones, se ajustará su escala para que coincida con la más pequeña de las dos dimensiones, restringida a su relación de aspecto original. Las propiedades maxheight y maxwidth aceptan un número entero entre 1 y 4800.

Debes especificar maxHeightPx o maxWidthPx, o ambos.

Parámetros opcionales

skipHttpRedirect

Si es false (predeterminado), realiza un redireccionamiento HTTP a la imagen para devolverla. Si es true, omite el redireccionamiento y devuelve una respuesta JSON que contenga los detalles de la imagen. Por ejemplo:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

Esta opción se ignora para las solicitudes que no son de HTTP.

Obtener el nombre de una foto

Todas las solicitudes a Place Photos (nuevo) deben incluir un nombre de recurso de foto, que se devuelve en la respuesta a una solicitud de Nearby Search (nuevo), Text Search (nuevo) o Place Details (nuevo). La respuesta a estas solicitudes contiene un array photos[] si el lugar tiene contenido fotográfico relacionado.

Cada elemento de photo[] contiene los siguientes campos:

  • name: Es una cadena que contiene el nombre del recurso de la foto cuando realizas una solicitud de Photo. Esta cadena tiene el siguiente formato:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx: Es la altura máxima de la imagen en píxeles.
  • widthPx: Es el ancho máximo de la imagen en píxeles.
  • authorAttributions[]: Cualquier atribución requerida. Este campo siempre está presente, pero puede estar vacío.

Las fotos que muestra Place Photos (nuevo) provienen de una variedad de fuentes, incluidas las fotos proporcionadas por los propietarios de las empresas y los aportes de los usuarios. En la mayoría de los casos, estas fotos se pueden utilizar sin atribución; de lo contrario, incluirán la atribución requerida como parte de la imagen. Sin embargo, si el elemento photo que se muestra incluye un valor en el campo authorAttributions, deberás incluir la atribución adicional en tu aplicación en cualquier lugar donde muestres la imagen.

En el siguiente ejemplo, se muestra una solicitud de Place Details (nuevo) que incluye photos en la máscara de campo para que la respuesta incluya el array photos[]:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 A continuación, se muestra un ejemplo de un array photos[] en la respuesta. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

Solicita una foto de un lugar

La siguiente solicitud de ejemplo devuelve una imagen con su recurso name y cambia su tamaño para que tenga un máximo de 400 píxeles de alto y ancho:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

La respuesta de una solicitud exitosa de Place Photos (nuevo) es una imagen.

Códigos de error

Las solicitudes de Place Photos (nuevo) pueden devolver los siguientes códigos de error.

Se superó la cuota (403)

Si tu solicitud supera la cuota disponible, el servidor devuelve un estado HTTP 403 y muestra la siguiente imagen para indicar que se superó la cuota:

Notificación de que se superó la cuota

Solicitud no válida (404)

Si el servidor no puede comprender tu solicitud, devuelve el estado HTTP 400, que indica que la solicitud no es válida. Estos son los motivos más comunes por los que se rechaza una solicitud:

  • El nombre de la foto enviada no se especificó correctamente.
  • La solicitud no incluyó el parámetro maxHeightPx ni el parámetro maxWidthPx.
  • El valor del parámetro maxHeightPx o maxWidthtPx se estableció en null.
  • Venció el name. Si name vence, realiza una solicitud a Place Details (nuevo), Nearby Search (nuevo) o Text Search (nuevo) para obtener un nuevo name.

Demasiadas solicitudes (429)

Google recomienda cargar las fotos según demanda. Si intentas mostrar todas las imágenes de un lugar a la vez, es posible que el servidor muestre un estado HTTP 429 que indique que se están cargando demasiadas fotos al mismo tiempo. Si recibes este mensaje de error, comunícate con el equipo de asistencia y solicita un aumento de la cuota.

Pruébalo

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

Para hacer una solicitud, sigue estos pasos:

  1. Selecciona el ícono de la API en el lado derecho de la página.
  2. Establece el parámetro name en lo siguiente: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Establece skipHttpRedirect en true para que la solicitud devuelva una respuesta JSON. De forma predeterminada, la solicitud devuelve la imagen, que no puede mostrar el Explorador de APIs.
  4. Selecciona el botón Ejecutar. En el cuadro de diálogo, elige la cuenta que deseas usar para hacer la solicitud.

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