Showing posts with label UniMap. Show all posts
Showing posts with label UniMap. Show all posts

Wednesday, 19 November 2025

Getting Started with UniMap Elements: A Step-by-Step Guide Using Custom HTML Components

Standard

 


Here the magic is No JavaScript required. Just write HTML for <Unimap></Unimap>.

When we think of map integrations, we imagine JavaScript-heavy code, SDK loading, event listeners, callbacks, async handling… and a lot of rework every time the mapping provider changes.

UniMap Elements flips this upside down.

It gives you a set of Custom HTML Elements like:

<unimap-map>
<unimap-marker>
<unimap-route>
<unimap-geocode>

…which work across Google Maps, Mapbox, OpenStreetMap, Bing, HERE, TomTom, Mappls and many more  with zero JavaScript.

This means:

  • You can build maps like writing simple HTML.
  • You can switch providers instantly by changing one attribute.
  • It works beautifully even inside frameworks (React, Vue, Next.js, Astro, Webflow, Blogger templates, etc.).

Let’s build your first UniMap Elements project.

1. Add UniMap Elements to Your Page

Just drop one script:

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

This gives you access to all UniMap Web Components.

2. Create Your First Map (In Just HTML)

<unimap-map
  provider="google"
  api-key="YOUR_GOOGLE_KEY"
  width="100%"
  height="500px"
  zoom="10"
  lat="40.7128"
  lng="-74.0060">
</unimap-map>

That’s it.
You now have a Google Map rendering magically.

Output:



3. Adding Markers (ZERO JavaScript)

Just place <unimap-marker> inside <unimap-map>.

<unimap-map provider="google" api-key="YOUR_KEY" height="500px" lat="40.7128" lng="-74.0060">

  <unimap-marker 
    lat="40.7128" 
    lng="-74.0060"
    title="New York City"
    color="#ff0000">
  </unimap-marker>

</unimap-map>

You can add unlimited markers the same way.

4. Adding Custom HTML Markers

Use the html attribute for styled HTML markers.

<unimap-marker 
  lat="40.73061" 
  lng="-73.935242"
  html='
    <div style="background:#0d6efd;padding:6px 10px;color:#fff;border-radius:20px">
      Custom Marker
    </div>
  '>
</unimap-marker>

No JS. No event listeners. Still works across all map providers.

5. Drawing Routes in HTML

UniMap Elements lets you draw routes visually:

<unimap-route 
  stroke-color="#ff0000"
  stroke-width="4"
  points='[
    {"lat":40.7128,"lng":-74.0060},
    {"lat":40.7589,"lng":-73.9851},
    {"lat":40.7484,"lng":-73.9857}
  ]'>
</unimap-route>

Just pass an array of points.

6. Drawing Shapes (Circle, Polygon, Polyline)

Circle

<unimap-circle 
  lat="40.7128"
  lng="-74.0060"
  radius="1000"
  fill-color="#4285F4"
  fill-opacity="0.2">
</unimap-circle>

Polygon

<unimap-polygon 
  points='[
    {"lat":40.72,"lng":-74.00},
    {"lat":40.72,"lng":-73.98},
    {"lat":40.70,"lng":-73.98},
    {"lat":40.70,"lng":-74.00}
  ]'
  stroke-color="#00ff00"
  fill-color="#00ff00"
  fill-opacity="0.3">
</unimap-polygon>

Polyline

<unimap-polyline
  stroke-color="#8a2be2"
  stroke-width="3"
  points='[
    {"lat":40.702,"lng":-74.009},
    {"lat":40.706,"lng":-73.997},
    {"lat":40.712,"lng":-73.985}
  ]'>
</unimap-polyline>

7. Geocoding (Search an Address Using HTML)

Use:

<unimap-geocode 
  query="Statue of Liberty, New York"
  on-result="handleResult">
</unimap-geocode>

<script>
  function handleResult(event) {
    console.log("Geocode Result:", event.detail);
  }
</script>

This makes geocoding possible without calling APIs manually.

8. Reverse Geocoding (lat/lng → Address)

<unimap-reverse-geocode 
  lat="40.7128"
  lng="-74.0060"
  on-result="printAddress">
</unimap-reverse-geocode>

<script>
function printAddress(e) {
  console.log("Address:", e.detail);
}
</script>

Results come via a simple event.

9. Directions Using HTML

