Guía del desarrollador de Google Static Maps

Google Static Maps API te permite insertar una imagen de Google Maps en tu página web sin la necesidad de usar JavaScript ni otro tipo de carga de página dinámica. El servicio Google Static Maps API crea tu mapa en función de los parámetros de dirección URL que hayas enviado a través de una solicitud HTTP estándar y devuelve el mapa en forma de imagen, que puedes mostrar en tu página web.

Nota: Los Límites de uso de Google Static Maps API han cambiado. Crear una clave de API e incluirla en tu solicitud te permite realizar un seguimiento del uso en Google Developers Console, y comprar cuota adicional, si fuera necesario.

En este documento se detalla Google Static Maps API v2. Para actualizar tus direcciones URL v1, consulta la Guía de actualización.

A continuación, verás un ejemplo rápido

El siguiente ejemplo contiene la dirección URL de una imagen de Google Static Maps API del centro de la ciudad de Nueva York, que se muestra a continuación:

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

No necesitas hacer nada en “especial” para que esta imagen aparezca en la página. No es necesario usar JavaScript. Todo lo que necesitamos hacer es crear una dirección URL y colocarla en una etiqueta <img> Puedes colocar una Google Static Maps API de Google en cualquier parte de tu página web donde puedas insertar una imagen.

Público

Este documento está orientado a desarrolladores de sitios web y móviles que quieran incluir imágenes de Google Static Maps API en una página web o una aplicación móvil. Proporciona una introducción al uso de la API y material de referencia acerca de los parámetros disponibles.

Información general

Google Static Maps API devuelve una imagen (GIF, PNG o JPEG) en respuesta a una solicitud HTTP a través de una dirección URL. Para cada solicitud, puedes especificar la ubicación del mapa, el tamaño de la imagen, el nivel de zoom, el tipo de mapa y la inclusión de marcadores opcionales en diferentes ubicaciones del mapa. También puedes etiquetar tus marcadores usando caracteres alfanuméricos.

Una imagen de Google Static Maps API se inserta en el atributo src de la etiqueta <img>, o su equivalente en otros lenguajes de programación. Si se usa una imagen de Google Static Maps API fuera de una aplicación web (como en un navegador), se deberá incluir un vínculo que conduzca a la ubicación que se muestra en un navegador web o en la aplicación nativa de Google Maps. (Los usuarios de Google Maps API for Work están exentos de este requisito). Consulta la sección 10.1.1(h), Condiciones de servicio de Google Maps/Google Earth, para obtener el lenguaje completo y actual acerca de este requisito.

Este documento describe el formato obligatorio para las direcciones URL de Google Static Maps API y los parámetros disponibles. También incluye algunas sugerencias para la especificación de tus direcciones URL.

Parámetros de dirección URL

Una dirección URL de Google Static Maps API debe respetar el siguiente formato:

https://maps.googleapis.com/maps/api/staticmap?parameters

Si a tu sitio web se accede a través de HTTPS, también debes cargar las imágenes de Google Static Maps API a través de HTTPS para evitar alertas de seguridad del navegador. HTTPS también se recomienda si tus solicitudes incluyen información confidencial, como la ubicación del usuario:

https://maps.googleapis.com/maps/api/staticmap?parameters

Nota: Ten en cuenta que Google Static Maps API no admite direcciones URL de iconos personalizados que usen HTTPS; se mostrará el icono predeterminado.

Ya sea que uses HTTP o HTTPS, ciertos parámetros de las direcciones URL son obligatorios y otros opcionales. Como es norma en las direcciones URL, todos los parámetros se separan con el carácter de Y comercial (&). A continuación, se proporciona una lista de los parámetros y sus posibles valores.

Importante: La siguiente discusión acerca de los parámetros de las direcciones URL usa ejemplos que, por motivos de claridad, se proporcionan en el formato previo al escape. Antes de enviar una solicitud a la API, sus parámetros se deben codificar como dirección URL de forma correcta. Por ejemplo, muchos parámetros usan un carácter de barra vertical (|) como separador, que debe codificarse como %7C en la dirección URL final, tal como se muestra en el ejemplo rápido en la parte superior de este documento. Para obtener más información, consulta Crear una dirección URL válida.

Google Static Maps API define imágenes de mapa con los siguientes parámetros de dirección URL:

Parámetros de ubicación

• center (obligatorio si no hay marcadores presentes) define el centro del mapa, equidistante de todos los bordes del mapa. Este parámetro toma una ubicación como un par de {latitude,longitude} separado por comas (p. ej., "40.714728,-73.998672") o como una cadena de dirección (p. ej., "city hall, new york, ny") para identificar una ubicación única sobre la faz de la tierra. Para obtener más información, consulta Ubicaciones a continuación.
• zoom (obligatorio si no hay marcadores presentes) define el nivel de zoom del mapa, que determina el nivel de amplificación del mapa. Este parámetro toma un valor numérico que corresponde al nivel de zoom de la región deseada. Para obtener más información, consulta niveles de zoom a continuación.

Parámetros de mapas

