Maps, styles and events

new milsat.Map(element, options) draws a map in an element, or in the element with that id. The element needs a height.

Options

OptionDefault
apiKeyYour public key. Needed once per page.
centerAll of NigeriaWhere to start.
zoom12 with a center0 is the whole world, 19 a single building.
boundsStart by showing an area: [southWest, northEast].
style"light""light", "dark" or "streets".
mapType"street""street" or "satellite": aerial imagery with roads and labels on top.
minZoommaxZoomLimits on zooming.
interactivetrueSet false for a still map.
gestureHandling"greedy""cooperative" lets the page scroll past the map: ctrl or ⌘ and the wheel zoom it, and two fingers pan it on a phone. Use it for a map in the middle of a long page.
milsatLayertrueShow MilsatMaps' own places and areas.
controlsZoom and scalenavigation, scale, geolocate, fullscreen: true, false or a corner such as "top-left". Zoom buttons show bottom-right; the scale bar is off unless you ask for it. attribution: a corner only, bottom-left by default. The data credits show in full when the map opens and fold down to “© Milsat” and an (i) after five seconds or once the map is used, as OpenStreetMap's attribution guidelines allow; they cannot be removed.

Events

map.on(type, listener) returns a subscription; call its remove() to stop listening. addListener is the same, under Google Maps' name. Click on the map, or on one of MilsatMaps' places:

Live: this is the code below, running.
const map = new milsat.Map(document.getElementById("map"), {
  apiKey: "YOUR_API_KEY",
  center: [3.3792, 6.5244],
  zoom: 14,
  style: "streets",
  controls: { geolocate: true, fullscreen: true },
});
const output = document.getElementById("output");

map.on("click", (event) => {
  output.textContent = `You clicked ${event.lngLat.lat.toFixed(5)}, ${event.lngLat.lng.toFixed(5)}`;
});

// Clicks on MilsatMaps' own places come with the place.
map.on("featureclick", async (event) => {
  const place = await milsat.places.details(event.feature.placeId);
  output.textContent = JSON.stringify(place, null, 2);
});
EventWhen
click, dblclick, contextmenu, mousemove, mousedown, mouseupThe pointer. The event has lngLat and point.
featureclickA click on one of MilsatMaps' places. event.feature.placeId goes to places.details.
movestart, move, moveend, zoomstart, zoom, zoomendThe view changing.
loadOnce, when the map can be drawn on. await map.ready does the same.
styleA style finished loading, MilsatMaps' layers included.
errorSomething failed, such as the key being refused. The base map still shows.

Styles

Three looks, switchable at any time with map.setStyle(…). Markers, popups and shapes added through the SDK stay on the map.

Live: this is the code below, running.
const map = new milsat.Map(document.getElementById("map"), {
  apiKey: "YOUR_API_KEY",
  center: [3.4219, 6.4281],
  zoom: 12,
  style: "dark",
});
new milsat.Marker({ position: [3.4219, 6.4281], map, title: "Victoria Island" });

// Switch after a few seconds. Markers and shapes stay.
setTimeout(() => map.setStyle("light"), 3000);

Separately, map.setMapType("satellite") draws aerial imagery with roads, places and MilsatMaps' layer on top, and map.setMapType("street") goes back. On satellite the style no longer changes the map. The imagery is Sentinel-2 cloudless, which is 10 m imagery and soft at street level; milsat.config({ imagery: { tiles, attribution, maxzoom } }) uses another source you have a licence for.

Layers that need approval

Postcode layers need Milsat's approval: districts (zoom 11 to 13), areas (from zoom 14) and buildings (from zoom 17, a dot and the last four characters of each postcode). Ask for them in the console, under your project's Data access. Once a layer is approved your maps draw it with no code change. Postcodes are drawn by the platform as images; lookups return a postcode's point, never its outline.

map.on("load", () => {
  map.getApprovedLayers(); // e.g. ["postcode_areas", "postcode_units"]
});
map.setPostcodesVisible(false);          // hide them
map.setPostcodeSelection("FC02D43KU");   // highlight one, e.g. after a lookup

For the full postcode where someone taps, call reverseGeocode: it returns the building's postcode, or the area's when the tap is not on a building.

Moving the map

map.setCenter([3.38, 6.52]);
map.setZoom(15);
map.panTo({ lat: 6.45, lng: 3.42 });          // smoothly, keeping the zoom
map.flyTo({ center: [3.42, 6.45], zoom: 16 });
map.fitBounds([[3.30, 6.40], [3.45, 6.65]], { padding: 40 });

map.getCenter();  // { lng, lat }
map.getZoom();
map.getBounds();  // { west, south, east, north }

Beyond this API

The map is drawn by MapLibre GL. map.maplibre is that map, for anything this API does not cover. Layers you add there yourself are dropped when the style changes; add them again in a style event listener.

map.remove() removes the map and stops its requests. Call it when your page or component goes away.