Comenzar

Introducción

La API de Maps Static devuelve una imagen (GIF, PNG o JPEG) en respuesta a una solicitud HTTP a través de una 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 la API de Maps Static se incorpora en el atributo src de una etiqueta <img>, o su equivalente en otros lenguajes de programación.

En este documento, se describe el formato obligatorio para las URLs de la API de Maps Static y los parámetros disponibles. También incluye algunas sugerencias para la especificación de tus URLs.

Antes de comenzar

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

Antes de comenzar a desarrollar con la API de Maps Static, revisa los requisitos de autenticación (necesitas una clave de API) y la información sobre uso y facturación de la API (debes habilitar la facturación en tu proyecto).

Parámetros de URL

Una URL de la API de Maps Static debe tener 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 la API de Maps Static 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 URLs, todos los parámetros se separan con el signo et (&). La lista de parámetros y sus posibles valores se enumeran en este documento.

La API de Maps Static define las 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 una cadena de dirección (p.ej., "city hall, new york, ny") que identifica una ubicación única sobre la faz de la tierra. Para obtener más información, consulta Ubicaciones.
  • 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.

Parámetros de mapas

  • size (obligatorio) define las dimensiones rectangulares de la imagen del mapa. Este parámetro toma una cadena del formato {horizontal_value}x{vertical_value}. Por ejemplo, 500x400 define un mapa de 500 píxeles de ancho 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; 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 que se muestran. 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 es útil cuando se desarrolla para pantallas de alta resolución. El valor predeterminado es 1. Los valores aceptados son 1 y 2. Consulta Valores de escala para obtener más información.
  • format (opcional) define el formato de la imagen resultante. De forma predeterminada, la API de Maps Static 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á. Hay varios valores posibles de maptype, incluidos roadmap, satellite, hybrid y terrain. Para obtener más información, consulta Maptypes de la API de Maps Static.
  • 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'). Consulta los detalles de cobertura de Google Maps Platform para conocer las regiones admitidas.

Parámetros de funciones

  • map_id (opcional) especifica el identificador de un mapa específico. El ID de mapa asocia un mapa con un diseño o una función en particular, y debe pertenecer al mismo proyecto que la clave de API que se usa para inicializar el mapa. Para obtener más información, consulta Cómo usar los IDs de mapa.
  • 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. Para agregar más marcadores de diferentes estilos, agrega más parámetros markers. Ten en cuenta que, si proporcionas marcadores para un mapa, no es necesario que especifiques los parámetros center y zoom (generalmente obligatorios). Para obtener más información, consulta Marcadores de la API de Maps Static.
  • path (opcional) define un solo trayecto de 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 (|) o una polilínea codificada con el prefijo enc: dentro de la declaración de ubicación de la ruta. Puedes proporcionar más trayectos al agregar parámetros path adicionales. Ten en cuenta que, si proporcionas una ruta para un mapa, no es necesario que especifiques los parámetros center y zoom (generalmente obligatorios). Para obtener más información, consulta Rutas de la API de Maps Static.
  • 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 la API de Maps Static.
  • style (opcional) define un estilo personalizado para alterar la presentación de una característica específica (calles, parques y otras características) 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 diseño aplicado.

Parámetros de clave y firma

  • key (obligatorio) te permite supervisar el uso de la API de tu aplicación en la consola de Google Cloud y garantiza que Google pueda comunicarse contigo en relación con tu aplicación si es necesario. Para obtener más información, consulta Cómo usar claves de API con la API de Maps Static.
  • 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. Es posible que las solicitudes sin una firma digital no se realicen correctamente. Para obtener más información, consulta Cómo usar una firma digital.

Restricción de tamaño de URL

Las URLs de la API de Maps Static tienen una limitación de tamaño de 16,384 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.

Uso de parámetros

La API de Maps Static es relativamente fácil de usar, ya que consiste únicamente en una URL con parámetros. En esta sección, se explica cómo usar estos parámetros para construir tus URLs.

Especificación de ubicaciones

