{ "openapi": "3.1.0", "info": { "title": "naija-data API", "version": "1", "description": "Free, read-only API for accurate, sourced Nigerian reference data: states, LGAs, wards (INEC registration areas), senatorial districts and federal and state constituencies (INEC), CBN-licensed banks with NUBAN validation, phone numbers (NCC) and vehicle plates. Every record lists its sources. Data version 2026-10-16. Please keep to about 120 requests per minute per IP (enforced on a best-effort basis). Responses may be cached for an hour; for heavy use, install the Python, JavaScript or Go package instead.", "license": { "name": "Data: CC BY 4.0 (Akanji Oluwaseun Gabriel). Code: MIT.", "url": "https://github.com/asgatcreation/naija-data/blob/main/ATTRIBUTION.md" }, "contact": { "name": "Akanji Oluwaseun Gabriel", "url": "https://github.com/asgatcreation/naija-data" } }, "servers": [ { "url": "https://naija-data-api.asgatcreation.workers.dev" } ], "paths": { "/v1/states": { "get": { "summary": "All 36 states and the FCT", "tags": [ "Places" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/State" } } }, "required": [ "count", "data" ] } } } } } } }, "/v1/states/{state}": { "get": { "summary": "One state", "tags": [ "Places" ], "parameters": [ { "name": "state", "in": "path", "required": true, "description": "ISO code, INEC code, P-code, slug, name or alias", "schema": { "type": "string" }, "example": "LA" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/State" } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/states/{state}/lgas": { "get": { "summary": "LGAs of a state", "tags": [ "Places" ], "parameters": [ { "name": "state", "in": "path", "required": true, "description": "Any state identifier", "schema": { "type": "string" }, "example": "FCT" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LGA" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lgas": { "get": { "summary": "All 774 LGAs, or those of one state", "tags": [ "Places" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Any state identifier", "schema": { "type": "string" }, "example": "Kano" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LGA" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lgas/{lga}": { "get": { "summary": "One LGA", "tags": [ "Places" ], "parameters": [ { "name": "lga", "in": "path", "required": true, "description": "P-code (NG025011), INEC code (24-11) or name", "schema": { "type": "string" }, "example": "NG025011" }, { "name": "state", "in": "query", "required": false, "description": "Needed when a name exists in several states", "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LGA" } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Ambiguous name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lgas/{lga}/wards": { "get": { "summary": "Wards (INEC registration areas) of an LGA", "tags": [ "Places" ], "parameters": [ { "name": "lga", "in": "path", "required": true, "description": "P-code, INEC code or name", "schema": { "type": "string" }, "example": "NG025011" }, { "name": "state", "in": "query", "required": false, "description": "Needed when a name exists in several states", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ward" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Ambiguous name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lgas/{lga}/constituencies": { "get": { "summary": "The senatorial district and federal and state constituencies an LGA lies in", "tags": [ "Elections" ], "description": "More than one federal or state constituency when the LGA is split (e.g. Surulere, Lagos).", "parameters": [ { "name": "lga", "in": "path", "required": true, "description": "P-code, INEC code or name", "schema": { "type": "string" }, "example": "NG025020" }, { "name": "state", "in": "query", "required": false, "description": "Needed when a name exists in several states", "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Constituency" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Ambiguous name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/constituencies": { "get": { "summary": "Senatorial districts, federal constituencies and state constituencies (INEC)", "tags": [ "Elections" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "senatorial_district, federal_constituency or state_constituency", "schema": { "type": "string" }, "example": "federal_constituency" }, { "name": "state", "in": "query", "required": false, "description": "Any state identifier", "schema": { "type": "string" }, "example": "Lagos" }, { "name": "q", "in": "query", "required": false, "description": "Exact name or alias (ignoring case and punctuation)", "schema": { "type": "string" }, "example": "Ikeja" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Constituency" } } }, "required": [ "count", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/senatorial-districts": { "get": { "summary": "The 109 senatorial districts (Senate)", "tags": [ "Elections" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Any state identifier", "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Constituency" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/federal-constituencies": { "get": { "summary": "The 360 federal constituencies (House of Representatives)", "tags": [ "Elections" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Any state identifier", "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Constituency" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/state-constituencies": { "get": { "summary": "The 990 state constituencies (State Houses of Assembly; none in the FCT)", "tags": [ "Elections" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Any state identifier", "schema": { "type": "string" }, "example": "Lagos" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Constituency" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/constituencies/{code}": { "get": { "summary": "One senatorial district or constituency", "tags": [ "Elections" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code (SD001, FC001, SC001) or INEC code (FC/001/AB)", "schema": { "type": "string" }, "example": "FC236" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Constituency" } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/constituencies/{code}/lgas": { "get": { "summary": "LGAs a unit covers in full or in part", "tags": [ "Elections" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code", "schema": { "type": "string" }, "example": "FC236" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LGA" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/constituencies/{code}/wards": { "get": { "summary": "Wards that make up a unit", "tags": [ "Elections" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Code", "schema": { "type": "string" }, "example": "SC001" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ward" } } }, "required": [ "count", "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/wards/{ward}": { "get": { "summary": "One ward by INEC code", "tags": [ "Places" ], "parameters": [ { "name": "ward", "in": "path", "required": true, "description": "INEC code", "schema": { "type": "string" }, "example": "24-11-01" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ward" } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/search": { "get": { "summary": "Fuzzy search (typos, aliases, accents)", "tags": [ "Places" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text", "schema": { "type": "string" }, "example": "lagso" }, { "name": "kinds", "in": "query", "required": false, "description": "Comma-separated: state, lga, ward", "schema": { "type": "string" }, "example": "state,lga" }, { "name": "limit", "in": "query", "required": false, "description": "1-50, default 10", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "count", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/banks": { "get": { "summary": "CBN-licensed institutions", "tags": [ "Banks" ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "commercial, merchant, non_interest, payment_service_bank, mobile_money_operator, microfinance, mortgage, development_finance", "schema": { "type": "string" } }, { "name": "active", "in": "query", "required": false, "description": "true (default) or false to include merged/revoked", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Fuzzy name search", "schema": { "type": "string" }, "example": "guaranty" }, { "name": "limit", "in": "query", "required": false, "description": "With q: 1-50", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bank" } } }, "required": [ "count", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/banks/{bank}": { "get": { "summary": "One institution", "tags": [ "Banks" ], "parameters": [ { "name": "bank", "in": "path", "required": true, "description": "Id, CBN code, NIP code, name or alias", "schema": { "type": "string" }, "example": "058" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bank" } }, "required": [ "data" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/validate/nuban": { "get": { "summary": "Check a NUBAN account number (CBN check digit)", "tags": [ "Banks" ], "description": "With `bank`, returns whether the account number is valid for that bank. Without it, lists the banks it could belong to. A valid check digit does not prove the account exists.", "parameters": [ { "name": "account", "in": "query", "required": true, "description": "10-digit account number", "schema": { "type": "string" }, "example": "0000014579" }, { "name": "bank", "in": "query", "required": false, "description": "Bank id, CBN code or name", "schema": { "type": "string" }, "example": "011" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone/{number}": { "get": { "summary": "Validate and describe a Nigerian phone number", "tags": [ "Phone" ], "parameters": [ { "name": "number", "in": "path", "required": true, "description": "Any common format", "schema": { "type": "string" }, "example": "08031234567" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/area-codes": { "get": { "summary": "The NCC's 56 landline area codes", "tags": [ "Phone" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/plates": { "get": { "summary": "Plate colours by category (Road Traffic Regulations 2012)", "tags": [ "Plates" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/plates/{plate}": { "get": { "summary": "Validate and parse a plate number", "tags": [ "Plates" ], "parameters": [ { "name": "plate", "in": "path", "required": true, "description": "Plate number", "schema": { "type": "string" }, "example": "KJA-123AB" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Plate" } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta": { "get": { "summary": "Dataset version, counts and sources", "tags": [ "About" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/health": { "get": { "summary": "Health check", "tags": [ "About" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } }, "State": { "type": "object", "properties": { "code": { "type": "string" }, "iso_code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "inec_code": { "type": "string" }, "pcode": { "type": "string" }, "capital": { "type": "string" }, "zone": { "type": "string" }, "created": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "unverified_fields": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } } } }, "LGA": { "type": "object", "properties": { "code": { "type": "string" }, "state_code": { "type": "string" }, "inec_code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "headquarters": { "type": [ "string", "null" ] }, "senatorial_district": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "unverified_fields": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } } } }, "Ward": { "type": "object", "properties": { "code": { "type": "string" }, "lga_code": { "type": "string" }, "state_code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "senatorial_district": { "type": "string" }, "federal_constituency": { "type": "string" }, "state_constituency": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "unverified_fields": { "type": "array", "items": { "type": "string" } } } }, "Constituency": { "type": "object", "properties": { "kind": { "enum": [ "senatorial_district", "federal_constituency", "state_constituency" ] }, "code": { "type": "string" }, "state_code": { "type": "string" }, "inec_code": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "lga_codes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } } } }, "SearchResult": { "type": "object", "properties": { "kind": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "state_code": { "type": "string" }, "score": { "type": "integer" }, "matched": { "type": "string" } } }, "Bank": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "short_name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "cbn_code": { "type": [ "string", "null" ] }, "nip_code": { "type": [ "string", "null" ] }, "ussd": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_date": { "type": [ "string", "null" ] }, "merged_into": { "type": [ "string", "null" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "unverified_fields": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } } } }, "PhoneNumber": { "type": "object", "properties": { "e164": { "type": "string" }, "local": { "type": "string" }, "national": { "type": "string" }, "type": { "type": "string" }, "prefix": { "type": "string" }, "area": { "type": [ "string", "null" ] }, "network": { "type": [ "string", "null" ] }, "allocated": { "type": "boolean" }, "note": { "type": [ "string", "null" ] } } }, "Plate": { "type": "object", "properties": { "compact": { "type": "string" }, "display": { "type": "string" }, "format": { "type": "string" }, "prefix": { "type": "string" }, "number": { "type": "string" }, "suffix": { "type": "string" }, "state_code": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } } } } }