Prácticas recomendadas para usar la API de Street View Static

Las APIs web estáticas de Google Maps Platform, una colección de interfaces HTTP, generan imágenes para incorporarlas directamente en tu página web.

Los servicios web de Google Maps Platform son una colección de interfaces HTTP que proporcionan datos geográficos para tus aplicaciones de mapas.

En esta guía, se describen algunas prácticas comunes útiles para configurar tus solicitudes de imágenes y servicios web, y para procesar las respuestas de los servicios. Para obtener más información sobre la API de Street View Static, consulta la guía para desarrolladores.

La API de Street View Static funciona como una API web estática, mientras que el servicio de metadatos funciona como un servicio web. Para obtener más información sobre el servicio de metadatos, consulta Metadatos de imágenes de Street View.

¿Qué es una API web estática?

Las APIs web estáticas de Google Maps Platform te permiten incorporar una imagen de Google Maps en tu página web sin necesidad de JavaScript ni de cargar páginas dinámicas. Las APIs web estáticas crean una imagen basada en los parámetros de URL que se envían con una solicitud HTTPS estándar.

Una solicitud típica a la API de Street View Static tiene el siguiente formato:

  https://www.googleapis.com/streetview/z/x/y?parameters

¿Qué es un servicio web?

Los servicios web de Google Maps Platform son una interfaz para solicitar datos de la API de Maps a servicios externos y usar los datos en tus aplicaciones de Maps. Estos servicios están diseñados para usarse junto con un mapa, de acuerdo con las Restricciones de licencia de las Condiciones del Servicio de Google Maps Platform.

Los servicios web de las APIs de Maps usan solicitudes HTTP o HTTPS a URLs específicas, y pasan parámetros de URL o datos POST en formato JSON como argumentos a los servicios. En general, estos servicios devuelven datos en el cuerpo de la respuesta como JSON para que tu aplicación los analice o procese.

Una solicitud de metadatos de la API de Street View Static tiene el siguiente formato:

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

Acceso a SSL y TLS

Se requiere HTTPS para todas las solicitudes a Google Maps Platform que usen claves de API o contengan datos del usuario. Es posible que se rechacen las solicitudes realizadas a través de HTTP que contengan datos sensibles.

Cómo crear una URL válida

Tal vez creas que una dirección URL "válida" es evidente, pero no siempre es así. Una URL que se ingresa en una barra de direcciones en un navegador, por ejemplo, puede contener caracteres especiales (p. ej., "上海+中國"), y el navegador debe traducir internamente esos caracteres a una codificación diferente antes de la transmisión. Con el mismo token, cualquier código que genere o acepte entradas en UTF-8 podría procesar las URLs con caracteres UTF-8 como "válidas", pero también necesitaría traducir esos caracteres antes de enviarlos a un servidor web. Este proceso se llama codificación de URLs o codificación por ciento.

Caracteres especiales

Debemos traducir los caracteres especiales porque todas las URLs deben cumplir con los requisitos de sintaxis que se indican en la especificación Identificador de recursos uniformes (URI). En efecto, esto significa que las URLs deben contener solo un subconjunto especial de caracteres ASCII: los símbolos alfanuméricos que ya conocemos y algunos caracteres reservados para usar como caracteres de control en las URLs, los cuales se resumen en la siguiente tabla:

Al crear una URL válida, debes asegurarte de que contenga solo los caracteres que se muestran en la tabla. Adaptar una dirección URL para usar este conjunto de caracteres generalmente provoca dos problemas, de omisión y de sustitución:

• Quizá quieras usar caracteres que no se encuentran dentro del conjunto anterior. Por ejemplo, los caracteres de otros idiomas, como 上海+中國, deben codificarse con los caracteres que se indican arriba. Por convención popular, los espacios (que no se permiten en las URLs) suelen representarse también con el carácter de signo más '+'.
• Hay caracteres dentro del conjunto anterior que son caracteres reservados, pero se deben usar literalmente. Por ejemplo, ? se usa en las URLs para indicar el comienzo de la cadena de consulta; si deseas utilizar la cadena "? and the Mysterions", debes codificar el carácter '?'.

La codificación de caracteres para URLs usa un carácter '%' y un valor hexadecimal de dos caracteres correspondiente a su carácter en UTF-8. Por ejemplo, 上海+中國 en UTF-8 se codificaría como %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B para usarse en URLs. La cadena ? and the Mysterians se codificaría como %3F+and+the+Mysterians o %3F%20and%20the%20Mysterians para usarse en URLs.

Caracteres comunes que necesitan codificación

A continuación se indican algunos de los caracteres que se deben codificar:

