Comenzar

Desarrolladores del Espacio Económico Europeo (EEE)

Si tu dirección de facturación se encuentra en el Espacio Económico Europeo, a partir del 8 de julio de 2025, se aplicarán las Condiciones del Servicio de Google Maps Platform para el EEE al uso que hagas de los Servicios. Obtén más información. Además, ya no se devolverá cierto contenido de la API de Maps Static. Obtén más información.

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. En 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 posición de los marcadores opcionales en las ubicaciones del mapa. Además, puedes etiquetar tus marcadores con 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 de las URLs de la API de Maps Static y los parámetros disponibles. También se indican 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. Se 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 sobre el uso y la 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 se accede a tu sitio web a través de HTTPS, también debes cargar las imágenes de la API de Maps Static por medio de HTTPS para evitar las alertas de seguridad del navegador. También se recomienda 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, algunos parámetros de URL son obligatorios y otros son opcionales. Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&). En este documento, se enumeran la lista de parámetros y sus valores posibles.

Importante: En el análisis de los parámetros de URL, se usan ejemplos que, para mayor claridad, se proporcionan en su formato previo al escape. Antes de enviar cualquier solicitud a la API, sus parámetros deben estar codificados en formato URL de forma correcta. Por ejemplo, muchos parámetros usan un carácter de barra vertical (|) como separador, que se debe codificar como %7C en la URL final, como en el ejemplo rápido que se encuentra en la parte superior de este documento. Para obtener más información, consulta Cómo crear una URL válida.

La API de Maps Static define las imágenes de mapas con los siguientes parámetros de URL:

Parámetros de ubicación

• center (obligatorio si no hay marcadores) define el centro del mapa, equidistante de todos los bordes del mapa. Este parámetro toma una ubicación como un par de coordenadas {latitud,longitud} separadas por comas (p.ej., "40.714728,-73.998672") o una dirección de cadena (p.ej., "city hall, new york, ny") que identifica una ubicación única en la superficie de la Tierra. Para obtener más información, consulta Ubicaciones.
• zoom (obligatorio si no hay marcadores) define el nivel de zoom del mapa, 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 del mapa

