Introducción
La API de Maps Static muestra 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 colocación de marcadores opcionales en diferentes ubicaciones del mapa. Además, puedes etiquetar tus marcadores con caracteres alfanuméricos.
Una imagen de la API de Maps Static está incorporada en el atributo src
de una etiqueta <img>
o en su equivalente en otros lenguajes de programación.
En este documento, se describe el formato requerido de las URLs de la API de Maps Static y los parámetros disponibles. También incluye algunas sugerencias y trucos para especificar tus URLs.
Antes de comenzar
Este documento está dirigido a desarrolladores de sitios web y dispositivos móviles que deseen 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 sobre 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 de 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 respetar el siguiente formato:
https://maps.googleapis.com/maps/api/staticmap?parameters
Si se accede a tu sitio web 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. También se recomienda usar HTTPS si tus solicitudes incluyen información sensible del usuario, como su ubicación:
https://maps.googleapis.com/maps/api/staticmap?parameters
Ya sea que uses HTTP o HTTPS, ciertos parámetros de URL son obligatorios y otros opcionales. Como es norma en las URLs, todos los parámetros se separan con el carácter et (&
). La lista de parámetros y sus valores posibles se enumeran en este documento.
La API de Maps Static define imágenes de mapa con los siguientes parámetros de 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 superficie 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, lo que determina el nivel de ampliació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 string con el 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 con un ancho inferior a 180 píxeles mostrarán un logotipo de Google de tamaño reducido. Este parámetro se ve afectado por el parámetroscale
. 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
muestra el doble de píxeles quescale=1
y, al mismo tiempo, mantiene la misma área de cobertura y nivel de detalle (es decir, el contenido del mapa no cambia). lo que es útil cuando desarrollas contenido para pantallas de alta resolución. El valor predeterminado es1
. Los valores aceptados son1
y2
. 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. Existen varios formatos posibles, incluidos GIF, JPEG y PNG. El formato que uses dependerá de cómo quieras presentar la imagen. JPEG normalmente 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 de maptype posibles, incluidosroadmap
,satellite
,hybrid
yterrain
. Para obtener más información, consulta Tipos de mapas de la API de Maps Static.language
(opcional) define el idioma que se usará para mostrar las etiquetas en los mosaicos de mapas. Ten en cuenta que este parámetro solo se admite para 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.region
(opcional): Define los bordes adecuados que se mostrarán, 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 la cobertura de Google Maps Platform para conocer las regiones admitidas.
Parámetros de atributos
map_id
(opcional) especifica el identificador para un mapa específico. El ID de mapa asocia un mapa con un diseño o componente determinado, y debe pertenecer al mismo proyecto que la clave de API que se usó 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 una definición de marcador único con parámetros separados por el carácter de barra vertical (|
). Se pueden colocar varios marcadores dentro del mismo parámetromarkers
siempre que tengan el mismo diseño. Puedes agregar marcadores adicionales de estilos diferentes agregando parámetrosmarkers
adicionales. Ten en cuenta que, si proporcionas marcadores para un mapa, no es necesario que especifiques los parámetroscenter
yzoom
(requeridos normalmente). Para obtener más información, consulta Marcadores de la API de Maps Static.path
(opcional) define una ruta única 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 separadas por el carácter de barra vertical (|
) o una polilínea codificada con el prefijoenc:
en la declaración de ubicación de la ruta. Para proporcionar rutas de acceso adicionales, agrega parámetrospath
adicionales. Ten en cuenta que, si proporcionas una ruta para un mapa, no es necesario que especifiques los parámetroscenter
yzoom
(requeridos normalmente). Para obtener más información, consulta Rutas de 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 asegurarte de que se muestren ciertos componentes o ubicaciones del mapa en la API de Maps Static.style
(opcional): Define un diseño personalizado para modificar la presentación de un componente específico (rutas, parques y otros componentes) del mapa. Este parámetro toma argumentosfeature
yelement
que identifican los componentes a los que se les aplicará el diseño y un conjunto de operaciones de diseño que se aplicarán a los componentes seleccionados. Puedes proporcionar varios estilos agregando parámetrosstyle
adicionales. Para obtener más información, consulta la guía sobre mapas con diseño.
Parámetros de clave y firma
key
(obligatorio): Te permite supervisar el uso de la API por parte de tu aplicación en Google Cloud Console y garantiza que Google pueda comunicarse contigo acerca de 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. Las solicitudes sin una firma digital podrían fallar. Para obtener más información, consulta Usa 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, es probable que no necesites URL más largas, a menos que crees mapas complicados con una gran cantidad de marcadores y rutas.
Uso de parámetros
La API de Maps Static es relativamente fácil de usar, ya que consiste solo en una URL parametrizada. En esta sección, se explica cómo utilizar estos parámetros para construir tus URLs.
Especificación de ubicaciones
La API de Maps Static debe poder identificar ubicaciones con precisión en el mapa, para enfocar el mapa en la ubicación correcta (mediante el parámetro center
) o colocar marcadores opcionales (con el parámetro markers
) en diferentes ubicaciones del mapa. La API de Maps Static usa números (valores de latitud y longitud) o strings (direcciones) para especificar estas ubicaciones. Estos valores identifican una ubicación geocodificada.
Varios parámetros (como markers
y path
) toman varias 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 números dentro de una cadena de texto separada por comas que tienen una precisión de 6 decimales. Por ejemplo, "40.714728,-73.998672" es un valor de geocódigo válido. Se ignora la precisión superior a 6 decimales.
Los valores de longitud se basan en la distancia desde Greenwich, Inglaterra, donde se encuentra el primer meridiano. Dado que Greenwich se encuentra a 51.477222 de latitud, 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á la solicitud por ser incorrecta.
Direcciones
La mayoría de las personas no hablan de latitudes y longitudes, sino que denotan ubicaciones con direcciones. 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 una latitud o 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 y longitud para usarlo en la colocación de marcadores o la especificación de ubicaciones. La cadena debe estar codificada como una URL, por lo que las direcciones como "Ayuntamiento, Nueva York, NY" deben convertirse en "City+Hall,New+York,NY", por ejemplo.
Ten en cuenta que las direcciones pueden reflejar ubicaciones precisas, como direcciones, polilíneas (como rutas con nombre) 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 centro de la dirección. Si tienes dudas acerca de cómo se puede geocodificar una dirección, puedes probarla mediante la 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
Niveles de zoom
Los mapas de Google Maps tienen un "nivel de zoom" entero que define la resolución de la vista actual. Los 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+
(hasta calles y edificios individuales) son posibles dentro de la vista predeterminada roadmap
. Los contornos de los edificios, si están disponibles, aparecen en el mapa cerca del nivel de zoom 17
. Este valor difiere de un área a otra y puede cambiar con el tiempo a medida que evolucionan los datos.
Google Maps establece el nivel de zoom 0
para abarcar toda la Tierra.
Cada nivel de zoom siguiente duplica la precisión tanto en la dimensión horizontal como en la vertical. Consulta la documentación de la API de Google Maps JavaScript para obtener más información al respecto.
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 mundo son más detallados que en otras.
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 su lugar.
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
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 del resultado del mapa en píxeles, cuando se multiplica por 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 con el 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
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
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
mostrará 200 píxeles por 200 píxeles. En un monitor de computadora LCD, que generalmente muestra alrededor de 100 píxeles por pulgada (PPP), un mapa de 200 x 200 tendrá aproximadamente 2 pulgadas en cada dimensión.
Sin embargo, los dispositivos móviles incluyen cada vez más pantallas de alta resolución con densidades de píxeles superiores a los 300 ppp que:
- Reducir el tamaño de una imagen de 200 x 200 píxeles a solo 0.7 de pulgada y renderizar las etiquetas y los íconos que son demasiado pequeños para leerlos
- Escala (zoom) la imagen para mejorar la legibilidad, lo que da como resultado una imagen difusa o pixelada.
Demasiado pequeño | Muy poco definida |
---|---|
![]() |
![]() |
Al desarrollar para dispositivos móviles, puedes usar el parámetro scale
de la API para mostrar imágenes de mapa de mayor resolución que resuelvan los problemas anteriores. El valor scale
se multiplica por el size
para determinar el tamaño de salida real de la imagen en píxeles, sin cambiar 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á la misma área de cobertura del mapa que una solicitud sin escala especificada, pero con el doble de píxeles en cada dimensión. Esto incluye rutas y etiquetas, de modo que se puedan leer en alta resolución, en pantallas pequeñas y cuando el navegador los ajuste.
150x150 | 150 x 150&escala=2 |
---|---|
![]() |
![]() |
Este tipo de imagen también funcionará bien en navegadores para computadoras cuando se inserten en una etiqueta img
o div
con la altura y el ancho establecidos mediante CSS. El navegador achicará la imagen al tamaño correcto sin perder calidad.
En esta tabla, se muestran tres solicitudes de imágenes diferentes.
- La primera es para una imagen de 100x100 sin valor de escala especificado. Se muestra correctamente en el escritorio, pero es demasiado pequeño para leerlo en un dispositivo móvil.
- La segunda duplica el tamaño del mapa. En el escritorio, el CSS se ajusta al elemento
img
especificado de 100 x 100, pero cuando se reduce el tamaño de la imagen, las rutas y las etiquetas se vuelven demasiado pequeñas. En el dispositivo móvil, la imagen tiene el tamaño correcto, pero, nuevamente, las rutas y las etiquetas son ilegibles. - La tercera solicitud es para un mapa de 100 x 100 con
scale=2
. La imagen se muestra con 200 px de detalle; el escritorio la reduce a escala perfectamente, de modo que no se distinga 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 |
Computadoras de escritorio (con height="100px" ywidth="100px" en laetiqueta img ) |
![]() |
![]() |
![]() |
Alta resolución (simulación) |
![]() |
![]() |
![]() |
Si quieres obtener más información sobre el desarrollo para pantallas de alta resolución y dispositivos móviles, te recomendamos lo siguiente:
- Compatibilidad con diferentes pantallas en la documentación para desarrolladores de Android.
- Las recomendaciones de Webkit.org para desarrollar sitios web con valores altos de DPI
- Compatibilidad con pantallas de alta resolución en la biblioteca para desarrolladores de iOS
Formatos de imagen
Las imágenes pueden mostrarse en varios formatos de gráficos web comunes: GIF, JPEG y PNG. El parámetro format
toma uno de los siguientes valores:
png8
opng
(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
Por lo general, jpg
y jpg-baseline
proporcionan el tamaño de imagen más pequeño, aunque lo hacen mediante una compresión "con pérdida", que puede degradar la imagen. gif
, png8
y png32
proporcionan una 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 antes y definen mejor su resolución a medida que llegan más datos. Esto permite que las imágenes se carguen rápidamente en páginas web y es el uso más general de JPEG en la actualidad. Sin embargo, algunos usos de JPEG requieren imágenes no progresivas (de referencia). 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 hoja de ruta estándar, como se muestra normalmente en el sitio web de Google Maps. Si no se especifica un valor demaptype
, la API de Maps Static publica mosaicosroadmap
de forma predeterminada.satellite
especifica una imagen satelital.terrain
especifica una imagen de 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 lugares en la imagen satelital.
En este ejemplo de código, puedes ver la diferencia entre los tipos de 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
Los mapas híbridos usan imágenes satelitales y características importantes del mapa de ruta para crear un mapa de combinación. En los siguientes ejemplos, se muestran los tipos de mapas satelitales y híbridos:
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
Mapas con diseños
Personaliza la presentación del mapa estándar de Google usando tus propios diseños. Consulta la guía sobre mapas con diseño.
Marcadores
El parámetro markers
define un conjunto de uno o más marcadores (marcadores del mapa) en un conjunto de ubicaciones. Cada marcador definido en una única declaración markers
debe exhibir el mismo estilo visual. Si deseas mostrar marcadores con estilos diferentes, deberás proporcionar varios parámetros de markers
con información de diseño por separado.
El parámetro markers
toma un conjunto de asignaciones de valor (descriptores de marcadores) con el siguiente formato:
markers=markerStyles|markerLocation1|
markerLocation2|...
, etcétera
El conjunto de markerStyles se declara al comienzo de la declaración markers
y consta de cero o más descriptores de estilo separados por el carácter de barra vertical (|
), seguidos de un conjunto de una o más ubicaciones también separadas por el carácter de barra vertical (|
).
Debido a que la información de diseño y la de ubicación están delimitadas 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 diseño 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 cuando se muestran los marcadores dentro de este descriptor. 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 establece ningún parámetrosize
, el marcador aparecerá en su tamaño predeterminado (normal).color:
(opcional) especifica un color de 24 bits (por 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 solo carácter alfanumérico uppercase del conjunto {A-Z, 0-9}. (El requisito de caracteres en mayúsculas es nuevo en esta versión de la API). Ten en cuenta que los marcadores de tamaño predeterminado ymid
son los únicos capaces de mostrar un parámetroalphanumeric-character
. Los marcadorestiny
ysmall
no pueden mostrar un carácter alfanumérico.
Ajuste del marcador
El valor 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 de escala predeterminado 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 ajuste. Por ejemplo, si el marcador se configura en scale:2
, puede ser más grande 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 ajuste. Cuando muestres mapas de mayor resolución, usa el escalamiento de los marcadores junto con la escala del mapa.
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. Estas ubicaciones se pueden especificar como valores de latitud/longitud o como direcciones. Estas 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 polilíneas o cadenas de direcciones legibles por humanos, la solicitud se limitará a 15 marcadores como máximo. Este límite solo se aplica a las ubicaciones de los marcadores que requieren geocodificación. No se aplica a las ubicaciones de los marcadores especificadas con coordenadas de latitud y longitud.
Los parámetros de 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 que se proporcionen los parámetros center
y zoom
. Sin embargo, si no se proporcionan estos parámetros, el servidor de la API de Maps Static construirá automáticamente una imagen que contenga los marcadores proporcionados.
(Consulta Posicionamiento implícito).
A continuación, se muestra una declaración de marcador de ejemplo. Ten en cuenta que definimos un conjunto de diseños 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
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 verde pequeño en "Delta Junction, AK" y un marcador amarillo mediano 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&signature=YOUR_SIGNATURE
Íconos personalizados
En lugar de usar í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
mediante una URL (que debe estar codificada como URL). Puedes usar URL creadas por servicios de acortamiento de URL como https://goo.gl
. La mayoría de los servicios de acortamiento de URL tienen la ventaja de codificar las URL automáticamente.
Puedes especificar un punto de anclaje para el icono personalizado. El punto de anclaje establece la manera en que se coloca el ícono en relación con las ubicaciones de 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 usando el descriptor anchor
junto con tu icon
. Configura anchor
como un punto x,y del ícono (como 10,5
), o como una alineación predefinida mediante 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 utilizar hasta cinco íconos personalizados únicos por solicitud. Esta limitación no significa que estés limitado a solo 5 ubicaciones marcadas en tu mapa. Cada ícono único se puede usar con más de una ubicación de markers
en tu mapa.
Formato de ícono:
- Las imágenes de los íconos pueden estar en formato PNG, JPEG o GIF, aunque se recomienda PNG.
- Los íconos pueden tener un tamaño máximo de hasta 4096 píxeles (64 x 64 para imágenes cuadradas).
Ejemplos de íconos personalizados
En el ejemplo 1, se crean íconos personalizados y se posicionan los íconos con anclajes.
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
En el ejemplo 2, se crean los mismos íconos personalizados que en el ejemplo 1, pero no se establecen las posiciones de los íconos con anclajes, ya que se basan en el anclaje predeterminado 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
Rutas de acceso a la API de Maps Static
El parámetro path
define un conjunto de una o más ubicaciones conectadas por una ruta para superponer en la imagen del mapa. El parámetro path
toma un conjunto de asignaciones de valor (descriptores de ruta de acceso) con el siguiente formato:
path=pathStyles|pathLocation1|pathLocation2|...
, etcétera
Ten en cuenta que ambos puntos de ruta están separados entre sí con el carácter de barra vertical (|
). Debido a que la información de estilo y la información de punto están delimitadas mediante 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 ruta 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 usarán cuando se muestre la ruta. Estos descriptores de estilo contienen las siguientes asignaciones de clave-valor:
weight:
(opcional) especifica el grosor de la ruta en píxeles. Si no se establece un parámetroweight
, la ruta aparecerá en su grosor predeterminado (5 píxeles).color:
(opcional) especifica un color como un valor hexadecimal de 24 bits (por ejemplo:color=0xFFFFCC
) o de 32 bits (por ejemplo:color=0xFFFFCCFF
), o 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) yFF
(completamente opaco). Ten en cuenta que las transparencias se admiten en los trazados, aunque no se admiten para los marcadores.fillcolor:
(opcional) indica que la ruta marca un área poligonal y especifica el color de relleno que se usará como una superposición dentro de 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 en el exterior del área llenada no se cerrará, a menos que proporciones específicamente la misma ubicación de inicio y finalización.geodesic:
(opcional) indica que la ruta solicitada debe interpretarse como una línea geodésica que sigue la curvatura de la Tierra. Cuando es falso, el trazado se renderiza como una línea recta en el espacio de la pantalla. La configuración predeterminada es "false".
Estas son algunas definiciones de ruta de ejemplo:
- Línea azul delgada con 50% de opacidad:
path=color:0x0000ff80|weight:1
- Línea roja continua:
path=color:0xff0000ff|weight:5
- Línea continua y gruesa blanca:
path=color:0xffffffff|weight:10
Estos estilos de trayecto son opcionales. Si deseas incluir atributos predeterminados, puedes omitir la definición de atributos de ruta de acceso. En ese caso, el primer "argumento" del descriptor de ruta de acceso consistirá en el primer punto (ubicación) declarado.
Puntos de ruta
Para dibujar una ruta, también se debe pasar al parámetro path
dos o más puntos. Luego, la API de Maps Static conectará la ruta 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 una ruta azul con un 50% de opacidad predeterminado desde Union Square NY hasta Times Square, NY.
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 la misma ruta en lugar de definir una línea roja sólida con un 100% de opacidad:
Los detalles de este parámetro path
son los 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, a la que se pasó una serie de intersecciones como ubicaciones:
Los detalles de este parámetro path
son los 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 trazado 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 una ruta como una polilínea codificada mediante el prefijo enc:
en la declaración de ubicación de path
.
En el siguiente ejemplo, se muestra 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¢er=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Al igual que con las rutas estándar, las rutas de polilínea codificadas 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¢er=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Viewports
Las imágenes pueden especificar un viewport mediante la especificación de 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 permanezcan visibles. Este parámetro también se puede combinar con marcadores o rutas existentes para definir una región visible. Si defines un viewport de esta manera, no es necesario 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
Posicionamiento implícito del mapa
Por lo general, debes especificar los parámetros de URL center
y zoom
para definir la ubicación y el nivel de zoom del mapa generado.
Sin embargo, si proporcionas 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, según la evaluación de la posición de estos elementos.
Si proporcionas dos o más elementos, la API de Maps Static determinará el centro y el nivel de zoom adecuados, y proporcionará márgenes generosos para los elementos que contenga. En este ejemplo, se muestra un mapa que contiene San Francisco, Oakland y San José, 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&signature=YOUR_SIGNATURE
Tamaños de imagen más grandes
Si necesitas imágenes con tamaños superiores a 640 × 640 píxeles (o 1,280 × 1,280 píxeles con un valor de escala de 2), comunícate con el equipo de asistencia al cliente y proporciona la siguiente información:
- Tu caso de uso y el motivo por el que necesitas imágenes de tamaño grande
- 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.
- Capturas de pantalla, simulaciones o muestras de cómo usarás imágenes de tamaño grande.
- Tu uso mensual estimado de imágenes de tamaño grande.
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 2048 x 2048 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 una buena idea comprobar si hay advertencias antes de lanzar una aplicación nueva. Ten en cuenta que las advertencias pueden no ser evidentes de inmediato porque aparecen en el encabezado HTTP. Para obtener más información, consulta la guía sobre errores y advertencias.