Back to developer docs
OpenAPI document
Machine-readable specification for the Lankawa public API.
{
"openapi": "3.1.0",
"info": {
"title": "Lankawa Public API",
"version": "0.8.0",
"description": "Public civic intelligence API for Sri Lanka. Every metric includes source provenance and freshness tiers."
},
"servers": [
{
"url": "/api/v1"
}
],
"paths": {
"/news": {
"get": {
"summary": "Sri Lanka news pulse",
"responses": {
"200": {
"description": "Recent RSS headlines from EN/SI/TA outlets with freshness provenance"
}
}
}
},
"/news/clusters": {
"get": {
"summary": "News story clusters",
"responses": {
"200": {
"description": "Multi-outlet story clusters (Jaccard title similarity) with stable cluster ids and member headlines"
}
}
}
},
"/cse": {
"get": {
"summary": "Colombo Stock Exchange snapshot",
"responses": {
"200": {
"description": "ASPI/S&P SL20, movers, market summary, and exchange notices"
}
}
}
},
"/cse/quotes": {
"get": {
"summary": "CSE per-symbol quotes (companyInfoSummery)",
"parameters": [
{
"name": "symbols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated CSE symbols, e.g. JKH.N0000,COMB.N0000"
}
],
"responses": {
"200": {
"description": "Quotes from companyInfoSummery with seed fallback"
}
}
}
},
"/brief": {
"get": {
"summary": "Trilingual morning brief",
"parameters": [
{
"name": "locale",
"in": "query",
"schema": {
"type": "string",
"enum": [
"en",
"si",
"ta"
]
}
}
],
"responses": {
"200": {
"description": "Quality-gated morning brief bullets derived from news pulse"
}
}
}
},
"/health": {
"get": {
"summary": "Source health and freshness",
"responses": {
"200": {
"description": "Health snapshot"
}
}
}
},
"/pulse": {
"get": {
"summary": "Live pulse metrics",
"responses": {
"200": {
"description": "Pulse snapshot"
}
}
}
},
"/districts": {
"get": {
"summary": "List all districts",
"responses": {
"200": {
"description": "District list"
}
}
}
},
"/districts/{slug}": {
"get": {
"summary": "Get district by slug",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "District profile"
},
"404": {
"description": "Not found"
}
}
}
},
"/provinces": {
"get": {
"summary": "List all provinces",
"responses": {
"200": {
"description": "Province list"
}
}
}
},
"/provinces/{slug}": {
"get": {
"summary": "Get province by slug",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Province profile with districts"
},
"404": {
"description": "Not found"
}
}
}
},
"/elections": {
"get": {
"summary": "Presidential election 2024 summary",
"responses": {
"200": {
"description": "Election data snapshot"
}
}
}
},
"/elections/parliamentary": {
"get": {
"summary": "Parliamentary election 2024 summary",
"responses": {
"200": {
"description": "Parliamentary election snapshot"
}
}
}
},
"/elections/parliamentary/{slug}": {
"get": {
"summary": "Parliamentary district seats",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Electoral district result"
},
"404": {
"description": "Not found"
}
}
}
},
"/services": {
"get": {
"summary": "Public services directory",
"parameters": [
{
"name": "district",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"hospital",
"school",
"gn_office",
"police_station",
"moh_office",
"divisional_hospital"
]
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Filtered facilities list"
}
}
}
},
"/services/{id}": {
"get": {
"summary": "Single public service facility",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Facility detail"
},
"404": {
"description": "Not found"
}
}
}
},
"/flood/history": {
"get": {
"summary": "Flood station level history",
"parameters": [
{
"name": "station",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 24
}
}
],
"responses": {
"200": {
"description": "Historical water levels with freshness tier"
}
}
}
},
"/fuel/history": {
"get": {
"summary": "CPC fuel price history",
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"default": 90
}
}
],
"responses": {
"200": {
"description": "Petrol 92 and auto diesel price series"
}
}
}
},
"/budget": {
"get": {
"summary": "National budget snapshot",
"responses": {
"200": {
"description": "FY 2024/25 and 2025/26 budget seed data"
}
}
}
},
"/environment": {
"get": {
"summary": "Air quality snapshot",
"responses": {
"200": {
"description": "District AQI and PM2.5 readings with live OpenAQ overlay when available"
}
}
}
},
"/environment/land-change": {
"get": {
"summary": "Land Change Pulse",
"responses": {
"200": {
"description": "District greenery and built-up indices (2018→2024) with national deltas and top movers"
}
}
}
},
"/economy/debt": {
"get": {
"summary": "Foreign debt composition pulse",
"responses": {
"200": {
"description": "Commercial vs concessionary external debt share series (2004–2020), normalized for Lankawa"
}
}
}
},
"/economy/ncpi": {
"get": {
"summary": "NCPI inflation snapshot",
"responses": {
"200": {
"description": "Latest NCPI headline YoY/MoM, core, food/non-food, and recent monthly series"
}
}
}
},
"/economy/tariffs": {
"get": {
"summary": "PUCSL domestic electricity tariffs",
"responses": {
"200": {
"description": "Residential energy and fixed charges by consumption block with effective date"
}
}
}
},
"/economy/water-bill": {
"get": {
"summary": "NWSDB water bill estimate",
"parameters": [
{
"name": "units",
"in": "query",
"required": false,
"schema": {
"type": "number",
"default": 20
},
"description": "Monthly consumption in cubic metres (m³)"
},
{
"name": "days",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 30
},
"description": "Billing period days for live BillCalculator request"
},
{
"name": "track",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"domestic",
"samurdhi"
],
"default": "domestic"
},
"description": "Tariff track id (domestic or Samurdhi/tenement)"
}
],
"responses": {
"200": {
"description": "Domestic/Samurdhi water tariff slabs with seed estimate and optional live BillCalculator totals"
}
}
}
},
"/disaster/landslide": {
"get": {
"summary": "Landslide early-warning snapshot",
"responses": {
"200": {
"description": "District watch/warning from lk_dmc tip layout parse, with seed honesty when unavailable"
}
}
}
},
"/changes": {
"get": {
"summary": "Product changelog",
"responses": {
"200": {
"description": "Curated Lankawa surface changelog entries"
}
}
}
},
"/subscribe": {
"post": {
"summary": "Morning brief email opt-in",
"responses": {
"200": {
"description": "Subscription accepted (confirm via email when mailer configured)"
},
"400": {
"description": "Invalid email"
},
"503": {
"description": "Database not configured"
}
}
}
},
"/tenders": {
"get": {
"summary": "Government procurement tender notices",
"parameters": [
{
"name": "district",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "province",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "category",
"in": "query",
"schema": {
"type": "string",
"enum": [
"goods",
"works",
"services"
]
}
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"open",
"closing_soon",
"closed"
]
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Filtered tender notices with live PROMISe fallback provenance"
}
}
}
},
"/health/dengue": {
"get": {
"summary": "Weekly dengue statistics",
"responses": {
"200": {
"description": "District-level dengue case counts with Epidemiology Unit live parse when available"
}
}
}
},
"/analytics/event": {
"post": {
"summary": "Retention analytics event (no PII)",
"responses": {
"200": {
"description": "Accepted retention event"
}
}
}
},
"/property": {
"get": {
"summary": "District property price bands",
"responses": {
"200": {
"description": "Median land price bands by district"
}
}
}
},
"/elections/history": {
"get": {
"summary": "Multi-cycle election history",
"responses": {
"200": {
"description": "Presidential 2010–2024 and parliamentary summaries"
}
}
}
},
"/local-government": {
"get": {
"summary": "Local government directory",
"parameters": [
{
"name": "district",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string",
"enum": [
"MC",
"UC",
"PS"
]
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Filtered local bodies list"
}
}
}
},
"/transport": {
"get": {
"summary": "Transport directory",
"parameters": [
{
"name": "district",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bus routes, railway stations, and airports"
}
}
}
},
"/cost-of-living": {
"get": {
"summary": "District cost of living index",
"responses": {
"200": {
"description": "Composite index from fuel, property, and food basket seeds"
}
}
}
},
"/vehicles": {
"get": {
"summary": "Vehicle market snapshot",
"responses": {
"200": {
"description": "District median used-vehicle prices and popular makes"
}
}
}
},
"/food": {
"get": {
"summary": "Food price snapshot",
"responses": {
"200": {
"description": "Staple prices and district meal-cost bands"
}
}
}
},
"/life": {
"get": {
"summary": "Life platform overview",
"responses": {
"200": {
"description": "Unified living-cost domain health from Ariva Life Platform"
}
}
}
},
"/export/{dataset}": {
"get": {
"summary": "Dataset export",
"parameters": [
{
"name": "dataset",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"districts",
"elections",
"services",
"fuel-history"
]
}
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string",
"enum": [
"csv",
"geojson",
"json"
]
}
}
],
"responses": {
"200": {
"description": "GeoJSON, JSON, or CSV download"
},
"404": {
"description": "Unknown dataset"
}
}
}
},
"/status": {
"get": {
"summary": "Platform health (DB, sources, version)",
"responses": {
"200": {
"description": "Platform status snapshot"
}
}
}
},
"/pulse/history": {
"get": {
"summary": "Pulse snapshot history (last 30 days, requires DB)",
"responses": {
"200": {
"description": "Historical pulse snapshots"
},
"503": {
"description": "Database not configured"
}
}
}
},
"/assistant": {
"post": {
"summary": "Civic assistant Q&A grounded on Lankawa data",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string"
}
},
"required": [
"question"
]
}
}
}
},
"responses": {
"200": {
"description": "Answer with citations"
}
}
}
}
}
}