SDK de MapTiler: Mapas JavaScript con esteroides

Publicado el 05 de mayo de 2023

¿Qué es el SDK de MapTiler?

MapTiler ha estado creando un completo ecosistema cartográfico para empresas, que incluye herramientas de procesamiento avanzado como Desktop/Engine, servicios de almacenamiento y procesamiento de datos, plugins QGIS, servicios de geocodificación y geolocalización, bibliotecas JavaScript, herramientas de estilización de mapas y mucho más. Hasta ahora, dependíamos principalmente de la comunidad de código abierto y de MapLibre para mostrar mapas en la web. Si bien esto continuará, estamos pasando al siguiente nivel mediante la creación de nuestro propio SDK para integrar mejor nuestros mapas con su sitio web. El SDK de MapTiler es un nuevo SDK de JavaScript y TypeScript adaptado a MapTiler Cloud.

En este artículo, daremos más detalles sobre nuestro nuevo SDK, cubriendo su público objetivo, construcción, características notables, cómo empezar, y nuestra visión para su futuro.

¿Por qué crear nuestro propio SDK?

Antes de empezar a desarrollar el SDK, mantuvimos numerosos debates internos sobre su creación: ¿Debemos construir algo totalmente nuevo desde cero o basarlo en una solución ya existente? En caso afirmativo, ¿qué opciones son las más adecuadas?

Desde el punto de vista empresarial, queríamos una solución que no requiriera un año de desarrollo, ya que la función principal del SDK es facilitar otras ideas (tanto nuestras como tuyas). En aquel momento, ya teníamos algunos proyectos que se integrarían bien con un SDK. Rápidamente, MapLibre GL surgió como el principal candidato. Es rápido, está bien mantenido y tanto nosotros como nuestra comunidad ya estábamos familiarizados con él, lo que lo convertía en la base ideal para nuestro proyecto.

Ahora te preguntarás: "¿Por qué no hacer aportaciones directas a MapLibre?". - Hay dos razones principales para ello:

• Queremos que nuestro SDK esté totalmente integrado con nuestra pila de datos y servicios para proporcionar una experiencia de desarrollo fluida y sin fricciones. Sería inapropiado que MapLibre, un proyecto mantenido por la comunidad, tuviera una fuerte opinión hasta la médula sobre un proveedor de datos específico.

• Como empresa, MapTiler tiene su propia hoja de ruta para el lanzamiento de productos. Tenemos características que queremos lanzar antes, y no queremos interrumpir o influir en la dirección del desarrollo impulsado por la comunidad de MapLibre con nuestra línea de tiempo.

En cuanto al segundo punto, nuestro SDK se publica bajo una licencia de código abierto (BSD-3), por lo que algunos de sus componentes podrían incorporarse a MapLibre en un futuro próximo.

Otra pregunta que anticipamos fue sobre la compatibilidad: "Si tengo mis datos (por ejemplo, tilesets, archivos GeoJSON, etc.) en mi propio servidor o en un servidor de un proveedor de datos que no sea MapTiler, ¿funcionarán con MapTiler SDK?". - Sí, ¡definitivamente puedes seguir utilizando tus datos!

Desde el primer día, nos aseguramos de que nuestro SDK, si se basa en MapLibre, siga siendo totalmente compatible con MapLibre. Nuestro SDK añade accesos directos y funciones, pero usted no está obligado a utilizarlos. Por lo tanto, siéntase libre de utilizar sus datos de un servidor personalizado o datos de otra fuente; ¡depende totalmente de usted!

Un último punto a tratar antes de profundizar en nuestro SDK es la evolución de MapLibre. Planeamos mantener activamente el SDK, y está diseñado para adaptarse y crecer con futuras versiones de MapLibre, beneficiándose de sus avances.

Pasemos ahora a los detalles.

Crea tu primer mapa con el sdk MapTiler

Si ya está familiarizado con MapLibre, la curva de aprendizaje de nuestro SDK va a ser casi plana.

Lo primero es lo primero: tienes que conseguir una clave API. Es fácil, y el nivel gratuito es bastante generoso, así que crea una cuenta en MapTiler Cloud y luego ve a la sección API para obtener tu clave.

A continuación, para instalar y utilizar el SDK en su proyecto JS/TS, tiene dos opciones:

• utilizar nuestro CDN y una simple página HTML como esta:

(Puede encontrar este ejemplo, así como muchos otros, en las páginas de documentación del SDK)

• o, instálalo en tu proyecto con NPM:

npm install --save @maptiler/sdk

A continuación, en una de las páginas del frontend o en un componente React importa estos elementos del SDK:

import { Map, MapStyle, config } from '@maptiler/sdk';


// Set your MapTiler CLoud API key
config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';


const map = new Map({
  container: 'map', // Div container ID HTML element, or React ref
  style: MapStyle.STREETS, // Pick one of the built-in styles
  center: [16.62662018, 49.2125578], // position [lng, lat]
  zoom: 14,
});

Como puede notar, esto es bastante similar a la inicialización de MapLibre. A partir de aquí, la principal diferencia es cómo se establece el token de la API (que solía ser parte de la URL de estilo) y la etiqueta estilo que ahora es un valor autocompletado a partir de un gran número de estilos incorporados.

El socio perfecto para la pila Data de MapTiler

MapTiler es un prolífico creador de datos. Desarrollamos muchas capas internamente, ¡y nuestro equipo de geodatos siempre está ocupado! Estoy pensando en MapTiler Planet, Geocoding, Ocean, terreno 3D personalizado, ¡y muchos más (basta con echar un vistazo al resto de artículos de esta sección de noticias)! También colaboramos activamente con algunas grandes empresas para ofrecer grandes datos a nuestros usuarios; sería una lástima que éstos no se incorporaran fácilmente a los productos de nuestros clientes.

Una de las principales características de nuestro SDK es el acceso a los datos sin esfuerzo.

Esto es lo que obtienes con una cuenta gratuita de MapTiler Cloud

• todos los estilos y tilesets premium, mantenidos por nuestros cartógrafos
• una herramienta para crear sus propios estilos desde cero o clonando uno existente
• un servicio de alojamiento para sus datos geográficos (.geojson, .gpx, .kml, .shp, .zip shapefile) almacenados como geojson
• un servicio para consumir sus datos (API REST y biblioteca TypeScript cliente)
• un servicio de geocodificación (API REST y biblioteca TypeScript cliente)
• un servicio de geolocalización IP (API REST y biblioteca TypeScript cliente)
• un montón de tutoriales para empezar y hacer cosas más avanzadas con los mapas.
• cuotas generosas, ¡más que suficientes para sus proyectos paralelos!

Estilos de mapa más fáciles

El diseño de mapas no es una tarea sencilla, sobre todo cuando el mapa debe transmitir intenciones claras minimizando el desorden visual. Pero nosotros le ayudamos.

El equipo de cartógrafos y diseñadores de MapTiler crea continuamente nuevos estilos para diversos fines: orientados a la calle, al senderismo y al esquí, a la visualización de datos, centrados en el océano, ¡y mucho más! Actualmente contamos con una extensa lista de estilos, cada uno con sus características y aplicaciones únicas.

Para facilitar la incorporación de estos estilos en tus proyectos, hemos decidido crear abreviaturas que se autocompletan con descripciones al utilizar TypeScript. Veamos cómo funciona:

import { Map, MapStyle } from '@maptiler/sdk';

this.map = new Map({
  container: someDiv,
  style: MapStyle.DATAVIZ.DARK,
})

En estilo en la propiedad Mapa es ahora opcional (mientras que en MapLibre es obligatorio) y, si no se proporciona, se utilizará nuestro constructor calles-v2 estilo (abreviado: MapStyle.CALLES).

Estas son las ventajas de utilizar la taquigrafía frente a la URL de estilo:

• no es necesario recordar la URL, las abreviaturas se autocompletan
• no es necesario saber cuál es la última versión, utiliza la más reciente (¿Calles-v2? ¿o quizás v3?)
• no es necesario concatenar la clave API
• las variantes de estilo son más fáciles de alcanzar

Así es como se muestra el autocompletado en VSCode con un proyecto TypeScript:

Autocompletar mostrando todos los estilos

Autocompletar mostrando todas las variantes para un estilo dado Sin embargo, MapTiler SDK es totalmente compatible con MapLibre, por lo que puede seguir utilizando una URL o una descripción de estilo de objeto.

Unas palabras sobre las variantes de estilo: si escribe MapStyle.DATAVIZ en VSCode, verá el autocompletado con lo siguiente:

• MapStyle.DATAVIZ.DEFAULT: un estilo minimalista con sólo un pequeño toque de color, equivalente a utilizar MapStyle.DATAVIZ
• MapStyle.DATAVIZ.LIGHT: una alternativa minimalista en gris claro
• MapStyle.DATAVIZ.DARKuna alternativa minimalista en modo gris oscuro

