Solicitud y respuesta de Street View

Una solicitud de imagen de Street View es una URL HTTP en este formato:

https://maps.googleapis.com/maps/api/streetview?parameters

La imagen se especifica usando parámetros de solicitud. Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&). A continuación, se proporciona una lista de los parámetros permitidos y sus posibles valores.

Parámetros obligatorios

Realiza una de las siguientes acciones:

  • location puede ser una cadena de texto (como Chagrin Falls, OH) o un par de coordenadas de latitud y longitud (40.457375,-80.009353), y debe estar codificada como una URL. Por lo tanto, convierte direcciones como “Ayuntamiento, Nueva York, NY” en “Ciudad+Hall,New+York,NY” antes de enviar la solicitud. La API de Street View Static se ajusta a la foto panorámica más cercana a la ubicación. Cuando proporcionas una cadena de texto de dirección, la API puede usar una ubicación de cámara diferente para mostrar mejor la ubicación especificada. Cuando proporcionas las coordenadas de latitud y longitud, la API busca un radio de 50 metros para encontrar la fotografía más cercana a la ubicación. Debido a que las imágenes de Street View se actualizan de manera periódica, y a que las fotografías pueden tomarse desde posiciones ligeramente diferentes en cada ocasión, es posible que el objeto location se adapte a una panorámica diferente cuando se actualicen las imágenes.

o:

  • pano es un ID de panorámica específico. El ID de las panorámicas puede cambiar con el tiempo, por lo que te recomendamos que no lo conserves. En su lugar, guarda la dirección de la ubicación o las coordenadas de latitud y longitud para poder actualizar el ID de la panorámica. Para obtener más información, consulta Cómo actualizar los IDs de panorámica borrados.

Y también:

  • size especifica el tamaño de salida de la imagen en píxeles. El tamaño se especifica como {width}x{height}. Por ejemplo, size=600x400 muestra una imagen de 600 píxeles de ancho y 400 de alto.
  • key te permite supervisar el uso de la API que hace tu aplicación en la consola de Google Cloud y garantiza que Google pueda comunicarse contigo acerca de tu aplicación, si es necesario. Para obtener más información, consulta Obtén una clave y firma.

Actualizar IDs de panorámica borrados

Si intentas recuperar un ID de panorámica y obtienes ZERO_RESULTS o ningún valor, este se borrará y deberá actualizarse.

  1. Guarda la dirección de la ubicación o las coordenadas de latitud y longitud que usaste para obtener un ID de panorámica para poder actualizar la información cuando sea necesario.

  2. Cuando detectes que el ID de una panorámica cambió, usa la dirección de la ubicación original o las coordenadas de latitud y longitud para volver a buscar las panorámicas más cercanas a esa ubicación y obtener un ID de panorámica nuevo.

Parámetros opcionales

  • signature (recomendada) es una firma digital que se usa para verificar que los sitios que generan solicitudes con tu clave de API estén autorizados para hacerlo. Es posible que fallen las solicitudes que no incluyan una firma digital. Para obtener más información, consulta Obtén una clave y firma.

    Nota: Para los antiguos clientes del plan Premium de Google Maps Platform, se requiere la firma digital. Obtén más información sobre los parámetros de autenticación para clientes del plan Premium.

  • heading indica la orientación de la cámara según la brújula. Los valores aceptados van de 0 a 360 (ambos valores indican el norte, 90 indica el este y 180 el sur). Si no se especifica una orientación, se calcula un valor que dirige la cámara hacia el location especificado desde el punto en el que se tomó la fotografía más cercana.
  • fov (el valor predeterminado es 90) determina el campo visual horizontal de la imagen expresada en grados, con un valor máximo permitido de 120. Cuando se trabaja con un viewport de tamaño fijo, al igual que con una imagen de Street View de un tamaño establecido, el campo visual en esencia representa el zoom, y los números más pequeños indican un mayor nivel de zoom.


    Captura de pantalla de un campo visual de amplia gama que muestra el techo, las paredes, el piso y la ventana de un tanque dentro de un acuario. Captura de pantalla de un campo visual en primer plano que muestra en detalle una foto de Street View dentro de un acuario.
    (Izquierda: fov=120; derecha: fov=20)

  • pitch (valor predeterminado 0) especifica el ángulo ascendente o descendente de la cámara en relación con el vehículo de Street View. Generalmente, pero no siempre, es plano horizontal. Los valores positivos apuntan a la cámara en un ángulo ascendente (donde 90 grados indica el extremo superior); los valores negativos orientan la cámara en un ángulo hacia abajo (-90 indica el extremo inferior).
  • radius (el valor predeterminado es 50) establece un radio, especificado en metros, en el que se debe buscar una panorámica, según la latitud y longitud determinadas. Los valores válidos son números enteros no negativos.
  • return_error_code indica si la API debe mostrar un código de error cuando no se encuentra ninguna imagen (404 NOT FOUND) o en respuesta a una solicitud no válida (400 BAD REQUEST). Los valores válidos son true y false. Si se configura en true, se muestra un mensaje de error en lugar de la imagen gris genérica. Esto elimina la necesidad de realizar una llamada separada para verificar la disponibilidad de la imagen.
  • source (la opción predeterminada es default) limita las búsquedas de Street View a las fuentes seleccionadas. Los valores válidos son los siguientes:
    • default usa las fuentes predeterminadas de Street View; las búsquedas no se limitan a fuentes específicas.
    • outdoor limita las búsquedas a las colecciones al aire libre. Estas colecciones no se incluyen en los resultados de la búsqueda. Ten en cuenta que es posible que no existan panorámicas al aire libre para la ubicación especificada. Además, ten en cuenta que la búsqueda solo muestra panorámicas cuando es posible determinar si se encuentran en interiores o al aire libre. Por ejemplo, no se muestran PhotoSpheres porque se desconoce si se encuentran en interiores o al aire libre.

Esta es una solicitud de ejemplo.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Captura de pantalla de una foto de un mirador a nivel de la calle que muestra las vías ferroviarias electrificadas.

No hay imágenes disponibles

En el caso de las ubicaciones donde las imágenes de Street View no están disponibles, la API de Street View Static muestra una imagen genérica gris con el texto "Lo sentimos, no tenemos imágenes aquí", como se muestra en este ejemplo:

Captura de pantalla de la imagen genérica que se muestra cuando no hay imágenes disponibles para la ubicación especificada. El fondo es marrón claro y muestra el texto "Lo sentimos, no tenemos imágenes aquí".
Figura: Se muestra una imagen genérica cuando no hay imágenes disponibles para la ubicación especificada.

Mostrar solo imágenes válidas

Para evitar mostrar la imagen genérica y asegurarte de que tu página web solo muestre imágenes válidas de la API de Street View Static, sigue estas sugerencias:

  • Establece el parámetro return_error_code en true. Esto hace que la API de Street View Static muestre un error 404 NOT FOUND (NO ENCONTRADO) en lugar de la imagen gris genérica si no hay una imagen disponible para la ubicación especificada.
  • Solicita metadatos de imagen de Street View para determinar si hay imágenes disponibles para la ubicación especificada antes de enviar una solicitud.