• size (obligatorio) define las dimensiones rectangulares de la imagen del mapa. Este parámetro toma una cadena 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. En los mapas con un ancho inferior a 180 píxeles, se mostrará un logotipo de Google de tamaño reducido. Este parámetro se ve afectado por el parámetro scale. El tamaño final del resultado es el producto de los valores de tamaño y escala.
• scale (opcional) afecta la cantidad de píxeles que se devuelven. scale=2 devuelve el doble de píxeles que scale=1, pero conserva la misma área de cobertura y el mismo nivel de detalle (es decir, el contenido del mapa no cambia). Esto es útil cuando desarrollas 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. Existen varios formatos posibles, incluidos los tipos GIF, JPEG y PNG. El formato que uses dependerá de cómo quieras presentar la imagen. Por lo general, JPEG 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 creará. Existen varios valores posibles para maptype, incluidos roadmap, satellite, hybrid y terrain. Para obtener más información, consulta Tipos de mapas de la API de Maps Static.
• colorscheme (opcional) define el esquema de colores del mapa. Los valores aceptados son light (predeterminado) y dark. El esquema de colores oscuros se aplica a los tipos de mapas roadmap y terrain. Para obtener más información, consulta Obtén información sobre los modos y los tipos de mapas.
• language (opcional) define el idioma que se usará para mostrar las etiquetas en los mosaicos del mapa. Ten en cuenta que este parámetro solo se admite para algunas tarjetas de países. Si el idioma específico solicitado no se admite para el conjunto de tarjetas, se usará el idioma predeterminado de ese conjunto de tarjetas.
• region (opcional) define los límites adecuados que se deben mostrar según las sensibilidades geopolíticas. Acepta un código de región especificado como un valor ccTLD ("dominio de nivel superior") de dos caracteres. 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 un componente 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 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 sola definición de marcador con parámetros separados por el carácter de barra vertical (|). Se pueden colocar varios marcadores dentro del mismo parámetro markers, siempre que tengan el mismo estilo. Puedes agregar marcadores adicionales de diferentes estilos agregando parámetros markers adicionales. Ten en cuenta que, si proporcionas marcadores para un mapa, no necesitas especificar los parámetros center y zoom (que normalmente son obligatorios). Para obtener más información, consulta Marcadores de la API de Maps Static.
• path (opcional) define una sola ruta de acceso 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 prefijo enc: dentro de la declaración de ubicación de la ruta. Puedes proporcionar rutas adicionales agregando parámetros path adicionales. Ten en cuenta que, si proporcionas una ruta de acceso para un mapa, no necesitas especificar los parámetros center y zoom (que normalmente son 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 asegurarte de que se muestren ciertas funciones o ubicaciones del mapa en la API de Maps Static.
• style (opcional) define un estilo personalizado para modificar la presentación de un componente específico (rutas, parques y otros componentes) del mapa. Este parámetro toma los argumentos feature y element que identifican los componentes a los que se 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ámetros style 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 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 generan solicitudes con tu clave de API estén autorizados para hacerlo. Es posible que las solicitudes sin una firma digital fallen. Para obtener más información, consulta Usa una firma digital.

Restricción de tamaño de la URL

Las URLs de la API de Maps Static están restringidas a un tamaño de 16,384 caracteres. En la práctica, es probable que no necesites URLs más largas que esta, a menos que produzcas mapas complicados con una gran cantidad de marcadores y rutas de acceso.

Uso de parámetros

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

Especificación de ubicaciones

La API de Maps Static debe poder identificar con precisión las ubicaciones en el mapa, tanto para enfocar el mapa en la ubicación correcta (con el parámetro center) como para colocar marcas de posición opcionales (con el parámetro markers) en las 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.

Varios parámetros (como markers y path) admiten 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 tiene una precisión de 6 decimales. Por ejemplo, "40.714728,-73.998672" es un valor de código geográfico válido. Se ignora la precisión más allá de los 6 decimales.

Los valores de longitud se basan en su distancia desde Greenwich, Inglaterra, donde se encuentra el meridiano de Greenwich. Como Greenwich se encuentra en la latitud 51.477222, podemos ingresar un valor de 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 en la superficie de la Tierra. Las latitudes pueden tomar cualquier valor entre -90 y 90, mientras que los valores de longitud pueden tomar cualquier valor entre -180 y 180. Si especificas un valor de latitud o longitud no válido, se rechazará tu solicitud como incorrecta.

Direcciones

La mayoría de las personas no hablan en términos de latitud y longitud, sino que indican 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 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 tener una codificación de URL, por lo que las direcciones como "City Hall, New 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. En el caso de 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 sobre cómo se puede geocodificar una dirección, puedes probarla con esta utilidad de geocodificación.

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

En el siguiente ejemplo, se genera una imagen de mapa estático 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 las calles y los edificios individuales) son posibles dentro de la vista predeterminada de roadmap. Los contornos de los edificios, cuando están disponibles, aparecen en el mapa alrededor del nivel de zoom 17. Este valor varía 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 sucesivo duplica la precisión en las dimensiones horizontal y vertical. Puedes obtener más información sobre cómo hacerlo en la documentación de la API de Maps JavaScript de Google Maps.

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 de algunas partes del mundo son más detallados que los de otras.

Si envías una solicitud para un nivel de zoom en el que no existen mosaicos de mapa, la API de Maps Static devolverá 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 los 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 de salida del mapa en píxeles, cuando se multiplica por el valor de 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 se devolverá como 200 píxeles por 200 píxeles. En un monitor LCD de computadora, que suele mostrar 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 300 ppi, que pueden hacer lo siguiente:

• Reducir el tamaño de una imagen de 200 x 200 píxeles a solo 0.7 pulgadas, lo que hace que las etiquetas y los íconos sean demasiado pequeños para leerlos
• Escalar (acercar) la imagen para mejorar la legibilidad, lo que genera una imagen borrosa o pixelada

Demasiado pequeña	Muy poco definida

Cuando desarrollas para dispositivos móviles, puedes usar el parámetro scale de la API para mostrar imágenes de mapas de mayor resolución que resuelvan los problemas anteriores. El valor de scale se multiplica por 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 devolverá 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 las rutas y las etiquetas, de modo que sean legibles en pantallas de alta resolución y tamaño pequeño, así como cuando el navegador las escala.