La mayoría de los estilos vienen con múltiples variantes, y todas las variantes dentro del mismo estilo muestran los mismos datos; sólo cambia la combinación de colores. También existen variantes para diferentes estilos, por ejemplo, un OSCURIDAD existe para el estilo DATAVIZ, y también para el estilo CALLES, BRILLANTE, BASICetc.

He aquí cuatro de nuestros estilos más populares:

MapStyle.CALLES	MapStyle.SATELLITE
MapStyle.DATAVIZ.DARK	MapStyle.OUTDOOR

El terreno, aún más fácil

Una de las ventajas de mostrar mapas mediante WebGL es la posibilidad de aprovechar sus capacidades de malla para renderizar elementos tridimensionales, como montañas. Sorprendentemente, a pesar de que el terreno 3D está disponible desde hace algún tiempo, nunca ha sido particularmente sencillo de habilitar. Por lo general, esto requiere añadir una fuente con la URL de los tilesets de terreno y, a continuación, incorporar esta fuente al mapa de una manera muy específica. Si se desea modificar la exageración, en cierto modo hay que reiniciar parte de este proceso, lo que puede resultar bastante engorroso.

En MapTiler, somos propietarios y proveedores de los datos del terreno, lo que nos permite ofrecer un acceso directo y simplificar significativamente el uso del terreno 3D. Puedes habilitar el terreno 3D justo cuando instales la aplicación Mapa:

const map = new Map({
  container: someDiv,
  style: MapStyle.OUTDOOR,
  terrain: true,            // OPTIONAL. This is false by default
  terrainExaggeration: 1.5, // OPTIONAL. This is 1 by default
})

o más tarde, después de instanciar el mapa:

// Without param, the exaggeration factor is 1
map.enableTerrain();

// Or with an exaggeration of more than 1, to have even bigger mountains
map.enableTerrain(1.5);

Para desactivar el terreno y dejar de obtener fichas de terreno bajo el capó, basta con utilizar map.disableTerrain().

Jugar con la exageración del terreno en MapStyle.INVIERNO

Más allá del Data

Un principio de diseño fundamental para nosotros es encapsular la complejidad para que usted no tenga que hacerlo. Esto incluye la creación de puentes directos a nuestra pila de datos, como se mencionó anteriormente, y mucho más. En la siguiente sección, encontrarás ejemplos adicionales de cómo nos adherimos a este principio rector.

Por una vida más sencilla (Dev)

Ahora sabemos que hay un acceso directo a la pila de datos de MapTiler Cloudque facilita el desbloqueo de estilos y terrenos. Sin embargo, hay más ayudas, así que vamos a echar un vistazo más de cerca:

• geolocalización: especifique geolocalizar: true (por defecto: falso) en el Mapa y el mapa se centra en la ubicación del usuario. Bajo el capó, esto está utilizando MapTiler Cloud's IP Geolocation API. Tenga en cuenta que esto es menos preciso que un GPS, pero también no necesita conceder acceso a la API de localización del navegador, por lo que no se interrumpe el flujo aquí.

• idioma: Por defecto en el SDK, las instancias del mapa utilizarán la configuración del navegador para usar el idioma preferido del usuario. Se puede cambiar con la opción Mapa opción constructor idioma: Language.ENGLISH o cualquier otro de los 78 atajos lingüísticos incorporados. Una vez creado el mapa, también puede utilizar el nuevo método map.setLanguage(Language.SPANISH) para actualizarlo.

• controles: Históricamente, los controles son otra fricción, y la mayoría de las veces necesitan ser instanciados y luego añadidos al mapa desde dentro de la llamada de retorno del evento "load". Para el SDK, hemos decidido simplificar esto y hacer que todos los controles clásicos estén disponibles desde el constructor. Para cada uno, puede especificar verdadero / falso y una posición como arriba-izquierda o abajo a la derecha. Esta es la lista de Mapa opciones del constructor:

  • navigationControl (por defecto: verdaderoque aparece en el arriba a la derecha) muestra los botones de zoom/soporte/rotación
  • terrainControl (por defecto: falsoque aparece en el arriba a la derecha cuando verdadero) muestra un botón para alternar el terreno 3D
  • geolocalizarControl (por defecto: verdaderoque aparece en el arriba a la derecha) muestra un botón para geolocalizar al usuario utilizando la API de localización del navegador (muy probablemente GPS)
  • scaleControl (por defecto: falsoque aparece en el abajo a la derecha cuando verdadero) muestra una regla de escala
  • fullscreenControl (por defecto: falsoque aparece en el arriba a la derecha cuando verdadero) muestra un botón para activar la pantalla completa

