Las API web estáticas de Google Maps Platform son un conjunto de interfaces HTTP para los servicios de Google que generan imágenes que puedes incorporar directamente en tu página web.
Los servicios web de Google Maps Platform son un conjunto de interfaces HTTP para los servicios de Google que proporcionan datos geográficos a tus aplicaciones de mapas.
En esta guía, se describen algunas prácticas comunes que son útiles para configurar las solicitudes de servicios web y las respuestas de servicio de imagen y procesamiento. Consulta la guía para desarrolladores a fin de obtener la documentación completa de la API de Street View Static.
La API de Street View Static se comporta como una API web estática, mientras que el servicio de metadatos se puede ver como un servicio web. Para obtener más información sobre el servicio de metadatos, consulta los metadatos de imágenes de Street View.¿Qué es una API web estática?
Las API web estáticas de Google Maps Platform te permiten incorporar una imagen de Google Maps en tu página web sin necesidad de usar JavaScript ni ninguna carga de página dinámica. Las API crean una imagen basada en parámetros de URL enviados a través de una solicitud HTTP estándar y te permiten mostrar el resultado en tu página web.Una solicitud típica de la API de Street View Static suele tener la siguiente forma:
https://maps.googleapis.com/maps/api/streetview?parameters
¿Qué es un servicio web?
Los servicios web de Google Maps Platform son una interfaz para solicitar datos de la API de Google Maps a servicios externos y usarlos dentro de tus aplicaciones de Maps. Estos servicios se diseñaron para usarse junto con un mapa, de acuerdo con las restricciones de licencia en las Condiciones del Servicio de Google Maps Platform.
Los servicios web de las API de Google Maps usan solicitudes HTTP(S) a URL específicas y pasan parámetros de URL o datos POST en formato JSON como argumentos a los servicios. Por lo general, estos servicios muestran datos en la solicitud HTTP(S) 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
Nota: Todas las aplicaciones de la API de Street View Static requieren autenticación. Obtén más información sobre las credenciales de autenticación.
Acceso SSL/TLS
HTTPS es obligatorio para todas las solicitudes de Google Maps Platform que usan claves de API o contienen datos del usuario. Es posible que se rechacen las solicitudes realizadas mediante HTTP que contengan datos sensibles.
Cómo crear una URL válida
Quizás pienses que una URL "válida" es evidente, pero no siempre es así. Una URL que se ingresa en una barra de direcciones de un navegador, por ejemplo, puede contener caracteres especiales (como "上海+中國"
); 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 URL 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 URL o codificación porciento.
Caracteres especiales
Necesitamos traducir los caracteres especiales porque todas las URL deben cumplir con la sintaxis que se indica en la especificación del identificador uniforme de recursos (URI). Esto significa que las URL solo deben contener un subconjunto especial de caracteres ASCII: los símbolos alfanuméricos conocidos y algunos caracteres reservados para usar como caracteres de control dentro de las URL. Dichos caracteres se resumen en la siguiente tabla:
Conjunto de | Caracteres | Uso de URL |
---|---|---|
Alfanuméricos | a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M M N N P P R S T U V W X Y Z 0 1 2 3 4 5 6 7 6 7 | Strings de texto, uso de esquemas (http ), puerto (8080 ), etcétera |
No reservados | - _ . ~ | Strings de texto |
Reservados | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Caracteres de control o strings de texto |
Cuando compiles una URL válida, debes asegurarte de que solo contenga los caracteres que se muestran en la tabla Resumen de caracteres válidos para URL. Adaptar una URL para usar este conjunto de caracteres generalmente provoca dos problemas, de omisión y sustitución:
- Es posible que quieras usar caracteres que no se encuentren dentro del conjunto anterior. Por ejemplo, los caracteres en otros idiomas, como
上海+中國
, se deben codificar mediante los caracteres anteriores. Por convención popular, los espacios (que no se permiten en las URL) suelen representarse con el carácter de signo más'+'
también. - Hay caracteres dentro del conjunto anterior que son reservados, pero se deben usar literalmente.
Por ejemplo,
?
se usa en las URL para indicar el comienzo de la cadena de consulta; si deseas usar la string "? and the Mysterions", debes codificar el carácter'?'
.
Todos los caracteres que utilicen la codificación de URL se codifican con un carácter '%'
y un valor hexadecimal de dos caracteres correspondiente a su carácter UTF-8. Por ejemplo, 上海+中國
en UTF-8 utilizaría la codificación de URL %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B
. A su vez, la string ? and the Mysterians
utilizaría las codificaciones de URL %3F+and+the+Mysterians
o %3F%20and%20the%20Mysterians
.
Caracteres comunes que necesitan codificación
A continuación, se indican algunos de los caracteres comunes que se deben codificar:
Carácter no seguro | Valor codificado |
---|---|
Barra espaciadora | %20 |
" | %22 |
< | %3C |
> | %3E |
# | %23 |
% | %25 |
| | %7C |
A veces, convertir una URL que recibes a través de la entrada de un usuario puede ser engañoso. Por ejemplo, un usuario puede ingresar una dirección como "5th&Main St.". Por lo general, deberías crear tu URL a partir de sus partes y tratar las entradas de los usuarios como caracteres literales.
Además, las URL tienen un límite de 8,192 caracteres para todos los servicios web de Google Maps Platform y las API web estáticas. Para la mayoría de los servicios, este límite de caracteres se alcanza con poca frecuencia. No obstante, ten en cuenta que algunos servicios tienen varios parámetros que podrían generar URL extensas.
Uso normal de las API de Google
Los clientes de API mal diseñados pueden colocar más carga de la necesaria en Internet y en los servidores de Google. En esta sección se explican algunas de las prácticas recomendadas para los clientes de las API. Seguir estas prácticas recomendadas puede ayudarte a evitar que se bloquee tu aplicación por abuso involuntario de las API.
Interrupción exponencial
En raras ocasiones, puede producirse un error en la entrega de tu solicitud; es posible que recibas un código de respuesta HTTP 4XX o 5XX, o que la conexión TCP simplemente falle en algún lugar entre tu cliente y el servidor de Google. A menudo, vale la pena reintentar la solicitud, ya que la solicitud de seguimiento puede tener éxito cuando falla la original. Sin embargo, es importante no repetir varias veces las solicitudes a los servidores de Google. Este comportamiento repetitivo puede sobrecargar la red entre tu cliente y Google, lo que puede causar 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 por un factor multiplicativo con cada intento, un enfoque conocido como retirada exponencial.
Por ejemplo, considera una aplicación que desea realizar esta solicitud a la API de Time Zone:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
En el siguiente ejemplo de Python se muestra la manera de realizar la solicitud con interrupción exponencial:
import json import time import urllib.error import urllib.parse import urllib.request # The maps_key defined below 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 we didn't get an IOError then parse the result. result = json.load(response) if result["status"] == "OK": return result["timeZoneId"] elif result["status"] != "UNKNOWN_ERROR": # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or # ZERO_RESULTS. There is no point retrying 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 each time we retry. if __name__ == "__main__": tz = timezone(39.6034810, -119.6822510, 1331161200) print(f"Timezone: {tz}")
También debes tener cuidado de que no haya un código de reintento más alto en la cadena de llamadas de la aplicación que lleve a solicitudes repetidas en una sucesión rápida.
Solicitudes sincronizadas
Una gran cantidad de solicitudes sincronizadas a las API de Google puede parecer un ataque de denegación de servicio distribuido (DSD) en la infraestructura de Google y se puede tratar de forma adecuada. Para evitar esto, debes asegurarte de que las solicitudes a la API no se sincronicen entre clientes.
Por ejemplo, considera una aplicación que muestre la hora en la zona horaria actual. Es probable que esta aplicación configure una alarma en el sistema operativo del cliente para que se active al inicio del minuto, de modo que se pueda actualizar la hora que se muestra. La aplicación no debe realizar llamadas a la API como parte del procesamiento asociado con esa alarma.
Realizar llamadas a la API en respuesta a una alarma fija es mala, ya que hace que las llamadas a la API se sincronicen al inicio del minuto, incluso entre diferentes dispositivos, en lugar de distribuirse de manera uniforme con el tiempo. Una aplicación mal diseñada que haga esto producirá un pico de tráfico sesenta veces más normal al comienzo de cada minuto.
En su lugar, un posible buen diseño es tener una segunda alarma configurada en una hora elegida al azar. Cuando se activa esta segunda alarma, la aplicación llama a cualquier API que necesite y almacena los resultados. Cuando la aplicación quiere actualizar su pantalla al comienzo del minuto, usa los resultados almacenados previamente en lugar de volver a llamar a la API. Con este enfoque, las llamadas a la API se distribuyen de manera uniforme. Además, las llamadas a la API no demoran la representación cuando se actualiza la pantalla.
Además de la hora de inicio del minuto, otros tiempos de sincronización comunes deben tener cuidado de no orientar los anuncios al comienzo de la hora y al comienzo de cada día a la medianoche.
Procesamiento de respuestas
En esta sección se discute cómo extraer esos valores de forma dinámica de las respuestas de los servicios web.
Los servicios web de Google Maps proporcionan respuestas fáciles de entender, pero no son fáciles de usar. Cuando realizas una consulta, en lugar de mostrar un conjunto de datos, es probable que quieras extraer algunos valores específicos. En general, se recomienda analizar las respuestas del servicio web y extraer solo los valores que te interesan.
El esquema de análisis que usas depende de si se muestra un resultado en JSON. Las respuestas JSON, que ya son en forma de objetos de JavaScript, se pueden procesar dentro de JavaScript en el cliente.