Mosaicos de Street View

Los mosaicos de Street View son similares a los mosaicos en 2D, excepto que contienen imágenes panorámicas tomadas a nivel de la calle. Con Street View, puedes explorar puntos de referencia en todo el mundo, observar maravillas naturales y recorrer el interior de lugares como museos, estadios, restaurantes y pequeñas empresas. Este extremo de API te brinda acceso a lo siguiente:

• Mosaicos de Street View de Google Maps
• Metadatos de Street View
• Miniaturas de Street View

Puedes unir mosaicos de imágenes tomados a nivel de la calle para crear un efecto panorámico realista. Además, puedes consultar hasta 100 IDs de panoramas para un conjunto de ubicaciones (como una ruta) y obtener metadatos más detallados sobre la posición de la cámara.

Se requiere un visor para unir los mosaicos de Street View. Por ejemplo, el visor de panorámicas personalizadas de Street View.

Sugerencia: Para obtener más información, consulta la API de Street View Static y el Servicio de Street View.

Una vez que tengas una clave de API, podrás acceder a las imágenes de Street View siguiendo estos pasos.

1. Obtén un token de sesión. Asegúrate de establecer el valor de mapType en streetview.

2. Usa el token de sesión para obtener el identificador de panorama (panoId) de una o más ubicaciones geográficas.

3. Usa los identificadores de panorama de la respuesta de la búsqueda de panoId para obtener lo siguiente:

   1. Metadatos de Street View. También puedes obtener metadatos de Street View pasando un conjunto de coordenadas y un radio.

   2. Miniaturas de Street View:

   3. Mosaicos de Street View.

Nota: Debes mostrar la información de derechos de autor en cada panorama de Street View. La cadena que se mostrará puede variar de un panorama a otro. Para obtener la información de derechos de autor, debes solicitar los metadatos de Street View y, luego, puedes consultar el campo copyright de la respuesta.

Métodos de Street View

Para acceder a las imágenes y los metadatos de Street View, llama a uno de los siguientes cuatro métodos.

Método	Descripción
https://tile.googleapis.com/v1/streetview/tiles	Muestra las tarjetas individuales de Street View. Puedes recuperar mosaicos de Street View en seis niveles de zoom: desde 512 píxeles hasta 13,312 píxeles.
https://tile.googleapis.com/v1/streetview/panoIds	Te permite buscar hasta 100 ubicaciones de forma masiva. Muestra los IDs de panorama para todas las ubicaciones con imágenes.
https://tile.googleapis.com/v1/streetview/thumbnail	Muestra una imagen JPEG en miniatura de una escena de Street View. Te permite proporcionar un encabezado, una inclinación, dimensiones y un campo de visión. Las dimensiones mínimas son de 16 × 16 píxeles. Las dimensiones máximas son de 250 x 600 píxeles.
https://tile.googleapis.com/v1/streetview/metadata	Proporciona información detallada sobre el panorama especificado. Los detalles incluyen la dirección relacionada y los vínculos a panoramas adyacentes.

Búsqueda de panoIds de Street View

Para encontrar el identificador de panorama de una o más ubicaciones geográficas, pasa sus coordenadas (lat, lng) al método panoIds. El cuerpo de la solicitud es un objeto JSON que contiene un array locations y, de manera opcional, un radius, como se muestra en el siguiente ejemplo de código JSON.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

El array locations debe contener al menos un conjunto de valores de coordenadas, pero puedes incluir más, hasta un máximo de 100.

radius

El valor radius (medido en metros) define el radio del círculo alrededor de la ubicación determinada en la que se deben buscar panorámicas. El valor predeterminado es de 50 metros.

Respuesta de PanoId

La API de Map Tiles intenta encontrar el panorama más cercano a cada ubicación y, luego, muestra sus IDs de panorama. Una solicitud panoIds correcta muestra un objeto JSON que contiene un array panoIds. El array contiene una lista de IDs de panorama, en el orden en que los solicitaste. Si la API de Map Tiles no puede encontrar ningún panorama para las ubicaciones que solicitaste, se muestra una cadena vacía en esa ubicación de la matriz. Para ver un ejemplo, consulta el siguiente código JSON.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Puedes usar panoIds para lo siguiente:

