Upgrade Guide

The Next Billion Maps GL is a drop-in upgrade for the Next Billion Maps. Most of the functionalities will work the same without changing much of your code.

However there are a few minor changes that would need adaptation depending on your use cases.

URL and API Key

The Next Billion Maps GL introduces a new tiles service provided by NextBillion.ai which requires a valid API Key. You'll need to add the API Key before initializing a map instance. Please refer to the page Get an API Key for more information.

Basically, to upgrade your projects with the Next Billion Maps GL, all that you need to change are:

  • Change maps.nextbillion.io to maps-gl.nextbillion.io for the stylesheet and script tags
  • Provide a valid API Key
- <link href="https://maps.nextbillion.io/maps/api/css" rel="stylesheet">
+ <link href="https://maps-gl.nextbillion.io/maps/api/css" rel="stylesheet" />
- <script src="https://maps.nextbillion.io/maps/api/js"></script>
+ <script src="https://maps-gl.nextbillion.io/maps/api/js"></script>
+ nextbillion.apiKey = '123456'

A complete example map:

<!DOCTYPE html>
<html lang="en">
<meta name="viewport" content="initial-scale=1.0" />
<meta charset="UTF-8" />
<title>Basic Map</title>
<link href="https://maps-gl.nextbillion.io/maps/api/css" rel="stylesheet" />
* {
margin: 0;
padding: 0;
#map {
width: 100vw;
height: 100vh;
<div id="map"></div>
<script src="https://maps-gl.nextbillion.io/maps/api/js"></script>
;(function () {
nextbillion.apiKey = '123456'
var map = new nextbillion.maps.Map(document.getElementById('map'), {
zoom: 12,
center: { lat: 28.6139, lng: 77.209 },

Polygon Path

If you've used polygons in your projects, you need to slightly change the path parameter to make them work in the Next Billion Maps GL.

var polygon = new nextbillion.maps.Polygon({
- path: [[loc, loc2, loc3]],
+ path: [loc, loc2, loc3],
map: map,

Shape Editing

The Next Billion Maps GL doesn't support changing the outline of the shapes at the moment. If it's critical for your project to be able to edit shapes, please stay with the legacy version of the Next Billion Maps for now.

Meanwhile we're working hard to enable all features from the Next Billion Maps legacy version to the Next Billion Maps GL. Please stay tuned!