Maps SDKs Integration guide

Estimated reading time: 7 minutes

Integrating Maps in your project

Jawg exposes multiple Tile APIs to work with maps. To display maps, you need to use a Maps SDK.

When we started working with maps, we wondered if we should make our own SDK. The answer was pretty straightforward: There are already great OpenSource Maps SDKs, and well… We’d rather spend our nights optimizing rendering efficiency to give you the fastest maps on the market than putting our name on a brand new Maps SDK which would pretty much do the same as the others.

We use those SDKs every day though, and are dedicating some time on OpenSourcing technologies to give back to the community (have you tried OSM Contributor?).

I know I know… It’s been 10 lines and you still don’t know the names of neither the SDKs nor the platforms. Let’s get to it!

Recommendations: Maps SDKs


If we had a fancy chat-bot, this is the first question it would ask you:

What did you have for breakfast? (I know. Pointless).

The second question it would ask you would actually be more meaningful:

What platform are you developing on?

And your possible answers would be:

Native Android, Native iOS, Web / Web-based Hybrid, Desktop / Software

Native Android


A long time ago, there was osmdroid. But honestly, this was a long time ago (when you still needed to recycle Bitmaps by hand on Android because they were not stored on heap. Yep, that long!). This library had the advantage to… well to exist, but is out-of-date, not maintained, and should not be used anymore.

A few years later, some cool guys were inspired by osmdroid and decided to recode a new one with better libraries on their own repo, with their own name. The SDK was called mapbox-android-sdk. I remember it because I was the one who contributed map rotation to it (good ol’times, I don’t think the feature ever worked correctly) when Jawg was not even in our minds. Fact is that even if the libraries were cool, the core of it was still spaghetti code, and I’m not even talking about the coordinate system.

This is also the time when people were starting to talk about Vector Tiles. And we have Mapbox to thank for putting both feet in it and specify things on the fly (at least they did that right!). Sure, they could have chosen way cooler names than mapbox-vector-tile, but you know… People in Marketing have a tendency to prefix everything with their own name. Some say it is powerful, and I believe them. So mapbox-android-sdk was abandoned, for a more low-level, OpenGL enabled library called mapbox-gl.

Although mapbox-gl took quite a few months to really take-off, and went through some heavy reengineering, it is safe to say that it became the standard for all OpenStreetMap based SDKs (Jawg included).

Integrating Jawg maps with Mapbox GL Android is quick & easy. Check out the available samples and integration-guide.

View Tutorial Examples

Web / Web-based Hybrid

A few years back, browsers did not have support for WebGL (yeah… I know…). What? You mean some browsers may still NOT have full support for WebGL? I’m not going to tell names, but it starts by “Int”, and ends by “ernet Explorer”.

And so, the community made two libraries to consume tile APIs, formatted under the Slippy Map Tiles specification or other standards (some could also display Google Maps, Bing Maps, or others).

Basically, those libraries are supposed to do at least two things:

  • Display specific raster tiles and load them dynamically as we browse the map
  • Overlay Geometries (Points, Polygons, PolyLines etc…) on top of the raster layer(s) and handle many kinds of events

Their names? OpenLayers and Leaflet Their differences? Lots. And your decision regarding which one you should keep and which one you should drop should depends on your goals.

Need perspective? Watch this awesome side-by-side comparison (credits to Ivan Sanchez, who is a core committer on Leaflet as well). OpenLayers is a community-project initiated by Christopher Schmidt in 2006. It is not modular (more of an all-in-one library) but is highly tested, well documented, and has very frequent updates. Leaflet was initiated by Vladimir Agafonkin in 2010, and actively maintained by the community. It turned v1.0 in September 2016 and has minor updates released very infrequently (approx every quarter).

Since Vector tiles were introduced a few years back, both OpenLayers and Leaflet have proposed their own solution using their JS-based technology. Although we can salute the effort, they did not reinvent themselves to this new paradigm, nor did they decide to switch to GPU rendering. We understand this choice as it requires a complete set of new skills and WebGL programming, but disqualifies both those libs when people want beautiful vector rendering.

A handful of companies decided to work on the subject, especially Mapbox (mapbox-gl-js) and Mapzen (tangram). Both have pros and cons. Mapbox is doing “half-way” Opensource: carefully documenting everything related to the use of their technology with their maps, and carefully omitting to talk about the APIs which allow you to use other tile sources. Admittedly, they have great people working on the lib, made it the best library out there today and support external tile sources any way. Mapzen has a much appreciated real openness when it comes to technology, even though they have not managed to give clients the smoothness nor the ability to forget about the tile approach. Mapbox GL is a brilliant work in that direction.

Attention though: all browsers are not equal when it comes to WebGL compatibility. By targeting multiple standards with the same core codebase (OpenGL, OpenGL ES, WebGL), implementations are not equal and GPU rendering wont be as good from one computer to another, from one browser to another.

Raster Tiles

Although we really enjoy the clean code approach of OpenLayers and their will to frequent releases, we cannot ignore the fact that Leaflet.js gives a better modular approach, an excellent quality and is therefore much more lightweight than OpenLayers.

leaflet-logo We would recommend Leaflet because every byte you can save in your payload is worth considering!

Integrating Jawg maps with Leaflet is a question of seconds. Check out the available samples and integration-guide.

View Tutorial Examples


Migrating from Google Maps or Mapbox? We also made two videos to show how easy it is to switch to Jawg in a minute !

Video : Switch from Google Maps to Jawg

Video : Switch from Mapbox to Jawg

Vector Tiles

Although Mapzen put great efforts on speed, reusability and openness, Mapbox-GL-js went much further in terms of user-experience.

mapbox-logo We would recommend using Mapbox-GL-js.

Integrating Jawg maps with Mapbox GL JS is quick & easy. Check out the available samples and integration-guide.

View Tutorial Examples

Desktop / Software

To use tiles in software, you need to know which Standard to apply. Jawg can talk to different standards. We expose TMS (also named Slippy-Map-Tile, or OpenStreetMap), and WMTS APIs. Also, WMS APIs can be opened for dynamic queries in our custom plans. Contact-us for more information.

If you are using Tableau or GIS software such as ArcGIS, ArcMap or QGIS, carry on reading as we have provided specific implementations for it.

qgis-logo Integrate Jawg maps in QGIS version 2.0 or later with the WMTS endpoint provided by Jawg.

Learn how with this tutorial:

View Tutorial

arcmap-logo Integrate Jawg maps in ArcGIS Desktop 10 or later with the WMTS endpoint provided by Jawg.

Learn how with this tutorial:

View Tutorial

tableau-logo Integrate Jawg maps in Tableau Desktop 10 or later with the TMS files we provide for you.

View tutorial - Download TMS files