• size (obligatorio) define las dimensiones rectangulares de la imagen del mapa. Este parámetro toma una cadena de forma {horizontal_value}x{vertical_value}. Por ejemplo, 500x400 define un mapa de 500 píxeles de ando por 400 píxeles de alto. Los mapas más pequeños que 180 píxeles de ancho mostrarán un logotipo de Google reducido. Este parámetro se ve afectado por el parámetro scale, que se describe a continuación; el tamaño de salida final es el producto de los valores de tamaño y escala.
• scale (opcional) afecta la cantidad de píxeles devuelta. scale=2 devuelve el doble de píxeles que scale=1, pero conserva la misma área de cobertura y nivel de detalle (es decir, el contenido del mapa no cambia). Esto resulta útil al desarrollar para visualizaciones en alta resolución o al generar un mapa para impresión. El valor predeterminado es 1. Los valores aceptados son 2 y 4 (4 solo está disponible para clientes de Google Maps API for Work). Para obtener más información, consulta Valores de escala.
• format (opcional) define el formato de la imagen resultante. De forma predeterminada, Google Static Maps API crea imágenes PNG. Hay varios formatos posibles, entre ellos, GIF, JPEG y PNG. El formato que uses depende de cómo quieras presentar la imagen. JPEG generalmente proporciona una mayor compresión, mientras que GIF y PNG proporcionan más detalles. Para obtener más información, consulta Formatos de imagen.
• maptype (opcional) define el tipo de mapa que se construirá. Existen diferentes valores de maptype posibles, e incluyen roadmap, satellite, hybrid y terrain. Para obtener más información, consulta Maptypes de Google Static Maps API a continuación.
• language (opcional) define el idioma que se usará para mostrar etiquetas en los mosaicos de mapa. Ten en cuenta que este parámetro solo es compatible con algunos mosaicos de países; si el idioma específico solicitado no es compatible con el conjunto de mosaicos, se usará el idioma predeterminado para ese conjunto de mosaicos.
• region (opcional) define los límites adecuados para mostrar, en función de sensibilidades geopolíticas. Acepta un código de región especificado como un valor ccTLD de dos caracteres ('dominio de nivel superior').

Parámetros de características

• markers (opcional) define uno o más marcadores para adjuntar a la imagen en las ubicaciones especificadas. Este parámetro toma la definición de un solo marcador con parámetros separados por el carácter de barra vertical (|). Se pueden incluir múltiples marcadores en el mismo parámetro markers siempre que exhiban el mismo estilo; podrías necesitar agregar más marcadores de diferentes estilos agregando parámetros markers adicionales. Ten en cuenta que su proporcionas marcadores para un mapa, no es necesario que especifiques los parámetros (generalmente obligatorios) center y zoom. Para obtener más información, consulta Marcadores de Google Static Maps API a continuación
• path (opcional) define un solo trayecto para dos o más puntos conectados para superponer en la imagen en las ubicaciones especificadas. Este parámetro toma una cadena de definiciones de puntos separados por el carácter de barra vertical (|). Puedes proporcionar más trayectos al agregar parámetros path adicionales. Ten en cuenta que su proporcionas un trayecto para un mapa, no es necesario que especifiques los parámetros (generalmente obligatorios) center y zoom. Para obtener más información, consulta Trayectos de Google Static Maps API a continuación.
• visible (opcional) especifica una o más ubicaciones que deben permanecer visibles en el mapa, aunque no se mostrarán marcadores ni otros indicadores. Usa este parámetro para garantizar que se muestren ciertas características o ubicaciones del mapa en Google Static Maps API.
• style (opcional) define un estilo personalizado para alterar la presentación de una característica específica (calle, parque, etc.) del mapa. Este parámetro toma argumentos feature y element que identifican las características que se seleccionarán y un conjunto de operaciones de estilo para aplicar a esa selección. Puedes proporcionar múltiples estilos al agregar parámetros style adicionales. Para obtener más información, consulta Mapas con estilos a continuación.

Parámetros de clave y firma

• key (obligatorio) te permite controlar el uso de la API que realiza tu aplicación en Google Developers Console; habilita límites de cuota basados en la clave en lugar de en la dirección IP y garantiza que Google pueda comunicarse contigo acerca de tu aplicación, si fuera necesario. Para acceder a más información, consulta Obtener una clave y una firma.
• signature (recomendado) es una firma digital que se usa para verificar que los sitios que generen solicitudes con tu clave de API estén autorizados para hacerlo. Para acceder a más información, consulta Obtener una clave y una firma.

Los usuarios de Google Maps API for Work deben incluir parámetros client y signature válidos con sus solicitudes. Para obtener más información, consulta el capítulo Autenticación y autorización en Google Maps API for Work.

Restricción de tamaño para direcciones URL

Las direcciones URL de la Google Static Maps API están restringidas a un tamaño aproximado de 2048 caracteres. En la práctica, probablemente no necesites direcciones URL más extensas, a menos que generes mapas complicados con una gran cantidad de marcadores y trayectos. No obstante, ten en cuenta que ciertos caracteres pueden ser codificados para direcciones URL por navegadores o servicios antes de enviarlos a la API, lo que produce un mayor uso de caracteres. Para obtener más información, consulta Crear una dirección URL válida.

Uso de parámetros

Google Static Maps API es relativamente fácil de usar, ya que consiste únicamente en una dirección URL con parámetros. Esta selección explica cómo usar esos parámetros para construir tus direcciones URL.

Especificación de ubicaciones

Google Static Maps API debe poder identificar con precisión ubicaciones en el mapa, tanto para centrar el mapa en la ubicación correcta (usando el parámetro center) como para colocar marcas de posición opcionales (usando el parámetro markers) en diferentes ubicaciones del mapa. Google Static Maps API usa números (valores de latitud y longitud) o cadenas (direcciones) para especificar esas ubicaciones. Esos valores identifican una ubicación geocodificada.

