How to Pick a Web Mapping Library for your App

Originally published by James Milner on SitePen.com.

With the boom of location-based technologies like mobile location services and the Geolocation API in the browser, we have seen the growth of mapping and location inside of applications. Alongside this we have seen numerous mapping libraries appear for the web, allowing developers to build map based experiences into their apps. These libraries abstract away the complexity of things like geographic coordinate systems, ordering map tiles correctly, panning, zooming and various other behaviors.

When it comes to building a web application with a location-based element, picking the right web mapping library can be critical to providing the correct functionality to your users. How do you determine the functionality you might need? What options are there for finding the right library and services for you and your team?

Knowing What You Need

Before diving into technology choices, it is worth examining the business requirements of the application you are building. Understanding these requirements will help you determine which mapping library is right for your team. Here are some questions to consider when requirements have been gathered:

• What geospatial functionality is required? Map tiles? Address lookups? Editing polygons? Satellite imagery?
• Do we have in house services for these features, or do I need third party services?
• Will the license agreement of a library/service match my business model?
• Is the pricing prohibitively expensive for the value this would add to the app?
• What are the additional complexities and increases in developer time added by including a mapping segment to the app?

How these questions are answered can drastically change the outcome of the question ‘What is the right mapping library for me?’. Different mapping libraries will have different strengths in relation to your requirements, as well as different stipulations on how they might get used. Working these out before implementing a solution might save a lot of effort long term, so it’s worth investing some time to better understand the options.

Libraries vs. Services

As alluded to above, it is important to grasp the distinction between libraries (sometimes referred to as JavaScript APIs) and services (web APIs, web services). The libraries get run in the browser and the services are what these libraries will make requests to for things like tiles or determining the location of a given address. These services will normally require some form of API key for authenticated requests. This can link back to your account with the provider and sometimes provide metrics for usage.

When it comes to services it’s important to note that many of these are paid services. Many companies will provide a free tier of usage, but after a certain usage limit, a financial cost will get incurred. The usage is normally tied to your API key, which keeps track of requests. Mapping service providers rarely charge for access to the actual mapping library itself.

Rendering Approaches and Map Tiles

Different libraries take different approaches to rendering map data. Libraries may just use DOM directly with layered elements, others leverage HTML5 Canvas, and most performantly, some use WebGL to render data. Some libraries may allow different renderers (for example Leaflet, which we come to later, is DOM-based but has an HTML5 canvas renderer). Depending on your use case the type of rendering approach may be important. For example, high performant applications requiring a high frame rate, or those rendering a lot of dense visual data, may benefit from a WebGL rendering based approach due to the ability to move work to the device GPU. Any 3D mapping generally requires a WebGL-based approach.

Basemaps, the underlying map that you pin your data on top of (for example a street map) can come in a variety of different formats. Historically the predominant approach was raster map tiles, which are essentially images that are stitched together in the browser. More recently vector map tiles (individual points, lines and polygons which get rendered to the screen) were introduced. This approach benefits from the Canvas and WebGL methods mentioned above as using these technologies is very efficient with vector data. Vector map tiles are normally in the Mapbox vector map tile standard which is open and based on protobufs for efficient data transfer. Some providers such as Google do not expose their basemap tiling approach.

Proprietary Libraries

Mapping technology companies such as Google, Esri and Here ship custom mapping libraries which allow easy usage of their services in your application. Since the services are integrated into the library it generally means you need to do less configuration to get up and running with a given mapping component (e.g. viewer, location search bar). Let’s examine some of the libraries to give a better feel for them.

Google Maps JavaScript API

Arguably the most well known of all mapping libraries, Google Maps provides a robust set of components and services for developers to integrate into their app. This is arguably one of Google Maps strongest points with a very detailed basemap, routing APIs and components and accurate geocoder. The library has a long history, lots of questions on Stack Overflow and many articles and posts written about it, giving it a good level of community support and interest.

