Monday, 17 November 2025

Getting Started with UniMap: Step-by-Step Guide to the JavaScript API

Standard

If you’ve ever switched between Google Maps, Mapbox, OpenStreetMap, Bing or MapmyIndia, you already know the pain:

every provider has its own SDK, docs and quirks.

UniMap solves that by giving you one JavaScript API that works across 10+ map providers like Google, Mapbox, Bing, OSM, Azure, HERE, TomTom, Yandex, CARTO and MapmyIndia. (GitHub)

In this tutorial, we’ll go step by step:

  1. Set up UniMap (npm & CDN options)
  2. Initialize your first map
  3. Add markers and custom markers
  4. Draw routes and shapes
  5. Use geocoding & directions
  6. Listen to events
  7. Switch providers with one line of code

By the end, you’ll have a clean, provider-agnostic map setup you can drop into any project.

1. Prerequisites

You’ll need:

  • A basic HTML/JS project (can be plain HTML + <script> or any framework)
  • An API key from at least one provider e.g. Google Maps, Mapbox, etc.
  • A <div> on your page where the map will be rendered

For this tutorial, let’s assume Google Maps (you can switch later).

2. Installing UniMap

Option A: Using npm (recommended for modern apps)

npm install unimap

Then in your JavaScript/TypeScript file:

import { UniMap } from 'unimap';

(GitHub)

Option B: Using CDN (no build setup needed)

Add this in your HTML <head> or before </body>:

<script type="module" src="https://cdn.jsdelivr.net/npm/unimap@latest/build/unimap.mini.js"></script>

Then you can access window.UniMap from your script. (GitHub)

3. Basic HTML Layout

Create a simple HTML file with a container for the map:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>UniMap JS API Demo</title>
    <style>
      #map {
        width: 100%;
        height: 500px;
      }
    </style>
  </head>
  <body>
    <h1>UniMap – JavaScript API Demo</h1>
    <div id="map"></div>

    <script type="module" src="main.js"></script>
  </body>
</html>

We’ll write all UniMap code in main.js.

Output:


4. Initializing Your First Map

UniMap is created with a config object that includes:

  • provider – e.g. 'google', 'mapbox', 'osm'
  • apiKey – your provider’s key
  • containerId – the DOM id of your map container
  • options – center, zoom, etc. (GitHub)

main.js

import { UniMap } from 'unimap';

async function initMap() {
  const map = new UniMap({
    provider: 'google',               // change this later to switch providers
    apiKey: 'YOUR_GOOGLE_MAPS_KEY',
    containerId: 'map',
    options: {
      center: { lat: 40.7128, lng: -74.0060 }, // New York
      zoom: 12
    }
  });

  await map.init(); // important: initializes provider SDK & map

  // For demo purposes, expose it globally
  window.unimap = map;
}

initMap().catch(console.error);

At this point, you should see a basic Google map centered on New York.

5. Adding Your First Marker

UniMap’s marker API is simple and consistent across providers:

await map.init();

map.addMarker({
  lat: 40.7128,
  lng: -74.0060,
  title: 'New York City',
  label: 'NYC',
  color: '#ff0000'
});

addMarker returns a markerId if you want to update/remove it later. (GitHub)

6. Custom HTML Markers (for branded pins)

Want a fancy marker (e.g., with your logo or a styled label)? Use addCustomMarker:

const customMarkerId = map.addCustomMarker({
  lat: 40.73061,
  lng: -73.935242,
  html: `
    <div style="
      background:#0d6efd;
      color:#fff;
      padding:6px 10px;
      border-radius:16px;
      font-size:12px;
      box-shadow:0 2px 6px rgba(0,0,0,0.3);
    ">
      Custom Marker
    </div>
  `,
  title: 'Cool custom marker'
});

Under the hood UniMap converts this to the provider’s equivalent (Google, Mapbox, etc.) but you write the same code everywhere. (GitHub)

7. Drawing Routes and Shapes

UniMap exposes high-level drawing methods: drawRoute, drawPolygon, drawCircle, drawRectangle, drawPolyline. (GitHub)

Draw a simple route between points

const routeId = map.drawRoute(
  [
    { lat: 40.7128, lng: -74.0060 }, // NYC
    { lat: 40.7589, lng: -73.9851 }, // Times Square
    { lat: 40.7484, lng: -73.9857 }  // Empire State
  ],
  {
    strokeColor: '#ff0000',
    strokeWeight: 4
  }
);