La API de Maps Static 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. La API de Maps Static usa números (valores de latitud y longitud) o cadenas (direcciones) para especificar estas ubicaciones. Estos 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 valor de geocódigo 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 que Greenwich se encuentra en la latitud 51.477222, podemos ingresar un valor center de 51.477222,0 para centrar el mapa en Greenwich:

Greenwich, Inglaterra

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 con addresses. El proceso de convertir una dirección en un punto geográfico se conoce como geocodificación, y el servicio de la API de Maps Static 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 la API de Maps Static un valor de latitud/longitud para usar en la colocación de marcadores o la especificación de ubicaciones. La cadena debe estar codificada como URL, de modo que direcciones como “City Hall, New York, NY” se conviertan 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 de la API de Maps Static usará el punto central de la línea o 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 con esta Utilidad de geocodificación.

En el siguiente ejemplo, se genera una imagen de mapa estática para Berkeley, California:

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

Berkeley, CA

Niveles de zoom

Los mapas de Google Maps tienen un nivel de zoom en números enteros que define la resolución de la vista actual. En la vista predeterminada roadmap, se pueden aplicar 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, aparecen 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 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 la API de Google Maps JavaScript.

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 detallados que en otras ubicaciones.

Si envías una solicitud para un nivel de zoom en el que no existen mosaicos de mapas, la API de Maps Static mostrará una imagen en blanco.

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

En este ejemplo, se solicitan dos mapas de Manhattan con el mismo valor de 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Manhattan más alejado  Manhattan más cerca

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 es 1 de forma predeterminada).

En esta tabla, se muestran los valores máximos permitidos para el parámetro size en cada valor de scale.

scale=1 scale=2
640x640 640x640 (devuelve 1280 x 1280 píxeles)

En este ejemplo, se 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&signature=YOUR_SIGNATURE

Ecuador

En este ejemplo, se 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&signature=YOUR_SIGNATURE

Mapa pequeño del Ecuador

Valores de escala

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

Sin embargo, 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 200 x 200 píxeles a solo 0.7 de pulgada y exhiben las etiquetas y los íconos 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

Cuando desarrolles para dispositivos móviles, puedes usar el parámetro scale de la API para devolver imágenes de mapa de mayor resolución que resuelvan los problemas anteriores. El valor de scale se multiplica por el de 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 y 2.

Por ejemplo, un valor de escala de 2 mostrará el mismo área de cobertura del mapa que 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.

En esta tabla, se muestran 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 100 x 100 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 × 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 que el navegador para dispositivos móviles se beneficia de la resolución adicional que muestra la API.
Solicitudes de imágenes
Dispositivo 100x100 200x200 100x100&scale=2
Escritorio
(con height="100px" y
width="100px" en la
etiqueta img)
Alta resolución
(simulación)

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

Formatos de imagen

Las imágenes pueden devolverse en varios 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.

En estos ejemplos, se solicitan mapas en los formatos gif y png:

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

jpg y jpg-baseline suelen proporcionar el tamaño de imagen más pequeño, aunque lo hacen a través de una compresión “con pérdida”, que puede degradar la imagen. gif, png8 y png32 proporcionan compresión sin pérdidas.

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 se carguen rápidamente en páginas web y es el uso más común de JPEG en la actualidad. Sin embargo, algunos usos de JPEG 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

La API de Maps Static crea mapas en varios formatos, que se indican a continuació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, la API de Maps Static entrega mosaicos de roadmap de forma predeterminada.
  • satellite especifica una imagen satelital.
  • terrain especifica una imagen de un mapa de relieve físico que muestra el terreno y la 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 este 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Mapa normal de Manhattan  Mapa de terreno de Manhattan

Los mapas híbridos usan imágenes satelitales y características prominentes del mapa de ruta para crear un mapa combinado. En los siguientes ejemplos, se 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Mapa satelital de Manhattan  Mapa de terreno de Manhattan

Mapas con diseños

Personaliza la presentación del mapa estándar de Google aplicando tus propios estilos. Consulta la guía de mapas con diseño.