Using the Google Maps API requires including the Google Maps library from the CDN. There is no official way to use Google Maps via npm, apart from the API directly with node via the @google/maps package. There is an unofficial loader at google-maps which can be used however. Using the API to create a map with JavaScript looks like this:

1 var map;
2 function initMap() {
3     map = new google.maps.Map(document.getElementById('map'), {
4         center: {lat: -34.397, lng: 150.644},
5         zoom: 8
      });

6 
7 }

Google Maps presents a simple API, with constructing a map just requiring the element we wish to place it in, and the latitude and longitude of where we’d like to position the map to start with. Google Maps will shine in scenarios that require high quality and accurate base-mapping like adding a directions widget to your app, or showing the location of your stores, or doing simple drawing onto the map. It also has the benefit that many consumers have used and are familiar with the look and feel of Google Maps. Last June Google changed their pricing model for maps, requiring an API key and billing account to begin development with Google Maps. The latest pricing information for Google Maps services is available on the Google Maps website.

Esri ArcGIS JavaScript API

Esri is a large provider of mapping APIs, specialising in presentation and analysis of complex spatial data. The ArcGIS API supports both 2D maps and 3D scenes. The ArcGIS JavaScript API is a heavy-duty mapping library that you would expect from a Geographic Information Systems company. The API shines for more in-depth applications that require features like supporting multiple overlapping layers, editing polygons, visualising multiple types of data potentially from different sources (i.e. WMS, WFS, Vector Tiles, GeoJSON).

The API is a viable solution to building applications with in-depth requirements with multiple data sources, for example, visualising and analysing land use or exploring fishing regulations in a given area. The library has a long history and is underpinned by the Dojo Toolkit, hence the use of require and AMD module approach in the code sample below:

1 require([
2   "esri/Map",
3   "esri/views/MapView"
4 ], function(Map, MapView) {
5 
6   var map = new Map({
7     basemap: "topo-vector"
8   });
9 
10   var view = new MapView({
11    container: "viewDiv",
12     map: map,
13     center: [-118.71511,34.09042],
14     zoom: 11
15   });
 

16 });

If you are using the library with a framework that isn’t the Dojo Toolkit, you can use the esri-loader to aid this. The library is closed source, but the minified version is available on npm to use in your applications. The Esri ArcGIS JavaScript API also provides support for working with TypeScript, with a guide supplied on the Esri JS API docs. An Esri ArcGIS JS CLI tool is also available for scaffolding apps, and a plugin for using ArcGIS for JS with Webpack.

Pricing information is available on the Esri developer website. No payment is required to begin building maps with Esri, just the creation of a development account.

Here JavaScript API

Here is a company that provides a selection of mapping services, map tiles, routing, geocoding, place searches and traffic data. Arguably lesser known than some of its competitors, Here still provides a competitive set of tools for building mapping applications. Alongside their APIs Here provides a JavaScript library which comes as a series of ‘modules’ (although they appear to attach to a global H variable). You can see a list of Here modules. Unfortunately these modules do not appear to be available on npm. Here is how you create a basic map using the API:

1 var platform = new H.service.Platform({
2     useHTTPS: true
3 });
4 
5 var pixelRatio = window.devicePixelRatio || 1;
6 var defaultLayers = platform.createDefaultLayers({
7     tileSize: pixelRatio === 1 ? 256 : 512,
8     ppi: pixelRatio === 1 ? undefined : 320
9 });
10  
11 var map = new H.Map(document.getElementById('map'),
12     defaultLayers.normal.map, 
13     {pixelRatio: pixelRatio,  zoom: 12,
14     center: { lng: -0.15, lat: 51.5 }
15 });
16
17 var behavior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));
  

We can see that this code sample is arguably a little more complicated than the previous examples. However, one could use Here’s mapping services with Open Source map providers like Leaflet or OpenLayers. Here may make the most sense if you are doing work with transport and logistics, as this is where many of there services are oriented. Here’s developer plans include a free tier with transaction-based pricing.