Draw a polygon (e.g., area selection)

const polygonId = map.drawPolygon(
  [
    { lat: 40.72, lng: -74.00 },
    { lat: 40.72, lng: -73.98 },
    { lat: 40.70, lng: -73.98 },
    { lat: 40.70, lng: -74.00 }
  ],
  {
    strokeColor: '#00ff00',
    fillColor: '#00ff00',
    fillOpacity: 0.3
  }
);

You can later remove any drawing with:

map.removeLayer(routeId);
map.removeLayer(polygonId);

8. Geocoding & Directions (Search & Routing)

UniMap wraps provider geocoding and routing into simple methods: geocode, reverseGeocode, and getDirections. (GitHub)

8.1 Geocode an address

const result = await map.geocode('Statue of Liberty, New York');
console.log('Geocode result:', result);

// Example: center the map on the first result
if (result && result.location) {
  map.setCenter(result.location);
}

8.2 Reverse geocode (lat/lng → human address)

const info = await map.reverseGeocode(40.7128, -74.0060);
console.log('Reverse geocode:', info);

8.3 Get directions between two points

const directions = await map.getDirections(
  { lat: 40.7128, lng: -74.0060 }, // origin
  { lat: 40.7589, lng: -73.9851 }, // destination
  { mode: 'driving' }              // provider-dependent options
);

console.log('Directions:', directions);

Exactly how rich the data is depends on the provider, but your code stays the same.

9. Handling Events (Clicks, Moves, etc.)

There are two styles of event handling:

9.1 Global map events with on

map.on('click', (event) => {
  console.log('Map clicked at:', event.lat, event.lng);
});

You can remove listeners with off(event, callback). (GitHub)

9.2 Marker click events

If you want special behavior on marker click (like opening a popup):

const markerId = map.addMarker({
  lat: 40.7589,
  lng: -73.9851,
  title: 'Times Square'
});

map.onMarkerClick(markerId, (markerInfo) => {
  console.log('Marker clicked:', markerInfo);
}, {
  popupHtml: '<strong>Times Square</strong><br>Welcome!',
  toastMessage: 'You clicked Times Square!'
});

UniMap uses provider-specific popups/toasts internally, but your API is consistent. (GitHub)

10. Advanced Goodies (Traffic, 3D, User Location)

When the provider supports it, UniMap gives you helpers for advanced map features: (GitHub)

// Enable traffic layer
map.enableTrafficLayer();

// Track user location
map.trackUserLocation((location) => {
  console.log('User location:', location);
  map.setCenter(location);
});

// Enable 3D (where supported)
map.enable3D(true);

These let you progressively enhance your app without writing provider-specific code.

11. Switching Providers in ONE Line

Here’s the magic of UniMap.

The rest of your code stays exactly the same – you just switch the provider (and API key):

const map = new UniMap({
  provider: 'osm',                      // <--- changed from 'google'
  apiKey: 'NO KEY REQUIRED FOR OSM',
  containerId: 'map',
  options: {
    center: { lat: 40.7128, lng: -74.0060 },
    zoom: 12
  }
});


output:

You can plug in:

  • 'google'
  • 'mapbox'
  • 'bing'
  • 'osm'
  • 'azure'
  • 'here'
  • 'tomtom'
  • 'yandex'
  • 'carto'
  • 'mapmyindia' (GitHub)

No more rewrites. No more vendor-lock-in hell.

12. Cleaning Up

When navigating between pages or destroying components (e.g. in SPA frameworks), always clean up the map:

map.destroy();

This ensures listeners and provider instances are properly removed. (GitHub)

13. Where to Go Next?

  • Explore the full API reference in the UniMap README (markers, heatmaps, indoor maps, styles, etc.). (GitHub)
  • Try using the Custom HTML Elements (<unimap-map>, <unimap-marker>, etc.) if you want a no-JS setup.
Build a small internal tool:
  • “Show all store locations on map”
  • “Plot live vehicles with custom markers”
  • “Highlight delivery zones with polygons”

Let's Conclude

UniMap lets you think in terms of maps and features, not “Which provider’s SDK do I have to fight with today?”

  • One JavaScript API
  • Multiple providers
  • Zero rewrites when business needs change

Bibliography