Marcadores

El parámetro markers define un conjunto de uno o más marcadores (pines de mapa) 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 declara 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 marcador. Una vez que el servidor de la API de Maps Static 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 del conjunto {tiny, mid, small}. Si no se establece 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 conjunto {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Ten en cuenta que las transparencias (especificadas con 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 único 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 que pueden mostrar un parámetro alphanumeric-character. Los marcadores tiny y small no pueden mostrar un carácter alfanumérico.

Escalamiento de marcadores

El valor de scale se multiplica por el tamaño de la imagen del marcador para producir el tamaño de salida real del marcador en píxeles. El valor predeterminado de escala es 1; los valores aceptados son 1, 2 y 4.

El límite de tamaño de píxeles en las imágenes se aplica después de aplicar el escalamiento. Por ejemplo, si el marcador se establece en scale:2, puede ser mayor que el tamaño máximo de 4,096 píxeles, siempre que se reduzca a menos de 4,096 píxeles después del escalamiento. Usa el escalamiento de marcadores junto con el escalamiento de mapas cuando muestres mapas de mayor resolución.

Ubicaciones de los marcadores

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

Nota: Si decides especificar las ubicaciones de los marcadores con un método que requiera geocodificación, como cadenas de direcciones legibles por humanos o polilíneas, la solicitud se limitará a un máximo de 15 marcadores. Este límite solo se aplica a las ubicaciones de marcadores que requieren la geocodificación. No corresponde a las ubicaciones de marcadores especificadas con coordenadas de latitud y longitud.

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, siempre y cuando se proporcionen los parámetros center y zoom. Sin embargo, si no se proporcionan esos parámetros, el servidor de la API de Maps Static construirá automáticamente una imagen que contenga los marcadores proporcionados. (Consulta Posicionamiento implícito).

Aquí se muestra un ejemplo de declaración de marcador. 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&signature=YOUR_SIGNATURE

Tres códigos postales de Brooklyn

Para definir marcadores con estilos diferentes, debemos proporcionar varios 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 amarillo mediano con la etiqueta "C" en "Tok, AK". Estos marcadores se muestran en este 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&signature=YOUR_SIGNATURE

Tres ciudades de Alaska, marcadores diferentes

Íconos personalizados

En lugar de usar los íconos de marcadores de Google, puedes usar tus propios íconos personalizados. Los íconos personalizados se especifican con el descriptor icon en el parámetro markers. Por ejemplo:

markers=icon:URLofIcon|markerLocation

Especifica el icon con una URL (que debe estar codificada como URL). Puedes usar URLs creadas por servicios de acortamiento de URLs, 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.

Puedes especificar un punto de anclaje para el ícono personalizado. El punto de anclaje establece cómo se coloca el ícono en relación con las ubicaciones markers especificadas. De forma predeterminada, el punto de anclaje de un ícono personalizado es la parte inferior central de la imagen del ícono. Puedes especificar un punto de anclaje diferente con el descriptor anchor junto con tu icon. Establece anchor como un punto x,y del ícono (como 10,5) o como una alineación predefinida con uno de los siguientes valores: top, bottom, left, right, center, topleft, topright, bottomleft o bottomright. Por ejemplo:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

Puedes usar hasta cinco íconos personalizados únicos por solicitud. Esta limitación no significa que solo puedas marcar 5 ubicaciones en tu mapa. Cada ícono único se puede usar con más de una ubicación markers en tu mapa.

Formato del ícono:

  • Las imágenes de íconos pueden tener formato PNG, JPEG o GIF, aunque se recomienda PNG.
  • Los íconos pueden tener un tamaño máximo de 4,096 píxeles (64 × 64 para imágenes cuadradas).
Ejemplos de íconos personalizados

En el ejemplo 1, se crean íconos personalizados y se posicionan con anclas.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Tres ciudades de Australia, diferentes íconos personalizados posicionados con anclas.

En el ejemplo 2, se crean los mismos íconos personalizados que en el ejemplo 1, pero no se configuran las posiciones de los íconos con anclas, sino que se usa el ancla predeterminada de la parte inferior central.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Tres ciudades de Australia, diferentes íconos personalizados con posicionamiento predeterminado.

Rutas de la API de Maps Static

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 de la ruta 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 ruta. Una vez que el servidor de la API de Maps Static encuentra una ubicación en el descriptor de ruta, se da por sentado que todos los demás parámetros de ruta también son ubicaciones.

Estilos de ruta

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 establece un parámetro weight, la ruta 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 varía 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 la API de Maps Static unirá automáticamente el primer y el último punto. Sin embargo, ten en cuenta que cualquier trazo 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 el espacio de la pantalla. La configuración predeterminada es "false".

Estos son algunos ejemplos de definiciones de ruta:

  • Línea azul delgada con 50% de opacidad: path=color:0x0000ff80|weight:1
  • Línea roja continua: 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 de ruta

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

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

Trayecto desde Union Square hasta Times Square

Los detalles del parámetro path son los siguientes:

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

En el siguiente ejemplo, se define el mismo trayecto en lugar de definir una línea sólida roja con un 100% de opacidad:

Trayecto desde Union Square hasta Times Square

Las especificaciones de este parámetro path son las siguientes:

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

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

Trayecto desde Union Square hasta Times Square

Las especificaciones de este parámetro path son las siguientes:

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 recorrido como una polilínea codificada usando el prefijo enc: dentro de la declaración de ubicación de path.

En el siguiente ejemplo, se describe el recorrido 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&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Autopista de Alaska

Al igual que con los trayectos estándar, los trayectos en forma de polilínea codificada también pueden demarcar áreas poligonales si se pasa 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&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Polilínea codificada de Brooklyn con firma

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 de la API de Maps Static 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&signature=YOUR_SIGNATURE

Mapa de Cambridge

Posicionamiento implícito del mapa

Normalmente, debes especificar los parámetros de URL center y zoom para definir la ubicación y el nivel de zoom del mapa que generaste. Sin embargo, si proporcionas los parámetros markers, path o visible, puedes permitir que la API de Maps Static determine el centro y el nivel de zoom correctos de forma implícita, en función de una evaluación de la posición de estos elementos.

Si proporcionas dos o más elementos, la API de Maps Static determinará un centro y un nivel de zoom correctos, y proporcionará márgenes generosos para los elementos contenidos. En este ejemplo, se muestra un mapa que contiene San Francisco, Oakland y San José, California:

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&signature=YOUR_SIGNATURE

Hoja de ruta

Tamaños de imagen más grandes

Si necesitas imágenes con tamaños superiores a 640 x 640 píxeles (o 1280 x 1280 píxeles con un valor de escala de 2), comunícate con el equipo de asistencia y proporciona la siguiente información:

  1. Tu caso de uso y por qué necesitas imágenes de gran tamaño
  2. Si consideraste usar otras APIs de Google Maps Platform (API de Maps JavaScript, API de Maps Embed, SDK de Maps para Android o SDK de Maps para iOS) y por qué no satisfacen tus necesidades
  3. Capturas de pantalla, simulaciones o muestras de cómo usarás las imágenes de gran tamaño.
  4. Es tu uso mensual estimado de imágenes de gran tamaño.

Revisaremos tu solicitud en función de la información que proporciones y determinaremos si tu caso de uso cumple con las Condiciones del Servicio de Google Maps Platform.

El tamaño máximo que podemos proporcionar es de 2,048 por 2,048 píxeles.

Solución de problemas y asistencia

Para obtener más información sobre el uso de la API de Maps Static, consulta la página de asistencia.

La API de Maps Static 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. También es conveniente que compruebes si hay advertencias antes de lanzar una aplicación nueva. Ten en cuenta que es posible que las advertencias no sean aparentes de inmediato, ya que aparecen en el encabezado HTTP. Para obtener más información, consulta la guía de errores y advertencias.