Muchos parámetros (como markers y path) incluyen múltiples ubicaciones. En esos casos, las ubicaciones se separan con el carácter de barra vertical (|)

Latitudes y longitudes

Las latitudes y longitudes se definen con numerales dentro de una cadena de texto separada por comas que tiene una precisión de 6 decimales. Por ejemplo, "40.714728,-73.998672" es un geocode válido. La precisión superior a 6 decimales se ignora.

Los valores de longitud se basan en la distancia desde Greenwich, Inglaterra, donde se encuentra el primer meridiano. Dado de Greenwich se encuentra en la latitud 51.477222, podemos ingresar un valor center de 51.477222,0 para centrar el mapa en Greenwich:

Los valores de latitud y longitud deben corresponder a una ubicación válida sobre la superficie de la tierra. Las latitudes pueden tener cualquier valor entre -90 y 90 mientras que los valores de longitud pueden tener cualquier valor entre -180 y 180. Si especificas un valor de latitud o longitud no válido, se rechazará tu solicitud por ser incorrecta.

Direcciones

La mayoría de las personas no hablan de latitudes y longitudes, sino que indican ubicaciones mediante direcciones. El proceso de convertir una dirección en un punto geográfico se conoce como geocodificación, y el servicio Google Static Maps API puede realizar la geocodificación por ti si proporcionas direcciones válidas.

En cualquier parámetro en el que puedas proporcionar un par de latitud/longitud, puedes especificar una cadena que indique una dirección. Google geocodificará la dirección y le proporcionará al servicio de Google Static Maps API un valor de latitud/longitud para usar en la colocación de marcadores o la especificación de ubicaciones. La cadena debe transferirse a la dirección URL, de modo que una dirección como "City Hall, New York, NY" se debe convertir en "City+Hall,New+York,NY", por ejemplo.

Ten en cuenta que las direcciones pueden reflejar ubicaciones precisas, como calles; polilíneas, como nombres de rutas o áreas poligonales, como ciudades, países o parques nacionales. Para los resultados polilineales y poligonales, el servidor Google Static Maps API usará el punto central de la línea/el área como el centro de la dirección. Si tienes dudas acerca de cómo se puede geocodificar una dirección, puedes probar la dirección usando esta Utilidad de geocodificación.

El siguiente ejemplo genera un Google Static Maps API para Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

Niveles de zoom

Los mapas de Google Maps tienen un nivel de zoom en números naturales que define la resolución de la vista actual. En la vista predeterminada roadmap, pueden aplicarse niveles de zoom entre 0 (el nivel de zoom más bajo en el que se puede ver todo el mundo en un mapa) y 21+ (acercamiento de calles y edificios individuales). Los contornos de los edificios, cuando estén disponibles, aparecerán en el mapa cerca del nivel de zoom 17. Este valor difiere según el área y puede cambiar con el tiempo a medida que evolucionan los datos.

Google Maps establece el nivel de zoom en 0 para poder abarcar toda la tierra. Cada nivel de zoom siguiente duplica la precisión tanto en la dimensión horizontal como en la vertical. Para obtener más información acerca de cómo hacer esto, consulta la documentación de Google Maps JavaScript API.

Nota: no todos los niveles de zoom estarán disponibles en todas las ubicaciones de la tierra. Los niveles de zoom varían según la ubicación, ya que los datos en algunas partes del planeta son más granulares que en otras ubicaciones.

Si envías una solicitud para un nivel de zoom en el que no hay mosaicos de mapas disponibles, Google Static Maps API devolverá un mapa con el máximo nivel de zoom disponible en esa ubicación.

El ejemplo a continuación solicita dos mapas de Manhattan en el mismo valor center, pero con niveles de zoom 12 y 14, respectivamente:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

  

Tamaños de las imágenes

El parámetro size, junto con center, define el área de cobertura de un mapa. También define el tamaño de salida del mapa en píxeles, cuando se multiplica con el valor scale (que, de forma predeterminada, es 1).

La siguiente tabla muestra los valores máximos permitidos para el parámetro size en cada valor de scale.

API	scale=1	scale=2	scale=4
Gratis	640x640	640x640 (devuelve 1280x1280 píxeles)	No disponible.
Google Maps API for Work	2048x2048	1024x1024 (devuelve 2048x2048 píxeles)	512x512 (devuelve 2048x2048 píxeles)

El ejemplo a continuación solicita una “porción” de la tierra en el Ecuador a un nivel de zoom 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

El ejemplo a continuación solicita un mapa pequeño, de 100 x 100 píxeles centrado en la misma región. Observa el logotipo de Google más pequeño:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

Valores de escala

El parámetro size de Google Static Maps API define el tamaño de un mapa en píxeles, de modo que un mapa con size=200x200 se devolverá como 200 píxeles x 200 píxeles. En un monitor de computadora LCD, que generalmente muestra aproximadamente 100 píxeles por pulgada (ppp), un mapa de 200x200 medirá aproximadamente 2 pulgadas en cada dimensión.

No obstante, los dispositivos móviles incluyen cada vez con más frecuencia pantallas de alta resolución con densidades de píxeles superiores a los 300 ppp que:

• Reducen el tamaño de una imagen de 200x200 píxeles a solo 0,7 de pulgada y exhiben las etiquetas y los iconos demasiado pequeños para leerlos; o
• Aplican escala (zoom) a la imagen para mejorar la legibilidad, lo que genera una imagen poco definida o pixelada.

Demasiado pequeña	Muy poco definida