• Cómo solicitar metadatos de Street View
• Cómo solicitar miniaturas de Street View
• Cómo solicitar mosaicos de Street View

Nota: Los IDs de panorama son transitorios. Es decir, no duran mucho tiempo. Como regla general, no confíes en que los IDs de panorama sean válidos durante más de una sesión de usuario.

Metadatos de Street View

Las solicitudes de metadatos de Street View recuperan información sobre los panoramas. Una solicitud de metadatos de Street View es una solicitud HTTPS GET. Puedes recuperar información sobre los panoramas de una de las siguientes maneras:

• Si pasas un pano_id, la API de Map Tiles muestra los metadatos de ese panorama.

• Sin embargo, si pasas un lat y un lng, la API de Map Tiles muestra los metadatos del panorama más cercano dentro del radio de búsqueda determinado.

Pasa un conjunto de coordenadas y un radio

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Dado que los IDs de panorama son transitorios, te recomendamos que pases un conjunto de coordenadas y un valor radius en tu solicitud inicial de metadatos de Street View. Como ejemplo, consulta el siguiente fragmento de código.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Pasa el panoId de una imagen de Street View

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Respuesta de metadatos

El siguiente código JSON es un ejemplo de una respuesta de metadatos típica.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

La siguiente lista contiene definiciones de los campos del cuerpo de la respuesta.

panoId

El ID único de este panorama. No debes confiar en que los IDs de panorama sean válidos durante más de una única sesión de usuario.

lat, lng

Las coordenadas (latitud y longitud) del panorama. Estos valores pueden ser diferentes de las coordenadas que pasaste en la solicitud porque la ubicación se ajusta al panorama más cercano.

imageHeight, imageWidth

Son las dimensiones de la imagen panorámica editada.

tileHeight, tileWidth

Son las dimensiones de una sola tarjeta de panorama.

heading

Es la orientación de la brújula, medida en grados en el sentido de las manecillas del reloj a partir del norte. Los encabezados se muestran dentro del rango [0,360], y 0 representa el norte.

tilt

La inclinación del panorama, medida en grados desde el polo sur del panorama hasta el horizonte. Los valores que se muestran están dentro del rango [0, 180]. Un valor de 90 grados indica que el horizonte ya está alineado en el ecuador del panorama.

roll

La rotación en el sentido de las manecillas del reloj alrededor de la línea de visión que se aplicó al panorama para nivelar el horizonte. Los valores que se muestran están dentro del rango [0, 360].

imageryType

Indica el tipo de imagen. Los valores válidos son indoor y outdoor.

date

Es la fecha en la que se tomó la imagen. No todas las imágenes tienen datos de fecha. Sin embargo, cuando está disponible, este campo contiene una combinación del año (AAAA) y el mes (MM). Por ejemplo, 2023-05 o 2024.

copyright

Es el texto de los derechos de autor que debes mostrar como atribución junto con la imagen de Street View.

reportProblemLink

Es un hipervínculo que los usuarios pueden usar para informar problemas con esta tarjeta de Street View. Debes mostrar este hipervínculo en la esquina inferior derecha de la imagen, y debe incluir un texto que diga algo como "Informar un problema con esta imagen".

addressComponent

Un Geocode estructurado que contiene detalles sobre la dirección del panorama. Para obtener más información, consulta Solicitudes y respuestas de geocodificación en la documentación de la API de Geocoding.

links

Es una lista de los IDs de panorama que se vinculan con este. También contiene el encabezado en el que se encuentra el vínculo. Por ejemplo, si el encabezado es de 180°, el panorama vinculado se orienta hacia el sur del panorama actual. Ten en cuenta que, debido a la naturaleza transitoria de los IDs de panorama, no debes confiar en estos durante más de una única sesión de usuario.

Miniaturas de Street View

