Prácticas recomendadas para usar la API de Maps Static

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 imágenes y procesar respuestas del servicio. Consulta la guía para desarrolladores si deseas 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 usar JavaScript ni ninguna carga de página dinámica. Las APIs web estáticas crean una imagen basada en parámetros de URL que se envían mediante una solicitud HTTPS estándar.

Una solicitud típica a la API de Maps Static tiene 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 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:

Resumen de caracteres válidos para URLs
ConjuntocaracteresUso 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 N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 Cadenas de texto, uso de esquemas (http), puerto (8080), etcétera
No reservados . ~ Cadenas de texto
Reservados ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Caracteres de control o cadenas de texto

Al crear una URL válida, debes asegurarte de que contenga solo los caracteres que se muestran en la tabla Resumen de caracteres de URL válidos. 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 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 búsqueda; 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.