• geocodificación: MapTiler SDK incluye el TypeScript Biblioteca MapTiler Cloud API Client y también lo expone. Esto significa que podemos utilizar fácilmente funciones como la geocodificación: geocoding.forward("paris")

¿Cuál es la ventaja sobre... tú_lo_llamas?

El objetivo de MapTiler SDK junto con nuestros datos es reducir la curva de aprendizaje con un gran paquete de inicio, y esperamos que haga del mapeo interactivo algo más fácil de hacer para que más personas puedan mostrar sus datos al mundo. Aún así, hay algunas alternativas populares por ahí que usted puede considerar, y todos ellos son populares por una razón, pero vamos a tratar de ver en una matriz de comparación cómo el SDK se destaca:

¿Busca ayuda?

El SDK incluye una completa documentación y multitud de ejemplos, que constituyen un excelente punto de partida. Si utiliza funciones como la geocodificación, la geolocalización por IP o la obtención de datos de MapTiler Cloud, recuerde que el SDK incluye la biblioteca API Client, que también está muy bien documentada.

También queremos incorporar sus comentarios al SDK.

• ¿Ha notado algún problema?
• ¿Le gustaría ver una nueva función?

Por favor, háznoslo saber directamente a través de GitHub Issues, y haremos todo lo posible para responder con prontitud.

Últimas palabras

En resumen, nuestro objetivo es reducir la complejidad y facilitar a todos, incluidos los desarrolladores noveles, la creación de mapas y visualizaciones de datos geográficos impresionantes.

Los métodos para conseguirlo pueden parecer sencillos y consisten principalmente en:

• Acortar la distancia entre usted y los datos que necesita
• Convertir los bloques de construcción más comunes en frases de una sola línea
• Incluye cómodos ajustes por defecto
• Documentación útil, tanto en línea como en el editor de código.

Por experiencia sabemos que encapsular la complejidad puede llevar mucho tiempo y a menudo requiere esfuerzos de ingeniería no triviales, pero esa es realmente la dirección que queremos que tome nuestro SDK.

Encuentra el SDK de MapTiler

Pruébalo tú mismo; es de código abierto (BSD-3), y recuerda que MapTiler Cloud tiene una generosa versión gratuita que te ofrece nuevos estilos de mapas y tilesets.

Aquí tiene algunos enlaces que pueden resultarle interesantes:

• Página principal del SDK de MapTiler
• Documentación de referencia
• Ejemplos oficiales
• En GitHub
• Sobre el MNP
• Página principal de la biblioteca MapTiler Client (no es necesario instalarla, está incluida en el SDK)

Estamos impacientes por ver lo que vas a crear con nuestro nuevo SDK, así que ¡háznoslo saber en Twitter @maptiler!

El futuro del SDK de MapTiler

El concepto de "ecosistema" es algo que valoramos mucho. Siempre que tenemos una idea para una nueva función, nos preguntamos: "¿Debería formar parte del SDK?". No hay una respuesta universal; a veces es un "sí", y lo hacemos realidad o lo añadimos a nuestra hoja de ruta, mientras que otras veces es un "no". ¿Y ahora qué? Hemos decidido desarrollar "módulos " que funcionan a la perfección con nuestro SDK, facilitan el acceso a los datos sin añadir complejidad e introducen nuevas funciones en tu aplicación. En cierto sentido, los módulos son como paquetes de refuerzo.

En conclusión, ¡el SDK está sólo en sus comienzos! ¡Seguiremos añadiendo nuevas funciones directamente relacionadas tanto con los datos de MapTiler como con la simplificación de algunos componentes de MapLibre para reducir aún más la fricción entre los desarrolladores y su próxima aplicación!

En MapTiler también somos desarrolladores y, como todo el mundo, apreciamos la simplicidad. Cada vez que nos encontramos con una peculiaridad y nos encontramos profundizando en StackOverflow o en el código fuente de una biblioteca para entender por qué las cosas no están funcionando como se esperaba, ¡vemos una oportunidad para hacer las cosas más sencillas! Por ejemplo, las capas de MapLibre: algunas son muy bonitas y personalizables, pero no siempre fáciles de configurar, ¿verdad? Quizá sea algo que podamos abordar en la próxima versión del SDK de MapTiler.

Mientras tanto, ¡nos vemos ahí fuera!