Al desarrollar para dispositivos móviles, usa el parámetro scale de la API para devolver imágenes de mapa de mayor resolución que resuelvan los problemas antes planteados. El valor de scale se multiplica por el del size para determinar el tamaño de salida real de la imagen en píxeles, sin modificar el área de cobertura del mapa. (El valor predeterminado de scale es 1; los valores aceptados son 1, 2, y (para clientes de Google Maps API for Work únicamente) 4).

Por ejemplo, un valor de escala de 2 devolverá la misma área de cobertura del mapa como una solicitud sin escala especificada, pero con el doble de píxeles en cada dimensión. Esto incluye calles y etiquetas, de modo que puedan leerse en alta resolución, en pantallas pequeñas y cuando se el navegador les aplique escala.

150x150	150x150&scale=2

Una imagen como esta también se verá bien en navegadores de escritorio, cuando se la inserte en una etiqueta img o div con la altura y el ancho configurados con CSS. El navegador achicará la imagen al tamaño correcto sin pérdida de calidad.

La siguiente tabla muestra tres solicitudes de imagen diferentes.

• La primera es para una imagen de 100x100 sin valor de escala especificado. Se visualiza bien en el escritorio, pero es muy pequeña para leerla en un dispositivo móvil.
• La segunda duplica el tamaño del mapa. En el escritorio, el CSS se ajusta al elemento img de 100x100 especificado, pero al reducir el tamaño de la imagen, las calles y etiquetas se ven muy pequeñas. En el dispositivo móvil, la imagen tiene el tamaño correcto, pero nuevamente, las calles y etiquetas son ilegibles.
• La tercera solicitud es para un mapa de 100x100 con scale=2. La imagen se devuelve con 200 píxeles de detalle; el escritorio la reduce a escala perfectamente de modo que sea indistinguible respecto de la solicitud original de 100x100, mientras el navegador móvil se beneficia de la resolución adicional que devuelve la API.

Dispositivo	100x100	200x200	100x100&scale=2
Escritorio (con height="100px" y width="100px" en la etiqueta img)
Alta resolución (simulación)

Sugerencia: Las plataformas móviles, como Android e iOS, permiten que las aplicaciones admitan pantallas de alta resolución al especificar imágenes individuales para cada resolución. El parámetro de escala facilita la solicitud de una imagen de mapa para una pantalla con resolución estándar, y el mapa correspondiente para una pantalla de alta resolución, simplemente al configurar scale=1 y scale=2 respectivamente.

Para obtener más información acerca del desarrollo para pantallas de dispositivos móviles y de alta resolución, te recomendamos que leas lo siguiente:

• Compatibilidad con diferentes pantallas en la documentación para desarrolladores de Android.
• Las recomendaciones de Webkit.org para el desarrollo de Sitios web con muchos ppp.
• Compatibilidad con pantallas de alta resolución en la biblioteca para desarrolladores de iOS.

Formatos de imagen

Las imágenes pueden devolverse en diferentes formatos gráficos web comunes: GIF, JPEG y PNG. El parámetro format admite uno de los siguientes valores:

• png8 o png (predeterminado) especifica el formato PNG de 8 bits.
• png32 especifica el formato PNG de 32 bits.
• gif especifica el formato GIF.
• jpg especifica el formato de compresión JPEG.
• jpg-baseline especifica un formato de compresión JPEG no progresivo.

jpg y jpg-baseline generalmente proporcionan el tamaño de imagen más pequeño, y lo hacen mediante compresión “con pérdida”, que puede degradar la imagen. gif, png8 y png32 proporcionan una compresión con menos pérdida.

La mayoría de las imágenes JPEG son progresivas, lo que significa que cargan una imagen más tosca con anticipación y redefinen su resolución a medida que reciben más datos. Esto permite que las imágenes puedan cargarse rápidamente en páginas web y es el uso más común de JPEG en la actualidad. No obstante, algunos usos de JPEG (especialmente la impresión) requieren imágenes no progresivas (básicas). En esos casos, te recomendamos que uses el formato jpg-baseline, que es no progresivo.

Tipos de mapas

Google Static Maps API crea mapas en diferentes formatos, que se indican a continución:

• roadmap (predeterminado), especifica una imagen de mapa de ruta estándar, como habitualmente se muestra en el sitio web de Google Maps. Si no se especifica un valor de maptype, Google Static Maps API proporciona mosaicos de roadmap de forma predeterminada.
• satellite especifica una imagen satelital.
• terrain especifica una imagen de un mapa de relevamiento físico que muestra terreno y vegetación.
• hybrid especifica un híbrido de la imagen satelital y del mapa de ruta, y muestra una capa transparente de las calles principales y los nombres de los sitios que aparecen en la imagen satelital.

En el siguiente ejemplo de código, puedes ver la diferencia entre los tipos mapa de ruta y terreno.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

  

Los mapas híbridos usan imágenes satelitales y características prominentes del mapa de ruta para crear un mapa combinado. Los siguientes ejemplos muestran los tipos de mapa híbrido y satelital:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

  

Mapas con estilos

Los mapas con estilos te permiten personalizar la presentación de los estilos de mapas estándar de Google, cambiar la visualización de elementos como calles, parques y áreas con edificaciones para reflejar un estilo diferente del que se usó en el tipo de mapa predeterminado. Esos componentes se conocen como características, y un mapa con estilos te permite seleccionar esas características y aplicarles estilos visuales (incluso ocultarlas por completo). Con estos cambios, se puede lograr que el mapa enfatice componentes específicos o contenido complementario en la página circundante.

