Las APIs 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.
En esta guía, se describen algunas prácticas comunes útiles para configurar tus solicitudes de imagen y procesar las respuestas del servicio. Consulta la guía para desarrolladores si quieres obtener la documentación completa de la API de Maps Static.
¿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 Maps Static suele tener el siguiente formato:
https://www.googleapis.com/staticmap/z/x/y?parameters
Nota: Todas las aplicaciones de la API de Maps Static requieren autenticación. Obtén más información sobre las credenciales de autenticación.
Acceso a 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 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:
| Conjunto | caracteres | Uso en la 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 N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 | Cadenas de texto, uso de esquemas (http), puerto (8080), etcétera |
| No reservados | - _ . ~ | Cadenas de texto |
| Reservados | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Caracteres de control o cadenas de texto |
Cuando crees 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:
| Caracteres no seguros | Valor codificado |
|---|---|
| Espacio | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
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.