<unimap-directions
  origin='{"lat":40.7128,"lng":-74.0060}'
  destination='{"lat":40.7589,"lng":-73.9851}'
  mode="driving"
  on-result="showDirections">
</unimap-directions>

<script>
function showDirections(e) {
  console.log("Directions:", e.detail);
}
</script>

You get structured direction steps automatically.

10. Listening to Map Events Using Attributes

You can capture map clicks like this:

<unimap-map 
  provider="google"
  api-key="YOUR_KEY"
  lat="40.7128"
  lng="-74.0060"
  on-map-click="handleMapClick">
</unimap-map>

<script>
function handleMapClick(e) {
  const { lat, lng } = e.detail;
  console.log("Clicked at:", lat, lng);
}
</script>

Same syntax works for:

  • on-marker-click
  • on-map-move
  • on-map-ready
  • on-shape-click
  • etc.

11. Switching Providers by Changing ONE Attribute

This:

provider="google"

can be changed to:

provider="mapbox"
provider="osm"
provider="bing"
provider="here"
provider="tomtom"
provider="mapmyindia"

Your entire HTML map remains identical.

  • No refactoring.
  • No JS changes.
  • No SDK rewrites.
  • Total freedom.


e.g Output for OSM?:

Why UniMap Elements Is a Game Changer

✔ Zero JavaScript required

Perfect for designers, low-code builders, bloggers, and frontend devs.

✔ Works anywhere

Static HTML, WordPress, Blogger, Webflow, Astro, React, Vue, Next.js — everything.

✔ One map → Any provider

Ultimate future-proof mapping.

✔ Fastest prototyping experience

You can build a full app by copy-pasting components.

✔ Perfect for Infotainment Systems & Browser-Based Apps

Works even in restricted WebView environments.

UniMap Elements brings HTML-first mapping to the modern web.

  • No SDK headaches.
  • No vendor-specific APIs.
  • Just clean, declarative components that work everywhere.
Bibliography

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

Sunday, 16 November 2025

UniMap: The Universal Mapping Layer You Wish You Had Years Ago

Standard

A real-world guide for developers, product teams, and companies building with maps.

Today, almost every product needs some form of location intelligence i.e. ride-hailing, delivery apps, travel platforms, EV charging locators, insurance tech, logistics dashboards, vehicle head-unit apps, and even government systems.

But here’s the problem…

Every map provider speaks a different language.

Google Maps has its own SDK.
Mapbox uses another approach.
Bing Maps, OpenStreetMap, Azure Maps, HERE Maps — all different, all incompatible, all evolving differently.

If you ever tried switching from one provider to another, you already know the pain: rewriting your entire map layer, refactoring events, rewriting markers, popup logic, geocoding functions, routing calls, and handling pricing or quota changes.

This is the exact problem UniMap was created to solve.

What is UniMap?

UniMap is a lightweight JavaScript/Node.js library that acts as a single universal mapping layer across multiple providers, including:

  • Google Maps
  • Mapbox
  • Bing Maps
  • OpenStreetMap
  • Azure Maps
  • HERE Maps
  • CARTO
  • Yandex Maps
  • TomTom
  • MapmyIndia (Mappls)
  • …and more.

Instead of writing provider-specific code, you interact with one clean interface like:

const map = new UniMap({
  provider: "google",
  apiKey: "...",
  container: "map"
});

map.addMarker(28.61, 77.23);
map.addPolyline([...]);
map.setCenter(lat, lng);

If tomorrow you want to switch to Mapbox, you only change the provider name.
Everything else stays the same.

Why UniMap Was Created

The idea behind UniMap didn’t come out of a lab or a research paper;
it was born from real developer frustration and real business struggles, especially in companies that rely heavily on mapping services.

Here are the real problems that inspired UniMap:

1. Companies Hate Vendor Lock-In

Many startups begin on Google Maps because it is easy.
But when the bills hit — often very high bills — they suddenly want to migrate to Mapbox or OpenStreetMap.

Migration = one of the most painful refactoring tasks a dev team can face.

UniMap makes migrations nearly effortless.

2. Global Companies Need Different Providers in Different Regions

Example:

  • Google Maps is strongest in the US.
  • MapmyIndia is best for India.
  • HERE Maps is popular in Europe.
  • Yandex Maps dominates Russia.
  • OSM works well worldwide and is cost-free.

A company expanding internationally would normally need multiple codebases to support these regions.

UniMap lets them plug providers like LEGO blocks without rewriting features.

