Developer API

Public read-only endpoints for civic data, freshness, and district profiles — all served from Lankawa.

Getting started

All endpoints are same-origin JSON APIs. No API key is required for read access. Responses include freshness tiers and internal provenance paths.

Base URL: /api/v1

Data export

Download curated datasets from the Lankawa API — same provenance as in-app data.

District boundaries

Download GeoJSON Download CSV

Election results

Download JSON Download CSV

Public services

Download JSON Download CSV

Fuel history

Download JSON Download CSV

Land change indices

Download JSON Download CSV

Foreign debt composition

Download JSON Download CSV

Embeddable widgets

Same-origin iframe widgets for today, pulse, fuel, and FX — preview and copy embed code on the embed page.

Open embed preview

Widget SDK snippet

Beyond iframes — drop-in script scaffold that mounts a same-origin embed. Prefer iframe for production until the npm package ships.

<div id="lankawa-widget" data-widget="brief"></div>
<script src="https://lankawa.vercel.app/embed/widget.js" defer></script>

Signed change webhooks

Partners can verify changelog deliveries with HMAC-SHA256. Sign the raw JSON body; send header X-Lankawa-Signature: sha256=<hex>. Helper: signWebhookBody / verifyWebhookSignature in src/lib/webhook-hmac.ts. Set LANKAWA_WEBHOOK_SECRET when a delivery endpoint is enabled.

X-Lankawa-Signature: sha256=<hmac-sha256-hex-of-body>

Endpoints

GET/api/v1/health

Source health

Freshness tiers and last-checked timestamps for every registered data source.

{ "generatedAt": "2026-07-19T06:00:00.000Z", "sources": [...] }

GET/api/v1/pulse

Live pulse

Current exchange rates, fuel prices, flood station counts, and related metrics.

{ "generatedAt": "...", "metrics": [...], "flood": [...], "sources": [...] }

GET/api/v1/districts

District list

All 25 Sri Lankan districts with population, area, and province metadata.

{ "districts": [{ "slug": "colombo", "name": "Colombo", ... }] }

GET/api/v1/districts/{slug}

District detail

Single district profile keyed by slug.

{ "slug": "colombo", "name": "Colombo", "population": 2427285, ... }

GET/api/v1/provinces

Province list

All 9 Sri Lankan provinces with slug and trilingual names.

{ "count": 9, "provinces": [{ "slug": "western", "name": "Western", ... }] }

GET/api/v1/provinces/{slug}

Province detail

Single province profile with aggregated population, area, and district list.

{ "slug": "western", "districtCount": 3, "population": 5846400, ... }

GET/api/v1/elections

Presidential election 2024

National summary and district-level first-preference results with provenance paths.

{ "election": { "id": "presidential-2024", ... }, "districts": [...] }

GET/api/v1/elections/parliamentary

Parliamentary election 2024

National seat summary and all electoral district results.

{ "election": { "id": "parliamentary-2024", ... }, "districts": [...] }

GET/api/v1/elections/parliamentary/{slug}

Parliamentary electoral district

Seat allocation for a single electoral district (e.g. colombo, vanni).

{ "slug": "colombo", "totalSeats": 18, "seats": { "npp": 14, ... } }

GET/api/v1/services?district=colombo&type=hospital

Public services

Filter hospitals, schools, and GN offices by district, type, or search query.

{ "count": 2, "facilities": [{ "id": "colombo-national-hospital", ... }] }

GET/api/v1/services/{id}

Service facility detail

Single public service facility by ID.

{ "id": "colombo-national-hospital", "type": "hospital", ... }

GET/api/v1/flood/history?station=Peradeniya&limit=24

Flood station history

Historical water levels for a river monitoring station with freshness tier.

{ "points": [{ "timestamp": "...", "waterLevel": 1.39 }], "tier": "fresh" }

GET/api/v1/fuel/history?days=90

Fuel price history

CPC petrol 92 and auto diesel price series from the Octane partner API.

{ "days": 90, "series": [{ "fuelType": "petrol_92", "points": [...] }] }

GET/api/v1/fuel/revisions?limit=8

Fuel revision steps

CPC petrol 92 and auto diesel official revision events with price deltas from Octane.

{ "limit": 8, "steps": [{ "fuelType": "petrol_92", "deltaLkr": -20 }] }

GET/api/v1/budget

National budget

FY 2024/25 and 2025/26 revenue, expenditure, and sector allocations (seed).

{ "fiscalYears": [{ "id": "fy2025-26", "revenue": 4580, ... }] }

GET/api/v1/health/dengue

Dengue weekly statistics

District-level dengue case counts from the Epidemiology Unit seed dataset.

{ "nationalTotal": 3842, "districts": [{ "slug": "colombo", "cases": 612 }] }

GET/api/v1/property

Property price bands

District-level median land price bands with low/high ranges.

{ "districts": [{ "slug": "colombo", "medianPerPerch": 9500000, ... }] }

GET/api/v1/elections/history

Election history

Multi-cycle presidential summaries and parliamentary seat history.

{ "presidential": { "cycles": [{ "year": 2024, ... }] }, "parliamentary": { ... } }

GET/api/v1/local-government?district=colombo&type=MC

Local government directory

Filter MC, UC, and PS bodies by district, type, or search query.

{ "totalCount": 327, "count": 1, "bodies": [{ "id": "...", "type": "MC" }] }

GET/api/v1/transport?district=colombo

Transport directory

Bus routes, railway stations, and airports filterable by district.

{ "busRoutes": [...], "railwayStations": [...], "airports": [...] }

