The map

This page is the map itself: what the floating panel offers your users, the hooks your app receives, and the controller you drive it with. Install and authentication are on the overview.

Options

const controller = await createLociMap(container, options);

Option	Type	What it does
`baseUrl`	`string`	The LOCI API origin.
`auth`	`{ apiKey }` or `{ shareToken }`	A scoped API key, or a read-only project share token.
`mapboxToken`	`string?`	Optional — omitted, the SDK borrows the deployment’s token with your credential.
`orgId` / `projectId`	`string?`	Which datasets to list. With an API key both are optional — the key resolves its own org.
`title`, `subtitle`	`string?`	The floating panel’s header.
`basemap`	`"dark" \| "light" \| "satellite" \| "streets" \| "3d"`	The first style; defaults to `dark`. Users switch from the toolbar.
`center`, `zoom`	`[lng, lat]`, `number`	The first view.
`analysisDatasetId`	`string?`	The dataset “Analyse this area” totals (defaults to the first population baseline the key can see).
`physicalDatasetId`	`string?`	The slope and land-cover baseline that enables off-road travel-time estimates.
`onAnalyze`	`(result: PolygonAnalysis) => void`	Every area analysis, for your own handling.
`onExport`	`(exp: MapExport) => void`	Every export (see below). Without it, exports download as files.
`onFrameSelect`	`(frames: Frame[]) => void`	A frame was selected on the grid.
`state`	`MapState?`	A previously exported map state to restore.

Datasets

The panel lists every dataset the key can read, each with:

A toggle. Points, lines and polygons render as an overlay; a frame-keyed baseline renders as a choropleth with a legend, from zoom 8 up (the widget says “Zoom in to see…” when toggled at country zoom).
A colour swatch with a palette and a No colour option. No colour paints nothing: polygons and frames render as hollow outlines, points as hollow rings — no grey stand-in, no legend.
A label picker (Aa) listing the dataset’s own columns under their data-dictionary names. The chosen attribute is written beside every feature on the map — settlements by name, facilities by is_active, anything the data carries. Booleans and numbers render too.

Clicking a feature opens its record in the panel: every attribute, labelled by the dataset’s data dictionary.

The place filter

The header chip opens a State → LGA → Ward cascade built from the national frame index. Picking a unit flies the camera to it immediately and replaces the viewport grid with exactly that unit’s frames, loading behind the moving camera.

The filter scopes the frame grid, not the data layers: dataset overlays and choropleths still load by viewport, and area analysis always measures the drawn polygon as drawn — a polygon crossing the selected LGA’s boundary includes what lies outside it. Draw inside the unit if the unit is the question.

Frames and what is inside them

At zoom 8 and up the national frame grid draws over the map. Clicking a frame opens it in the panel:

its administrative assignment (State, LGA, Ward, Zone),
the values every enabled baseline records on it,
In this frame — every feature of the key’s ordinary datasets whose geometry falls in the cell, each expandable in place to its full record.

the panel, after clicking a frame

Frame 2163706
State   FCT
LGA     ABUJA MUNICIPAL AREA COUNCIL
Ward    WUSE

IN THIS FRAME · 1
› Medicaid Radioagnostic        Health facilities (NHFR)
    Facility level              Primary
    Ownership                   Public
    …

Drawing

Drawing is first-class: a shape is whatever your product makes of it — a work area, a site, a zone — and analysing it is just one of the actions on it.

Shapes persist on the map and reopen on click; double-click edits points.
A shape can be reshaped but never dragged whole — a slipped click cannot silently move a work area.
Once anything is drawn, a Drawings row appears under the dataset list with a live count. Unchecking it hides every drawn shape (they stay in exports); starting a new drawing shows them again.

The drawing’s screen offers Analyse this area, Export drawings and Delete this shape.

Area analysis

Analysing a drawn polygon asks the API for:

Totals — area-weighted population (or any additive metric the analysis dataset carries), area, density, and how much of the polygon has data.
Amenities — for each enabled facility-like dataset: how many features fall inside, and the nearest one with its distance.
Travel time — with physicalDatasetId set: minutes to the nearest facility by walking, motorbike and vehicle, over slope and land cover.

The same result reaches your app through onAnalyze, so you can store it, chart it, or build a report from it.

Measuring

Shift-click two features — any geometry, across datasets — for the distance between them (edge to edge and centre to centre for polygons) and road directions where available. The measure tool on the toolbar does the same from arbitrary points. ⌘/Ctrl-click builds a multi-selection; ⌘K opens a command palette with every action.

Basemaps

The toolbar’s basemap button opens a picker: dark, light, satellite, streets, 3D (Mapbox Standard). Switching rebuilds the grid, the filtered frames and every enabled overlay; drawn shapes survive, and the camera stays where the user put it.

Export and restore

The toolbar’s export button offers the whole workspace in three forms:

Image (PNG) — the view with the legend, a scale bar and attribution.
Map (JSON) — a restorable MapState: camera, basemap, place filter, datasets with colours and label choices, drawings and their visibility. Pass it back as state to reopen the exact view. It references datasets by id only — contents reload through the API, so licensing travels with the key, never with the file.
Drawings (GeoJSON) — just the shapes, for QGIS, ArcGIS or your pipeline.

receiving exports

createLociMap(el, {
  // …
  onExport: (exp) => {
    if (exp.kind === "map") saveWorkspace(exp.state);  // JSON state
    if (exp.kind === "drawings") store(exp.drawings);  // GeoJSON FC
    if (exp.kind === "image") upload(exp.blob);        // PNG blob
  },
});

With the hosted embed, exports arrive as a cancelable loci:export CustomEvent on the mount element (event.detail is the MapExport); call event.preventDefault() to take it, or let it fall through to a file download.

The controller

createLociMap resolves to a controller:

controller.map;              // the underlying mapboxgl.Map
controller.getState();       // MapState — persist it, restore with `state`
controller.getDrawings();    // GeoJSON FeatureCollection of drawn shapes
controller.exportImage();    // Promise<Blob> — the composed PNG
controller.setSidebarPosition({ x, y });
controller.destroy();

Analysis results are deliberately not part of MapState. Restoring a state brings back the drawings, not their numbers: analysis runs only when a user clicks Analyse this area on a shape, and then against current data under the opening key. Persist results from onAnalyze if your product needs yesterday’s figures — for example to build a report alongside exportImage() and getState().

Web (JavaScript)

Flutter

Android (Kotlin)

Native

Options

Datasets

The place filter

Frames and what is inside them

Drawing

Area analysis

Measuring

Basemaps

Export and restore

The controller