Puedes solicitar imágenes de Street View en formato thumbnail. Las miniaturas son imágenes sin mosaico, con un tamaño, un encabezado, una inclinación y un campo visual definidos por el usuario. Las imágenes en miniatura tienen una resolución inferior a la de los mosaicos y el tamaño de archivo de estas es más pequeño. Para realizar una solicitud de miniatura, envía una solicitud GET al extremo thumbnail, como se muestra en el siguiente prototipo de código.

Nota: Los valores de campo encerrados entre corchetes en este ejemplo muestran rangos. Por ejemplo, height puede variar de 16 a 250 píxeles.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

Considera el siguiente ejemplo de código, que descarga una miniatura de imágenes de Street View tomadas en Whistler, Canadá.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

Parámetros obligatorios

panoId

El ID único de la miniatura que deseas. Puedes obtener valores de ID de panorama del extremo panoIds o del extremo metadata, que aceptan coordenadas geográficas y muestran el panoId correspondiente.

session

Un token de sesión válido.

key

Tu clave de API.

Parámetros opcionales

height

Especifica la altura de la miniatura en píxeles, que puede variar de 16 a 250. Si no especificas una altura, esta se establecerá de forma predeterminada en el valor máximo permitido de 250 píxeles. Si especificas un valor fuera del rango, la miniatura se ajusta al valor válido más cercano.

width

Especifica el ancho de la miniatura en píxeles, de 16 a 600. Si no especificas un ancho, el valor predeterminado será de 600 píxeles. Si especificas un valor fuera del rango, la miniatura se ajusta al valor válido más cercano.

pitch

Especifica el ángulo de la cámara a lo largo del eje vertical. Los valores válidos están entre -90 y 90 inclusive. El valor predeterminado es 0.

yaw

Especifica la dirección de la cámara en el eje horizontal. Los valores válidos están entre -360 y 360 inclusive. El valor predeterminado es 0.

fov

Especifica el campo de visión horizontal, expresado en grados, con un valor máximo de 120. Cuando se manipula un viewport de tamaño fijo, al igual que con una imagen de Street View de un tamaño determinado, el campo de visión representa el zoom, en el que los valores más bajos especifican un nivel de zoom más alto. El valor predeterminado es 90.

Mosaicos de imágenes de Street View

Una vez que tengas un panoId, puedes solicitar un mosaico de imagen de Street View. Las solicitudes de mosaicos son solicitudes HTTPS GET. Considera el siguiente ejemplo:

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

En este ejemplo de código, z es el nivel de zoom, y x y y son las coordenadas de mosaico de la tarjeta de Street View que deseas. Los niveles de zoom de los panoramas de Street View deben estar dentro del rango [0,5], con 0 representando el campo visual más amplio.

Nivel de zoom	Campo visual aproximado
0	360°
1	180°
2	90°
3	45°
4	22.5°
5	11.25°

Nota: Las imágenes de Street View provienen de dos fuentes: Google (imágenes no públicas controladas por el desarrollador) y el público (CGU o contenido público generado por usuarios). Ten en cuenta que no hay manera de usar solo una fuente de imágenes de Street View en lugar de la otra. Obtén más información sobre nuestra Política de privacidad de las imágenes de Street View.

Respuestas de los mosaicos de Street View

Una solicitud de mosaico de Street View exitosa muestra una imagen con el formato y el tamaño que especificaste en tu respuesta createSession.

En el nivel de zoom cero, se modifica el panorama completo en un mosaico de dimensiones tileWidth por tileHeight. Debido a que los panoramas son más grandes en la dimensión x, el mosaico tendrá un espacio vacío en la dimensión y:

En el nivel de zoom cinco, se usa el panorama de tamaño completo y se divide en mosaicos.

Sugerencia: Para calcular los valores máximos de x y y, divide imageHeight y imageWidth por tileHeight y tileWidth.

Información sobre derechos de autor

Debes mostrar la información de derechos de autor en cada panorama de Street View. La cadena que se mostrará puede variar entre los panoramas. Para obtener la información de derechos de autor, debes solicitar los metadatos de Street View y, luego, puedes consultar el campo copyright de la respuesta. Para obtener más información, consulta Atribuciones de datos.