Un mapa “con estilos” personalizado consiste en uno o más estilos especificados, cada uno indicado mediante un parámetro style en la dirección URL de la solicitud de Google Static Maps API. Puedes especificar estilos adicionales al pasar otros parámetros style. Un estilo consiste en una selección y un conjunto de reglas para aplicar esa selección. Las reglas indican la modificación visual que se realizará a la selección.

Cada declaración de style consiste en los siguientes argumentos, separados con el carácter de barra vertical ("|") dentro de la declaración de style:

• feature (opcional) indica qué características seleccionar para la modificación de este estilo. (Consulta Características de mapas a continuación). Si no se pasa un argumento feature, se seleccionarán todas las características.
• element (opcional) indica qué subconjunto de las características seleccionadas se debe escoger. (Consulta Elementos de mapas a continuación). Si no se pasa un argumento element, se seleccionarán todos los elementos de la característica en cuestión.
• Los argumentos posteriores indican las reglas que se deben aplicar a la selección anterior. Todas las reglas se aplican en el orden en que aparecen en la declaración de style. (Consulta Reglas de estilo a continuación). La selección de características puede estar seguida de cualquier cantidad de reglas, dentro de las restricciones normales de Google Static Maps API para la longitud de las direcciones URL.

Nota: la declaración de style debe especificar los argumentos anteriores en el orden indicado. Por ejemplo, una selección de características con dos reglas se vería de la siguiente manera:

style=feature:featureArgument|element:elementArgument|rule1:rule1Argument|rule2:rule2Argument

Funciones de mapas

Un mapa consiste en un conjunto de características, como calles y parques. Los tipos de características forman un árbol de categorías, con feature:all como la raíz. A continuación se indican algunas de las características más comunes:

• feature:all (predeterminada) selecciona todas las características del mapa.
• feature:road selecciona todas las calles/rutas en el mapa.
• feature:landscape selecciona todos los paisajes de fondo en un mapa, que generalmente es el área entre rutas, por ejemplo. En las ciudades, el paisaje normalmente consiste en áreas con edificaciones.

En la referencia de Google Maps JavaScript API se proporciona la lista completa de funciones para seleccionar dentro de un mapa.

Algunas categorías de tipos de características contienen subcategorías que se especifican en notación estándar (landscape.natural o road.local, por ejemplo). Si se especifica la característica principal (road, ejemplo), los estilos aplicados a esa selección se aplicarán a todas las rutas, incluidas las subcategorías.

Elementos de las características de mapas

Además, algunas características en un mapa generalmente constan de varios elementos. Una ruta, por ejemplo, consiste no solo en la línea gráfica (geometría) en el mapa, sino también en el texto que la define (etiquetas) adjuntado al mapa. Los elementos dentro de las características se seleccionan al declarar un argumento elemento. Se admiten los siguientes valores de argumento de elementos:

• element:all (predeterminado) selecciona todos los elementos de esa característica.
• element:geometry selecciona solo los elementos geométricos de esa característica.
• element:labels selecciona solo las etiquetas textuales asociadas con esa característica.

Si no se pasa un argumento de elemento, los estilos se aplicarán a todos los elementos de la característica en cuestión, independientemente del tipo de elemento.

La siguiente declaración de style selecciona las etiquetas para todas las rutas locales:

style=feature:road.local|element:labels

Reglas de estilo

Las reglas de estilo son opciones de formato que se aplican a las características y los elementos especificados en cada declaración de style. Cada declaración de style debe contener una o más operaciones separadas por un carácter de barra vertical ("|"). Cada operación especifica el valor de su argumento con dos puntos (":"), y se aplican todas las operaciones a la selección en el orden en el que se especificaron.

Actualmente, se admiten los siguientes argumentos de operaciones, y los valores que aceptan:

• hue (una cadena RGB hexadecimal de formato 0xRRGGBB) indica el color básico que se aplicará a la selección. (* Consulta la nota sobre uso a continuación).
• lightness (un valor de punto flotante entre -100 y 100) indica el cambio en el porcentaje de brillo del elemento. Los valores negativos aumentan la oscuridad (donde -100 especifica negro) mientras los valores positivos aumentan el brillo (donde +100 especifica blanco).
• saturation (un valor de punto flotante entre -100 y 100) indica el cambio en el porcentaje de la intensidad del color básico que se aplicará al elemento.
• gamma (un valor de punto flotante entre 0.01 y 10.0, donde 1.0 no aplica corrección) indica la cantidad de corrección gamma que se aplicará al elemento. Los valores gamma modifican el brillo de los tonos de forma no lineal, sin afectar los valores de blanco o negro. Los valores gamma generalmente se usan para modificar el contraste de múltiples elementos. Por ejemplo, podrías modificar un valor gamma para aumentar o reducir el contraste entre los bordes y el interior de los elementos. Los valores gamma bajos (< 1) aumentan el contraste y los valores gamma altos (> 1) disminuyen el contraste.
• inverse_lightness:true simplemente invierte el brillo actual.
• visibility (on, off o simplified) indica si aparece el elemento en el mapa y cómo. visibility:simplified indica que el mapa debe simplificar la presentación de esos elementos como lo considere adecuado. (Por ejemplo, una estructura de rutas simplificada puede mostrar menos rutas).

Las reglas de estilo se deben aplicar como operaciones independientes y en el orden en que aparecen en la declaración de style. El orden es importante, ya que algunas operaciones no son conmutativas. Las características o los elementos que se modifican mediante operaciones de estilo (generalmente) ya tienen estilos; las operaciones actúan sobre esos estilos existentes, si estuvieran presentes.