150x150	150x150&scale=2

Este tipo de imagen también tendrá un buen rendimiento en los navegadores para computadoras cuando se inserte en una etiqueta img o div con la altura y el ancho establecidos con CSS. El navegador reducirá 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 la computadora, pero es demasiado pequeña para leerla en un dispositivo móvil.
• La segunda duplica el tamaño del mapa. En el escritorio, el CSS lo ajusta al elemento img de 100 x 100 especificado, pero, al reducir 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, de nuevo, las rutas y las etiquetas son ilegibles.
• La tercera solicitud es para un mapa de 100 x 100 con scale=2. La imagen se devuelve con 200 px de detalle; la computadora de escritorio la reduce perfectamente, de modo que no se distingue de la solicitud original de 100 x 100, mientras que el navegador para dispositivos móviles se beneficia de la resolución adicional que devuelve la API.

Solicitudes de imágenes
Dispositivo	100x100	200x200	100x100&scale=2
Computadora de escritorio (con height="100px" y width="100px" en la etiqueta img)
Alta resolución (simulada)

Nota: Las plataformas para dispositivos móviles, como Android y iOS, permiten que las apps admitan pantallas de alta resolución especificando imágenes independientes para cada resolución. El parámetro scale facilita la solicitud de una imagen de mapa para una pantalla de resolución estándar y el mapa correspondiente para una pantalla de alta resolución, simplemente configurando scale=1 y scale=2, respectivamente.

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:

• Compatibilidad con diferentes pantallas en la documentación para desarrolladores de Android
• Recomendaciones de Webkit.org para desarrollar sitios web con DPI alto.
• Supporting High-Resolution Screens en la biblioteca para desarrolladores de iOS

Formatos de imagen

Las imágenes se pueden mostrar en varios formatos de gráficos web comunes: GIF, JPEG y PNG. El parámetro format toma 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 gruesa antes y, luego, mejoran la resolución de la imagen a medida que llegan más datos. Esto permite que las imágenes se carguen rápidamente en las páginas web y es el uso más extendido 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 no es 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 se muestra normalmente en el sitio web de Google Maps. Si no se especifica ningún 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 mapa de relieve físico, que muestra el terreno y la vegetación.
• hybrid especifica una combinación de la imagen satelital y la del mapa de ruta, que muestra una capa transparente de las calles principales y los nombres de lugares sobre la imagen satelital.

Puedes ver la diferencia entre los tipos de mapa de ruta y de terreno en este ejemplo de código.

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 funciones destacadas de mapas de ruta para crear un mapa combinado. En los siguientes ejemplos, se muestran los tipos de mapas satelitales e 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 aplicando tus propios estilos. Consulta la guía sobre 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 marcador definido en una sola declaración markers debe tener el mismo estilo visual. Si deseas mostrar marcadores con diferentes estilos, deberás proporcionar varios parámetros markers con información de estilo independiente.

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

markers=markerStyles|markerLocation1| markerLocation2|..., etcétera.

El conjunto de markerStyles se declara al principio 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 (|).

Dado que tanto la información de estilo como la información de ubicación se delimitan con 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 marcador, se supone que todos los demás parámetros de marcador también son ubicaciones.

Estilos de marcadores

El conjunto de descriptores de estilo de marcador es una serie de asignaciones de valores separadas por el carácter de barra vertical (|). Este descriptor de estilo define los atributos visuales que se usarán cuando se muestren los marcadores dentro de este descriptor de marcador. 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 ningún parámetro size, 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 en las rutas de acceso.

• label: (opcional) especifica un solo carácter alfanumérico en mayúscula del conjunto {A-Z, 0-9}. (El requisito de caracteres en mayúscula es nuevo en esta versión de la API). Ten en cuenta que los marcadores predeterminados y de tamaño 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.

Nota: En lugar de usar estos marcadores, puedes usar tu propio ícono personalizado. (Para obtener más información, consulta Íconos personalizados).

Ajuste de escala de los 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 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 que se aplica el escalamiento. Por ejemplo, si el marcador se establece 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 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 direcciones. Estas ubicaciones se separan con el carácter de barra vertical (|).

