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 API 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 APIs Premium Plan 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

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 APIs Premium Plan). 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 modificar la presentación de una característica específica (calles, parques, etc.) del mapa. Este parámetro toma argumentos feature y element que identifican las características a las que se les aplicará estilo y un conjunto de operaciones de estilo que se implementarán en las características seleccionadas. Puedes proporcionar múltiples estilos agregando parámetros style adicionales. Para obtener más información, consulta la guía de mapas con ajustes de estilo.

Parámetros de clave y firma

• key (obligatorio) te permite controlar el uso de la API por parte de tu aplicación en Google API Console, habilita el acceso a una cuota diaria gratuita y garantiza que Google pueda comunicarse contigo respecto de tu aplicación, si es 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. Nota: Si habilitas la facturación, se requiere la firma digital. Si excedes el límite diario gratuito de cargas de mapa, se facturará el resto de los mapas que cargues durante el día. Las cargas de mapa facturables en las que no se incluya la firma digital fallarán. Para acceder a más información, consulta Obtener una clave y una firma.

Nota: Los clientes de Google Maps APIs Premium Plan pueden usar una clave de API y una firma digital, o una firma digital y un ID de cliente válidos, en tus solicitudes de Static Maps. Obtén más información sobre parámetros de autenticación para clientes del Premium Plan.

Los clientes con una licencia anterior de Google Maps APIs for Work deben incluir parámetros client y signature válidos con sus solicitudes, en lugar de una key. Para obtener más información, consulta la sección ID de cliente y firmas de la página Obtener una clave y una firma.

Restricción de tamaño para direcciones URL

Las direcciones URL de la Google Static Maps API tienen una limitación de tamaño de 8192 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.

En la siguiente lista, se muestra el nivel aproximado de detalle que puedes esperar ver en cada nivel de zoom:

• 1: Mundo
• 5: Tierra firme y continente
• 10: Ciudad
• 15: Calles
• 20: Edificios

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 APIs Premium Plan	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 APIs Premium Plan ú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 100 x 100 con scale=2. La imagen se muestra con un nivel de detalle de 200 px; el escritorio la reduce a escala perfectamente, de modo que no pueda distinguirse respecto de la solicitud original de 100 x 100, mientras el navegador móvil se beneficia con la resolución adicional que muestra 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

Consulta la guía de mapas con ajustes de estilo.

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 íconos personalizados se especifican usando en el parámetro markers el siguiente descriptor:

• 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.

El parámetro icon se debe especificar usando una dirección URL (que debe tener codificación URL). Puedes usar URL creadas por servicios de acortamiento de URL como https://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.

El punto de anclaje de un ícono personalizado se establece como la parte inferior central 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:https://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 este carácter no se admite en una URL (consulta la nota anterior), al crear una dirección URL completamente válida para un gráfico debe transferirse como %7C. El resultado se inserta como una string 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 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:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://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:https://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.