Ten en cuenta que usamos el modelo tono, saturación, brillo (HSL) para denotar color dentro de las operaciones de estilo. Esas operaciones para definir color son comunes en diseño gráfico. Hue indica el color básico, saturation indica la intensidad de ese color, y lightness indica la cantidad relativa de blanco o negro en el color constituyente. Los tres valores HSL se pueden asignar a valores RGB (y viceversa). La corrección gamma modifica la saturación en el espacio de color, generalmente para aumentar o reducir el contraste. Además, el modelo HSL define color en un espacio de coordenadas donde hue indica la orientación en una paleta de colores, y la saturación y el brillo indican amplitudes a lo largo de diferentes ejes. Los tonos se miden en un espacio de color RGB similar a la mayoría de los espacios de color RGB, excepto porque no están presentes los matices de blanco y negro.

Paleta de colores RGB

Nota: si bien hue admite un valor de color hexadecimal RGB, solo usa ese valor para determinar el color básico (su orientación en la paleta de colores), no su saturación ni su brillo, que se indican por separado como cambios de porcentaje. Por ejemplo, el tono para un verde puro se puede definir como hue:0x00ff00 o hue:0x000100 y ambos valores serán idénticos. (Ambos valores apuntan al verde puro en el modelo de color HSL). Los valores hue en RGB que consisten en partes iguales de rojo, verde y azul, como hue:0x0000000 (negro) y hue:0xffffff (blanco) y todos los matices puros de gris, no indican un tono, ya que ninguno de esos valores indican una orientación en el espacio de coordenadas de HSL. Para indicar negro, blanco o gris, debes eliminar toda la saturation (agrega una operación saturation:-100) y ajustar el lightness.

Además, al modificar características existentes que ya tienen un esquema de color, cambiar un valor como hue no cambia su saturation o lightness existentes.

El siguiente ejemplo muestra un mapa de Brooklyn donde las calles locales se cambiaron a verde brillante y las áreas residenciales se cambiaron a negro (ten en cuenta que en este ejemplo completo los separadores de barra vertical se codificaron correctamente como dirección URL; consulta la nota anterior):

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=15&center=Brooklyn&style=feature:road.local%7Celement:geometry%7Ccolor:0x00ff00%7Cweight:1%7Cvisibility:on&style=feature:landscape%7Celement:geometry.fill%7Ccolor:0x000000%7Cvisibility:on&style=feature:administrative%7Celement:labels%7Cweight:3.9%7Cvisibility:on%7Cinverse_lightness:true&style=feature:poi%7Cvisibility:simplified&key=YOUR_API_KEY

El siguiente ejemplo usa operaciones y simplificaciones para aproximar la apariencia de un atlas de rutas de los EE. UU.

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=12&center=Chicago&format=png&style=feature:road.highway%7Celement:geometry%7Cvisibility:simplified%7Ccolor:0xc280e9&style=feature:transit.line%7Cvisibility:simplified%7Ccolor:0xbababa&style=feature:road.highway%7Celement:labels.text.stroke%7Cvisibility:on%7Ccolor:0xb06eba&style=feature:road.highway%7Celement:labels.text.fill%7Cvisibility:on%7Ccolor:0xffffff&key=YOUR_API_KEY

Marcadores

El parámetro markers define un conjunto de uno o más marcadores en un conjunto de ubicaciones. Cada uno de los marcadores definidos en una declaración markers individual deben exhibir el mismo estilo visual; si quieres mostrar marcadores con estilos diferentes, deberás proporcionar múltiples parámetros markers con información de estilo independiente.

El parámetro markers admite un conjunto de asignaciones de valor (descriptores de marcadores) con el siguiente formato:

markers=markerStyles|markerLocation1| markerLocation2|... etc.

El conjunto de markerStyles se indica al comienzo de la declaración de markers y consiste en cero o más descriptores de estilo separados por una barra vertical (|), seguidos por un conjunto de una o más ubicaciones también separadas por el carácter de barra vertical (|).

Como la información de estilo y la información de ubicación está delimitada por el carácter de barra vertical, la información de estilo debe aparecer primero en cualquier descriptor de marcadores. Una vez que el servidor Google Static Maps API encuentra una ubicación en el descriptor de marcadores, se da por sentado que todos los demás parámetros de marcador también son ubicaciones.

Estilos de marcador

El conjunto de descriptores de estilo de los marcadores es una serie de asignaciones de valor separadas por el carácter de barra vertical (|). Este descriptor de estilo define los atributos visuales que se deben usar al mostrar los marcadores dentro de este descriptor de marcadores. Estos descriptores de estilo contienen las siguientes asignaciones de clave/valor:

• size: (opcional) especifica el tamaño del marcador según el conjunto {tiny, mid, small}. Si no se estableció un parámetro size, el marcador aparecerá en su tamaño predeterminado (normal).