Convertir una dirección URL que recibes a través de la entrada de un usuario puede ser engañoso. Por ejemplo, un usuario puede ingresar la dirección "5th&Main St.". Generalmente, deberías crear tu URL a partir de sus partes y tratar las entradas del usuario como caracteres literales.

Además, las URLs tienen una limitación de 16,384 caracteres en todos los servicios web y las APIs web estáticas de Google Maps Platform. Para la mayoría de los servicios, este límite de caracteres rara vez se alcanza. No obstante, ten en cuenta que algunos servicios tienen varios parámetros que podrían generar URLs extensas.

Uso adecuado de las APIs de Google

Los clientes de API mal diseñados pueden generar cargas pesadas en Internet y en los servidores. En esta sección, se incluyen prácticas recomendadas para los clientes de la API. Seguir estas prácticas recomendadas puede ayudarte a evitar que se bloquee tu aplicación por abuso involuntario de las APIs.

Retirada exponencial

En casos excepcionales, es posible que algo salga mal con tu solicitud. Podrías recibir un código de respuesta HTTP 4xx o 5xx, o la conexión TCP podría fallar en algún punto entre tu cliente y el servidor de Google. A menudo, vale la pena volver a intentar la solicitud, ya que la solicitud de seguimiento podría tener éxito cuando la original falló. Sin embargo, es importante no realizar solicitudes repetidamente a los servidores de Google. Este comportamiento de bucle puede sobrecargar la red entre tu cliente y Google, lo que causa problemas para muchas partes.

Un mejor enfoque consiste en realizar nuevos intentos con demoras más prolongadas entre uno y otro. Por lo general, el retraso aumenta en un factor multiplicativo con cada intento, un enfoque conocido como retirada exponencial.

Por ejemplo, considera una aplicación que realiza esta solicitud a la API de Time Zone:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

En el siguiente ejemplo de Python, se muestra cómo realizar la solicitud con una espera exponencial:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined in the following code isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Asegúrate de que no haya código de reintento más arriba en la cadena de llamadas de la aplicación que genere solicitudes repetidas en rápida sucesión.

Solicitudes sincronizadas

Una gran cantidad de solicitudes sincronizadas a las APIs de Google pueden parecer un ataque de denegación de servicio distribuido (DDoS) a la infraestructura de Google y tratarse como tal. Para evitar este problema, asegúrate de que las solicitudes a la API no estén sincronizadas entre los clientes.

Por ejemplo, considera una aplicación que muestra la hora en la zona horaria actual. Es probable que esta aplicación configure una alarma en el sistema operativo del cliente para activarlo al comienzo del minuto, de modo que se pueda actualizar la hora que se muestra. No realices ninguna llamada a la API en la aplicación como parte del procesamiento asociado a esa alarma.

Realizar llamadas a la API en respuesta a una alarma fija es una práctica inadecuada porque hace que las llamadas a la API se sincronicen con el inicio del minuto, incluso entre diferentes dispositivos, en lugar de distribuirse de manera uniforme a lo largo del tiempo. Una aplicación mal diseñada que hace esto genera un aumento repentino del tráfico 60 veces superior a los niveles normales al comienzo de cada minuto.

En su lugar, puedes diseñar la aplicación para que tenga una segunda alarma configurada para una hora elegida de forma aleatoria. Cuando suena esta segunda alarma, la aplicación llama a las APIs que necesita y almacena los resultados. Cuando la aplicación actualiza su pantalla al comienzo del minuto, usa los resultados almacenados anteriormente en lugar de volver a llamar a la API. Con este enfoque, las llamadas a la API se distribuyen de manera uniforme a lo largo del tiempo. Además, las llamadas a la API no retrasan la renderización cuando se actualiza la pantalla.

Además del inicio del minuto, no segmentes tus anuncios para que se publiquen en otros momentos de sincronización comunes, como el inicio de una hora y el inicio de cada día a la medianoche.

Procesa respuestas

Dado que no se garantiza el formato exacto de las respuestas individuales a una solicitud de servicio web (es posible que falten algunos elementos o que se encuentren en varias ubicaciones), no supongas que el formato que se devuelve para una respuesta determinada es el mismo para diferentes búsquedas. En su lugar, procesa la respuesta y selecciona los valores adecuados con expresiones.

En esta sección, se explica cómo extraer estos valores de forma dinámica de las respuestas de los servicios web.

Los servicios web de Google Maps proporcionan respuestas comprensibles, pero no fáciles de usar. Cuando realizas una consulta, en lugar de mostrar un conjunto de datos, probablemente quieras extraer algunos valores específicos. En general, analiza las respuestas del servicio web y extrae solo los valores que te interesan.

El esquema de análisis que uses dependerá de si devuelves el resultado en JSON. Las respuestas JSON, que ya están en forma de objetos JavaScript, se pueden procesar dentro de JavaScript en el cliente.