Open Source Libraries

Developers can also use a set of libraries that are open source. These libraries can be used without any strong stipulations which make them a good choice for when licensing is a sensitive issue for a project or when you need greater transparency and extensibility of the underlying implementation.

Leaflet

Leaflet is a light and simple mapping library that is relatively easy to use. The library is licensed under BSD-2-Clause and is available on npm. Leaflet has a strong plugin ecosystem which provides strong additional feature sets which can help make Leaflet as functional as other mapping libraries. Here’s an example of creating a simple map using the API:

1 var map = L.map('map').setView([51.505, -0.09], 13);
2 L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
3     attribution: '&copy; <a >OpenStreetMap</a> 
contributors'
4 }).addTo(map);

Due to its lightweight nature and straightforward API, Leaflet is a great choice when you need a simple map which you want to plot smaller amounts of data onto. Leaflet will work with TMS/XYZ sources and WMS layers, but does not support Vector Tiles out the box (although there is a plugin).

OpenLayers

OpenLayers offers a robust, deep mapping API that can be used for a variety of complex applications. Out the box OpenLayers provides support for more complex features like editing polygons, heatmaps and more niche data sources like WMTS. Like Leaflet, OpenLayers is licensed under BSD 2-Clause. OpenLayers is also available on NPM and provides instructions on getting started using a bundler (Parcel in this case). The OpenLayers API uses Canvas and in some cases WebGL to give performant rendering. The API is very extensible and integrates well with other tools and frameworks. Creating a map with OpenLayers looks a little something like this:

1 var map = new ol.Map({
2     target: 'map',
3     layers: [
4         new ol.layer.Tile({
5         source: new ol.source.OSM()
6         })
7     ],
8     view: new ol.View({
9         center: ol.proj.fromLonLat([37.41, 8.82]),
10         zoom: 4
    })

11 });

Overall, OpenLayers provides a solid Open Source choice when your use case has complex requirements, including customisation of components, controls and map symbology.

MapBox GL

MapBox are another provider of location and mapping services. MapBox have a variety of service products such as basemaps, location search, and routing. They provide a request-based pricing model for web users, with a strong free tier. Along with their services, MapBox also provides a series of mapping libraries, many of which are open source.

MapBox GL, Mapbox’s WebGL powered mapping library, is a performant and simple to use library for rendering maps, in both 2D and 3D. Mapbox GL can do things like visualise buildings in 3D, create heatmaps or add a video onto a map.

MapBox is also available on npm and usable with a bundler which helps with modern web development approaches. The library is licensed under the 3-Clause BSD license. Below is an example of creating a basic basemap:

1 L.mapbox.accessToken = 'ACCESS_TOKEN_GOES_HERE';
2 var map = L.mapbox.map('map')
     .setView([40, -74.50], 9)

3
4    .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));

Mapbox GL would be a good choice if you are keen to use Mapbox services and/or need to integrate 3D mapping into your app. It is also a good choice if you require a performant user experience, such as targeting mobile web applications.

Conclusion

As you can see, there are many options when choosing a mapping library. The choice can be a little overwhelming, but the important thing to start with is your user requirements. You can then use those to deduce the services and library that make sense. Factors such as features, performance, developer ergonomics, licensing and pricing all play into making a sound decision. It may be worth shortlisting your options, then doing some exploratory work to determine the library that would best fulfill your gathered requirements.

As a final note, it is worth mentioning in some cases it may be possible to use a mapping providers’ services with another mapping library, for example using MapBox or Esri services with Leaflet or OpenLayers, which can allow for new solutions.

Alongside this blog post, you can review the web-mapping-libraries GitHub repository which collates the examples above for you to explore, as well as some lesser known libraries. Hopefully, the guidance and aggregated list of libraries in this post will help steer you towards picking the library that works for you and your team!

If you need help choosing a mapping library or creating your next mapping-based application, please contact us to discuss how we can help!