GET/api/v1/cost-of-living

Cost of living index

District composite index from fuel, property, and food basket seeds.

{ "nationalIndex": 72, "districts": [{ "slug": "colombo", "index": 98 }] }

GET/api/v1/vehicles

Vehicle market snapshot

District median used-vehicle prices, popular makes, and listing counts.

{ "totalListings": 112609, "districts": [{ "slug": "colombo", "medianPriceLkr": 9314924 }] }

GET/api/v1/food

Food price snapshot

Staple prices, essentials basket, and district meal-cost bands.

{ "essentialsBasketLkr": 8650, "stapleItems": [{ "name": "Rice", "priceLkr": 320 }] }

GET/api/v1/life

Life platform overview

Unified living-cost domain health from the Ariva Life Platform orchestrator.

{ "headline": "...", "domains": [{ "key": "food", "status": "degraded" }] }

GET/api/v1/export/districts

Export districts GeoJSON

Download simplified district boundaries with provenance metadata, including CSV.

GeoJSON FeatureCollection download; add ?format=csv for CSV

GET/api/v1/export/elections

Export elections

Download presidential and parliamentary 2024 seed datasets as JSON or CSV.

{ "presidential": {...}, "parliamentary": {...} }; add ?format=csv for CSV

GET/api/v1/export/services

Export services

Download the full public services directory seed as JSON or CSV.

{ "facilities": [...], "sourceId": "public_services_seed" }; add ?format=csv for CSV

GET/api/v1/export/fuel-history?format=csv

Export fuel history

Download petrol and diesel price history as JSON or CSV.

fuelType,label,recordedAt,priceLkr,...

GET/api/v1/environment/land-change

Land Change Pulse

District greenery and built-up indices (2018→2024) with national deltas and top movers.

{ "national": { "greeneryDelta": -4 }, "districts": [...], "provenancePath": "/sources/lankawa_land_pulse" }

GET/api/v1/economy/debt

Foreign debt composition

Commercial vs concessionary external debt share series (2004–2020), normalized for Lankawa.

{ "latest": { "year": 2020, "commercialPct": 53.8 }, "series": [...], "provenancePath": "/sources/lankawa_debt_pulse" }

GET/api/v1/economy/ncpi

NCPI inflation

Latest NCPI headline YoY/MoM, core, food/non-food splits, and recent monthly series from DCS.

{ "periodLabel": "March 2026", "latest": { "yoyPct": 2.4, "momPct": 0.7 }, "provenancePath": "/sources/dcs_ncpi" }

GET/api/v1/economy/tariffs

PUCSL domestic tariffs

Residential electricity energy and fixed charges by consumption block with effective date.

{ "effectiveFrom": "2025-06-12", "tracks": [{ "id": "above_60", "slabs": [...] }], "provenancePath": "/sources/pucsl_tariff" }

GET/api/v1/economy/water-bill?units=20

NWSDB water bill estimate

Domestic/Samurdhi water tariff slabs with seed estimate and optional live BillCalculator totals.

{ "seedEstimate": { "totalLkr": 2537 }, "liveAvailable": true, "provenancePath": "/sources/nwsdb_tariff" }

GET/api/v1/cse/quotes?symbols=JKH.N0000,COMB.N0000

CSE per-symbol quotes

Company quotes from cse.lk companyInfoSummery for a comma-separated symbol list, with seed fallback.

{ "generatedAt": "...", "quotes": [{ "symbol": "JKH.N0000", "price": 22.1 }], "provenancePath": "/sources/cse_lk" }

GET/api/v1/export/land-change?format=csv

Export land change

Download district greenery and built-up indices as JSON or CSV.

slug,greenery2018,greenery2024,greeneryDelta,...

GET/api/v1/export/foreign-debt?format=csv

Export foreign debt composition

Download commercial vs concessionary debt share series as JSON or CSV.

year,commercialPct,concessionaryPct,...

GET/api/v1/disaster/landslide

Landslide early warning

District watch/warning from lk_dmc tip layout parse, with seed honesty when unavailable.

{ "watchCount": 5, "warningCount": 0, "districts": [...], "isSeed": true }

GET/api/v1/changes

Product changelog

Curated Lankawa surface changelog entries.

{ "count": 4, "entries": [{ "date": "2026-07-19", "title": "..." }] }

POST/api/v1/subscribe

Morning brief subscribe

Double opt-in email subscription for the cached morning brief.

{ "ok": true, "message": "Check your email to confirm the morning brief." }

GET/api/v1/openapi.json

OpenAPI specification

Machine-readable OpenAPI 3.1 document for the public API.

{ "openapi": "3.1.0", "info": { ... }, "paths": { ... } }

GET/api/v1/status

Platform status

Database connectivity, source freshness counts, API version, and ingest schedule.

{ "version": "0.6.0", "database": { "configured": true, "connected": true }, "sources": { "fresh": 3 } }

GET/api/v1/pulse/history

Pulse history

Stored pulse snapshots for the last 30 days (requires database).

{ "days": 30, "count": 42, "snapshots": [...] }

POST/api/v1/assistant

Civic assistant

POST a question; receive an answer grounded on Lankawa API data with citations.

{ "question": "USD rate?", "answer": "...", "citations": [...], "mode": "rule" }

Data provenance

Every metric references a source ID and an internal provenance path. Use the sources registry to understand methodology and freshness.

Browse data sources

OpenAPI document

View the full OpenAPI specification rendered inside Lankawa, or fetch the raw JSON from the API.

View OpenAPI JSON