3. Developers Want Consistent APIs

Every map SDK has different function names, event models, and data formats.
This creates:

  • Huge learning curve
  • Longer onboarding
  • Inconsistent code
  • More bugs

UniMap standardizes the APIs into one smooth interface.

4. Product Teams Want Faster Experimentation

Often PMs ask:

“Can we quickly test Mapbox styles?”
“Can we use Bing for satellite imagery?”
“Can we add cheaper geocoding for bulk data imports?”

Without UniMap → big engineering effort
With UniMap → change one line of code.

Key Features of UniMap

✔ Unified API

One codebase, multiple providers.

✔ Supports 10+ Map Platforms

No need to learn new SDKs.

✔ Marker, Shapes, Routes, Polylines

One API for all providers.

✔ Geocoding / Reverse Geocoding

Works through provider adapters.

✔ Easy Provider Switching

Google → Mapbox → OSM → HERE
Just change configuration.

✔ Lower Cost & Risk

Avoid sudden map-pricing shocks.

Real Case Studies — How Companies Use UniMap

Let’s make this human and practical with real-world scenarios.

Case Study 1: A Global Delivery Startup Avoided a $300k Migration Cost

A delivery platform used Google Maps for 4 years.
As they expanded to 6 countries, Google’s monthly bill skyrocketed.

Their CTO asked:
“Can we migrate to OSM or Mapbox to reduce cost?”

The dev team said:
“Not unless you’re okay with a 2–3 month rewrite.”

After introducing UniMap as a middle layer:

  • They wrapped their existing Google logic into UniMap
  • Swapped provider to Mapbox
  • Saved $25k/month in API costs
  • Migration time was reduced from 3 months to 3 days

Outcome:
Vendor lock-in eliminated. Cost cut. Minimal engineering effort.

Case Study 2: An Automotive OEM Needed Map Support for Multiple Countries

A car company (Infotainment systems) needed maps for:

  • North America → Google
  • Europe → HERE
  • India → MapmyIndia
  • China → AutoNavi

Engineering initially estimated 6 separate map implementations.

Using UniMap:

  • They built one UI layer for the head unit browser
  • Providers could be swapped using a config file
  • OTA updates allowed rapid switching
  • Saved thousands of engineering hours

Outcome:
One unified mapping architecture across all international markets.

Case Study 3: A Tourism App Needed Offline & Custom Styled Maps

A tourism company used Google Maps but wanted fully custom styles and offline usage.

Their solution:
Switch to Mapbox.

Problem:
Their team had no Mapbox experience, and rewriting popups, markers, clustering, layers would take 4–6 weeks.

With UniMap:

  • They quickly switched to Mapbox
  • Added custom Dark/Adventure themes
  • Integrated offline tiles
  • Kept the same code structure

Outcome:
Faster launch, highly custom UI, no retraining needed.

Case Study 4: A Real Estate Company Wanted Multi-Provider Search

Real estate apps need accurate geocoding.

But one provider alone is never enough.

Using UniMap, they built:

  • Primary Geocoder → Google
  • Fallback Geocoder → Mapbox
  • Batch Processing → OSM (free)

The fallback logic was implemented in minutes because UniMap exposes a consistent API.

Outcome:
The company improved address accuracy by 22% without rewriting geocoding logic three times.

Benefits for Companies

1. Massive Cost Savings

Map APIs can become extremely expensive.
UniMap helps you switch to cost-efficient providers instantly.

2. Developer Efficiency

Teams no longer need to learn or maintain 10 different SDKs.

3. Scale Faster Across Regions

Choose the best map provider per geography.
No code rewrites.

4. Lower Business Risk

If a provider:

  • Increases prices
  • Changes terms
  • Gets throttled
  • Has outages

You can switch instantly.

5. Freedom to Innovate

You can test features from multiple map providers easily — 3D, custom tiles, routing engines, traffic layers, etc.

Finally

UniMap isn’t just another mapping library;
it’s a strategy, a safety net, a future-proofing layer, and a product accelerator.

In a world where digital maps are critical for apps in logistics, mobility, real estate, automotive, and travel, UniMap ensures you never get stuck with the wrong provider, wrong pricing, or wrong limitations.

If your product uses maps, UniMap gives you:

  • Flexibility
  • Cost control
  • Simplicity
  • Faster releases
  • Happier developers

It’s the mapping layer every modern company needs.


Bibliography


Subscribe to: Comments (Atom)