Nota: Si eliges 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 geocodificación. No se aplica a las ubicaciones de 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, ese 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 creará automáticamente una imagen que contenga los marcadores proporcionados. (consulta Posicionamiento implícito).

A continuación, 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

Para definir marcadores con diferentes estilos, 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 los íconos de marcador 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 URLs tienen la ventaja de codificar las URLs 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 de markers especificadas. De forma predeterminada, el punto de anclaje de un ícono personalizado es el centro de la parte inferior de la imagen del ícono. Puedes especificar un punto de anclaje diferente con el descriptor anchor junto con tu icon. Establece el 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 tener 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 del ícono:

• Las imágenes de íconos pueden estar en formato PNG, JPEG o GIF, aunque se recomienda el formato 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 los posiciona 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, sino que se usa 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 la API de Maps Static

El parámetro path define un conjunto de una o más ubicaciones conectadas por una ruta de acceso para superponer en la imagen del mapa. El parámetro path acepta un conjunto de asignaciones de valores (descriptores de ruta de acceso) con el siguiente formato:

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

Ten en cuenta que ambos puntos de la ruta de acceso se separan entre sí con el carácter de barra vertical (|). Debido a que tanto la información de estilo como la de los puntos se delimitan con el carácter de barra vertical, la información de estilo debe aparecer primero en cualquier descriptor de ruta de acceso. Una vez que el servidor de la API de Maps Static encuentra una ubicación en el descriptor de ruta, se supone que todos los demás parámetros de ruta también son ubicaciones.

Estilos de ruta de acceso

El conjunto de descriptores de estilo de ruta de acceso es una serie de asignaciones de valores 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 el parámetro weight, la ruta de acceso aparecerá con 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 bien 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 se admiten transparencias en las rutas, pero no en los marcadores.

• fillcolor: (opcional) indica que la ruta delimita un área poligonal y especifica el color de relleno que se usará como superposición dentro de esa área. No es necesario que el conjunto de ubicaciones que se indica a continuación sea un bucle "cerrado", ya que el servidor de la API de Maps Static unirá automáticamente el primer punto y el último. Sin embargo, ten en cuenta que cualquier trazo en el exterior del área rellenada 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, la ruta se renderiza como una línea recta en el espacio de la pantalla. La configuración predeterminada es "false".

Estos son algunos ejemplos de definiciones de rutas de acceso:

• Línea azul delgada, 50% de opacidad: path=color:0x0000ff80|weight:1
• Línea roja continua: path=color:0xff0000ff|weight:5
• Línea blanca gruesa continua: path=color:0xffffffff|weight:10

Estos estilos de trayecto son opcionales. Si deseas usar los atributos predeterminados, puedes omitir la definición de los 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 deben pasar dos o más puntos al parámetro path. Luego, la API de Maps Static conectará la ruta a lo largo de 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 una opacidad predeterminada del 50% 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, pero se define una línea roja continua 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 y se pasa 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 la ruta de acceso 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 con el prefijo enc: dentro de la declaración de ubicación de la path.

En el siguiente ejemplo, se describe el recorrido de la autopista de Alaska desde Dawson Creek, Columbia Británica, hasta Delta Junction, Alaska, 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

Al igual que con las rutas estándar, las rutas de polilíneas codificadas también pueden delimitar á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

Viewports

Las imágenes pueden especificar un viewport indicando las ubicaciones visibles con el parámetro visible. El parámetro visible indica al servicio de la API de Maps Static que cree 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). Definir un viewport de esta manera evita la necesidad de especificar un nivel de zoom exacto.

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

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 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, 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á un centro y un nivel de zoom adecuados, y proporcionará márgenes amplios para los elementos incluidos. 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

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:

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, bocetos o ejemplos de cómo usarás las imágenes de gran tamaño
4. Es tu uso mensual estimado para 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 2,048 × 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 emitir un error o una advertencia cuando algo sale mal. En particular, debes verificar si hay advertencias si notas que falta algo en el mapa. También es una buena idea verificar si hay advertencias antes de lanzar una aplicación nueva. Ten en cuenta que es posible que las advertencias no se vean de inmediato, ya que aparecen en el encabezado HTTP. Para obtener más información, consulta la guía sobre errores y advertencias.