• color: (opcional) especifica un color de 24 bits (ejemplo: color=0xFFFFCC) o un color predefinido del grupo {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Ten en cuenta que las transparencias (especificadas usando valores de color hexadecimales de 32 bits) no se admiten en los marcadores, aunque sí se admiten para los trayectos.

• label: (opcional) especifica un carácter alfanumérico en mayúscula individual del conjunto {A-Z, 0-9}. (El requisito de caracteres en mayúscula es nuevo para esta versión de la API). Ten en cuenta que los marcadores de tamaño predeterminado y mid son los únicos capaces de mostrar un parámetro alphanumeric-character. Los marcadores tiny y small no pueden mostrar un carácter alfanumérico.

Nota: en lugar de usar esos marcadores, puedes usar tu propio icono personalizado. (Para obtener más información, consulta Iconos personalizados a continuación).

Ubicaciones de los marcadores

Cada descriptor de marcadores debe contener un conjunto de una o más ubicaciones que definan dónde colocar el marcador en el mapa. Esas ubicaciones pueden especificarse como valores de latitud/longitud o como direcciones. Las ubicaciones se separan con el carácter de barra vertical (|).

Los parámetros de la ubicación definen la ubicación del marcador en el mapa. Si la ubicación está fuera del mapa, el marcador no aparecerá en la imagen construida si se proporcionan los parámetros center y zoom. No obstante, si no se proporcionan esos parámetros, el servidor de Google Static Maps API construirá automáticamente una imagen que contenga los marcadores proporcionados. (Consulta Posicionamiento implícito a continuación).

Aquí se muestra un ejemplo de declaración de marcadores. Ten en cuenta que definimos un conjunto de estilos y tres ubicaciones:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

Para definir marcadores con estilos diferentes, necesitamos proporcionar múltiples parámetros markers. Este conjunto de parámetros markers define tres marcadores: un marcador azul con la etiqueta "S" en 62.107733, -145.5419, un marcador pequeño color verde en "Delta Junction, AK", y un marcador mediano color amarillo con la etiqueta "C" en "Tok, AK". Estos marcadores se muestran en el siguiente ejemplo:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

Iconos personalizados

En lugar de usar iconos de marcadores de Google, puedes usar tus propios iconos personalizados. Los iconos personalizados se especifican en el parámetro markers usando los siguientes descriptores:

• icon especifica una dirección URL para usar como el icono personalizado del marcador. Las imágenes pueden tener formato PNG, JPEG o GIF, aunque se recomienda PNG.
• shadow (valor predeterminado true) indica que el servicio de Google Static Maps API debe construir una instantánea para la imagen. Esa instantánea se basa en la región visible de la imagen y su opacidad/transparencia.

El parámetro icon se debe especificar usando una dirección URL (que debe tener codificación URL). Puedes usar cualquier dirección URL válida de tu elección, o un servicio de acortamiento de direcciones URL como http://goo.gl. La mayoría de los servicios de acortamiento de direcciones URL tienen la ventaja de poder codificar direcciones URL automáticamente. Los iconos están limitados a los 4096 píxeles (64x64 para imágenes cuadradas), y el servicio de Google Static Maps API admite hasta cinco iconos personalizados únicos por solicitud. Ten en cuenta que cada uno de esos iconos únicos se pueden usar múltiples veces en Google Static Maps API.

Los iconos personalizados que poseen un descriptor shadow:true (predeterminado) tendrán su “punto de anclaje” establecido como la parte central inferior de la imagen del icono proporcionada, desde la que se obtiene la instantánea. Los iconos sin una instantánea (configuración de un descriptor shadow:false) se asumen como iconos centrados en sus ubicaciones específicas, de modo que sus puntos de anclaje se establecen como el centro de la imagen.

El siguiente ejemplo usa la Google Chart API para crear marcadores personalizados que indiquen varias cafeterías en la ciudad de Nueva York:

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Nota: Los distintos niveles de escape anteriores pueden resultar confusos. Google Chart API usa el carácter de barra vertical (|) para delimitar cadenas dentro de sus parámetros de dirección URL. Dado que el uso de este carácter en una dirección URL no es legal (consultar la nota anterior), al crear una dirección URL completamente válida para un gráfico, se debe transferir como %7C. Ahora el resultado se inserta como cadena en una especificación icon, pero contiene un carácter % (proveniente de %7C, como se mencionó antes), que no se puede incluir directamente como datos en una dirección URL y debe transferirse como %25. El resultado es que la dirección URL contiene %257C, que representa dos capas de codificación. De igual manera, la dirección URL del gráfico contiene un carácter &, que no se puede incluir directamente sin que se confunda con un separador para parámetros de dirección URL de Google Static Maps API, por lo que también debe codificarse.

Aquí te mostramos los pasos para crear la dirección URL de Google Static Maps API:

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Trayectos Google Static Maps API

El parámetro path define un conjunto de una o más ubicaciones conectadas por un trayecto para superponerse en una imagen de mapa. El parámetro path admite un conjunto de asignaciones de valor (descriptores de trayecto) con el siguiente formato:

path=pathStyles|pathLocation1|pathLocation2|... etc.

Ten en cuenta que ambos puntos del trayecto están separados entre sí por el carácter de barra vertical (|). Como la información de estilo y la información de punto está delimitada por el carácter de barra vertical, la información de estilo debe aparecer primero en cualquier descriptor de trayecto. Una vez que el servidor Google Static Maps API encuentra una ubicación en el descriptor de trayecto, se da por sentado que todos los demás parámetros de trayecto también son ubicaciones.

Estilos de trayecto

El conjunto de descriptores de estilo de trayecto es una serie de asignaciones de valor separadas por el carácter de barra vertical (|). Este descriptor de estilo define los atributos visuales que se deben usar al mostrar el trayecto. Estos descriptores de estilo contienen las siguientes asignaciones de clave/valor:

• weight: (opcional) especifica el grosor del trayecto en píxeles. Si no se estableció un parámetro weight, el trayecto aparecerá en su grosor predeterminado (5 píxeles).

• color: (opcional) especifica un color como un valor hexadecimal de 24 bits (ejemplo: color=0xFFFFCC) o de 32 bits (ejemplo: color=0xFFFFCCFF), o a partir del conjunto {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Cuando se especifica un valor hexadecimal de 32 bits, los últimos dos caracteres especifican el valor de transparencia alfa de 8 bits. Este valor oscila entre 00 (completamente transparente) y FF (completamente opaco). Ten en cuenta que en los trayectos se admiten las transparencias, pero no se admiten para los marcadores.

• fillcolor: (opcional) indica que el trayecto señala un área poligonal y especifica el color de relleno que se usará como superposición en esa área. No es necesario que el conjunto de ubicaciones que sigue sea un bucle “cerrado”; el servidor de Google Static Maps API unirá automáticamente el primer y el último punto. No obstante, ten en cuenta que cualquier pincelada fuera del área rellenada no se cerrará a menos que proporciones específicamente la misma ubicación inicial y final.
• geodesic: (opcional) indica que el trayecto solicitado se debe interpretar como una línea geodésica que sigue la curvatura de la tierra. Cuando esto no ocurre, el trayecto se muestra como una línea recta en la pantalla. El valor predeterminado es “false”.

Aquí te mostramos algunas definiciones de trayecto de ejemplo:

• Línea fina azul con 50% de opacidad: path=color:0x0000ff80|weight:1
• Línea sólida roja: path=color:0xff0000ff|weight:5
• Línea sólida y gruesa color blanco: path=color:0xffffffff|weight:10

Estos estilos de trayecto son opcionales. Si prefieres usar atributos predeterminados, puedes omitir la definición de los atributos de trayecto; en ese caso, el primer “argumento” del descriptor de trayecto consistirá en el primer punto (ubicación) declarado.

Puntos del trayecto

Para trazar un trayecto, también se le debe pasar al paaráametro path dos o más puntos. Luego, Google Static Maps API conectará el trayecto entre esos puntos en el orden especificado. Cada pathPoint se indica en el pathDescriptor separado por el carácter de barra vertical |.

El siguiente ejemplo define un trayecto azul con un 50% de opacidad predeterminado, desde Union Square, NY, hasta Times Square, NY.

A continuación se indican las características específicas del parámetro path:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

El siguiente ejemplo define el mismo trayecto en lugar de definir una línea sólida roja con un 100% de opacidad.

A continuación se indican las características específicas de este parámetro path:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

El siguiente ejemplo define un área poligonal dentro de Manhattan, para la que se pasó una serie de intersecciones como ubicaciones:

A continuación se indican las características específicas de este parámetro path:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Ten en cuenta que configuramos el trayecto para que sea invisible y el área poligonal para que tenga una opacidad del 15%.

Polilíneas codificadas

En lugar de una serie de ubicaciones, puedes declarar un traayecto como una polilínea codificada usando el prefijo enc: con la declaración de ubicación del path. Ten en cuenta que su proporcionas un trayecto en forma de polilínea codificada para un mapa, no es necesario que especifiques los parámetros (generalmente obligatorios) center y zoom.

El siguiente ejemplo señala el trayecto de la autopista de Alaska desde Dawson Creek, BC hasta Delta Junction, AK con una polilínea codificada:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

Al igual que con los trayectos estándar, los trayectos en forma de polilínea codificada también pueden demarcar áreas poligonales si se pasar un argumento fillcolor al parámetro path.

En el siguiente ejemplo se indica un área poligonal para Brooklyn, NY:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Viewports

Las imágenes pueden especificar un viewport al indicar ubicaciones visibles con el parámetro visible. El parámetro visible le indica al servicio Google Static Maps API que construya un mapa de modo que las ubicaciones existentes sigan estando visibles. (Este parámetro también puede combinarse con marcadores o trayectos existentes para definir una región visible). Al definir un viewport de esta manera, se evita la necesidad de especificar un nivel de zoom exacto.

En el siguiente ejemplo se solicita un mapa centrado en Boston, MA, que contiene MIT y Harvard Square en Cambridge, MA:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

Posicionamiento implícito del mapa

Normalmente, debes especificar los parámetros de dirección URL center y zoom para definir la ubicación y el nivel de zoom del mapa que generaste. No obstante, si proporcionas los parámetros markers, path o visible, puedes permitirle a Google Static Maps API que determine el centro y el nivel de zoom correctos implícitamente, en función de una evaluación de la posición de esos elementos.

Si proporcionas dos o más elementos, Google Static Maps API determinará un centro y un nivel de zoom correctos, y proporcionará márgenes generosos para los elementos dentro del área. El ejemplo a continuación muestra un mapa que contiene San Francisco, Oakland y San Jose, CA:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

Solución de problemas y soporte

Para obtener más información acerca del uso de Google Static Maps API, échale un vistazo a la página de soporte.

Google Static Maps API puede generar un error o una advertencia cuando algo sale mal. Debes comprobar especialmente la presencia de advertencias si notas que falta algo en el mapa. Se recomienda que compruebes la presencia de advertencias antes de lanzar una aplicación nueva. Ten en cuenta que posiblemente no notes las advertencias de inmediato ya que aparecen en el encabezado de HTTP. Para obtener más información, consulta la guía de errores y advertencias.

Antes, Google Static Maps API requería que incluyeras el parámetro sensor para indicar si tu aplicación usaba un sensor para determinar la ubicación del usuario. El uso de este parámetro ya no es obligatorio.