trueset
Sign in Get started
Product Datasets Pricing Docs Status Sign in Get started

API docs

All paths start with https://trueset.timileyin.dev/v1.

Get an API key OpenAPI spec

Quick start

Paste this into a terminal. You don't need a key: you get 20 requests a day and the core fields. Add a key from a paid plan for higher limits and every field.

Shell 
curl "https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=2"

Response

JSON 
{
  "data": [
    {
      "code": "NG025001",
      "id": "lga_01M3MZBEBF38X6KGEHRKRJ402V",
      "name": "Agege",
      "state": {
        "code": "NG-LA",
        "id": "state_01M3MZBDZ0FRB1W27FX3HGFE3P",
        "name": "Lagos"
      },
      "updated_at": "2026-09-28T22:40:41.002811+01:00",
      "verification": {
        "method": "cross_referenced",
        "retrieved_at": "2026-09-06",
        "source_id": "src_01M3MZBE2TYZ54M5788NA0F09V",
        "status": "verified",
        "verified_at": "2026-09-28T21:40:41.002811+00:00",
        "verified_by": "timileyin",
        "version": 1
      }
    },
    {
      "code": "NG025002",
      "id": "lga_01M3MZBEBGEP51RX5HNM39J6Q5",
      "name": "Ajeromi/Ifelodun",
      "state": {
        "code": "NG-LA",
        "id": "state_01M3MZBDZ0FRB1W27FX3HGFE3P",
        "name": "Lagos"
      },
      "updated_at": "2026-09-28T22:40:41.002811+01:00",
      "verification": {
        "method": "cross_referenced",
        "retrieved_at": "2026-09-06",
        "source_id": "src_01M3MZBE2TYZ54M5788NA0F09V",
        "status": "verified",
        "verified_at": "2026-09-28T21:40:41.002811+00:00",
        "verified_by": "timileyin",
        "version": 1
      }
    }
  ],
  "next": "lga_01M3MZBEBGEP51RX5HNM39J6Q5"
}

Examples by dataset

List the LGAs in a state, two per page.

Shell 
curl "https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=2"

Response

JSON 
{
  "data": [
    {
      "code": "NG025001",
      "id": "lga_01M3MZBEBF38X6KGEHRKRJ402V",
      "name": "Agege",
      "state": {
        "code": "NG-LA",
        "id": "state_01M3MZBDZ0FRB1W27FX3HGFE3P",
        "name": "Lagos"
      },
      "updated_at": "2026-09-28T22:40:41.002811+01:00",
      "verification": {
        "method": "cross_referenced",
        "retrieved_at": "2026-09-06",
        "source_id": "src_01M3MZBE2TYZ54M5788NA0F09V",
        "status": "verified",
        "verified_at": "2026-09-28T21:40:41.002811+00:00",
        "verified_by": "timileyin",
        "version": 1
      }
    },
    {
      "code": "NG025002",
      "id": "lga_01M3MZBEBGEP51RX5HNM39J6Q5",
      "name": "Ajeromi/Ifelodun",
      "state": {
        "code": "NG-LA",
        "id": "state_01M3MZBDZ0FRB1W27FX3HGFE3P",
        "name": "Lagos"
      },
      "updated_at": "2026-09-28T22:40:41.002811+01:00",
      "verification": {
        "method": "cross_referenced",
        "retrieved_at": "2026-09-06",
        "source_id": "src_01M3MZBE2TYZ54M5788NA0F09V",
        "status": "verified",
        "verified_at": "2026-09-28T21:40:41.002811+00:00",
        "verified_by": "timileyin",
        "version": 1
      }
    }
  ],
  "next": "lga_01M3MZBEBGEP51RX5HNM39J6Q5"
}

Get a bank and its code. Use ?code= or ?q= on /v1/banks to search.

Shell 
curl "https://trueset.timileyin.dev/v1/banks/access-bank"

Response

JSON 
{
  "category": "bank",
  "code": "044",
  "id": "bank_01M3SCB7DZD3HQAFHH6KVMDA4A",
  "name": "Access Bank",
  "slug": "access-bank",
  "updated_at": "2026-09-30T15:44:03.720808+01:00",
  "verification": {
    "method": "community",
    "retrieved_at": "2026-09-30",
    "source_id": "src_01M3SCB7DDFFWH3R72459JNKJR",
    "status": "verified",
    "verified_at": "2026-09-30T14:44:03.720808+00:00",
    "verified_by": "timileyin",
    "version": 1
  }
}

Find the network a number was issued on. A ported number still reports its original network.

Shell 
curl "https://trueset.timileyin.dev/v1/phone-prefixes/lookup?number=08031234567"

Response

JSON 
{
  "id": "pfx_01M3SCB7PMJ3FVVGH34V2KVGRV",
  "international": "+2348031234567",
  "number": "08031234567",
  "operator": "MTN",
  "prefix": "0803",
  "updated_at": "2026-09-30T15:44:03.534674+01:00",
  "verification": {
    "method": "official_document",
    "retrieved_at": "2026-09-30",
    "source_id": "src_01M3SCB7P21BGCN694WX0T3NDH",
    "status": "verified",
    "verified_at": "2026-09-30T14:44:03.534674+00:00",
    "verified_by": "timileyin",
    "version": 1
  }
}

List a year's public holidays. Dates marked tentative have not been announced yet. The response is shortened to the first holiday.

Shell 
curl "https://trueset.timileyin.dev/v1/holidays?year=2026"

Response

JSON 
{
  "data": [
    {
      "date": "2026-01-01",
      "id": "hol_01M3SCB7VNA659KXTQKQT006ZH",
      "kind": "fixed",
      "name": "New Year's Day",
      "tentative": false,
      "updated_at": "2026-09-30T15:44:03.627037+01:00",
      "verification": {
        "method": "official_document",
        "retrieved_at": "2026-09-30",
        "source_id": "src_01M3SCB7VJ2FWYS2D0X73S75K7",
        "status": "verified",
        "verified_at": "2026-09-30T14:44:03.627037+00:00",
        "verified_by": "timileyin",
        "version": 1
      }
    }
  ]
}

Convert between currencies at the day's central rate. Add date= to use a past rate. Key

Shell 
curl -H "Authorization: Bearer $TRUESET_KEY" \
  "https://trueset.timileyin.dev/v1/exchange-rates/convert?from=USD&to=NGN&amount=100"

Response

JSON 
{
  "amount": 100,
  "date": "2026-09-29",
  "from": "USD",
  "rate": 1329.9737,
  "result": 132997.37,
  "to": "NGN"
}

Get a coin's price in US dollars and naira. Key

Shell 
curl -H "Authorization: Bearer $TRUESET_KEY" \
  "https://trueset.timileyin.dev/v1/crypto/prices/BTC"

Response

JSON 
{
  "change_24h_percent": -0.16402,
  "market_cap_usd": 1681074704889,
  "name": "Bitcoin",
  "price_ngn": 111097658,
  "price_usd": 83687,
  "rank": 1,
  "symbol": "BTC",
  "updated_at": "2026-09-30T15:52:53.038476+01:00"
}

Client examples

Shell 
curl "https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=2"
JavaScript 
const res = await fetch("https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=2");
const { data, next } = await res.json();

for (const lga of data) {
  console.log(lga.name, lga.verification.status);
}
Python 
import requests

r = requests.get(
    "https://trueset.timileyin.dev/v1/states/NG-LA/lgas",
    params={"limit": 2},
)
r.raise_for_status()

for lga in r.json()["data"]:
    print(lga["name"], lga["verification"]["status"])
Ruby 
require "net/http"
require "json"

uri = URI("https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=2")
body = JSON.parse(Net::HTTP.get(uri))

body["data"].each do |lga|
  puts "#{lga["name"]}: #{lga["verification"]["status"]}"
end

Authentication

Send your key in the Authorization header.

Shell 
curl -H "Authorization: Bearer ts_62e0f9c5_..." \
  "https://trueset.timileyin.dev/v1/wards?limit=5"

Create keys on your account page. We show each key once, so copy it somewhere safe. If a key leaks, revoke it and it stops working straight away.

Rate limits

Rate limits and access by plan
Limit No key Starter Growth Business
Rate limits
Key required No Yes Yes Yes
Requests per minute 5 60 120 300
Requests per day 20 1,000 2,500 5,000
Maximum page size 50 500 500 500
Datasets
LGA boundaries No Yes Yes Yes
Wards No Yes Yes Yes
Health facilities No Yes Yes Yes
Population No Yes Yes Yes
Senatorial districts No Yes Yes Yes
Federal constituencies No Yes Yes Yes
Polling units No Yes Yes Yes
Exchange rates No Yes Yes Yes
Crypto prices No Yes Yes Yes
Geopolitical zones Yes Yes Yes Yes
States Yes Yes Yes Yes
Local government areas Yes Yes Yes Yes
Tertiary institutions Yes Yes Yes Yes
Banks Yes Yes Yes Yes
Phone prefixes Yes Yes Yes Yes
Public holidays Yes Yes Yes Yes
Countries Yes Yes Yes Yes
Airports Yes Yes Yes Yes
Fields
State and LGA centroids Withheld Included Included Included
Source and retrieval date Withheld Included Included Included
Institution website and founding year Withheld Included Included Included
Identifiers, names and codes Included Included Included Included
Formats
JSON Yes Yes Yes Yes
CSV No Yes Yes Yes
GeoJSON No Yes Yes Yes
Parquet No Yes Yes Yes
Changes
Change feed Yes Yes Yes Yes
Record history No Yes Yes Yes

Each response includes RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the limit you will hit first, per minute or per day, and RateLimit-Policy lists both, for example 5;w=60, 20;w=86400. Daily limits reset at 00:00 UTC. If you go over, you get a 429 with a Retry-After header.

Pagination

To get the next page, pass the next value you received as after. When a page has no next, you have everything.

Shell 
curl "https://trueset.timileyin.dev/v1/states/NG-LA/lgas?limit=50&after=lga_01M3MZBEBGEP51RX5HNM39J6Q5"

Each page picks up exactly where the last one stopped, so you won't get duplicates or gaps even if records change while you page through.

Formats

Pick a format with ?format= or an Accept header. JSON works without a key. CSV, GeoJSON and Parquet need one.

Shell 
curl -H "Authorization: Bearer ts_62e0f9c5_..." \
  "https://trueset.timileyin.dev/v1/health-facilities?format=csv" > facilities.csv

Errors

Errors come back as RFC 9457 problem documents. Use the code field in your error handling: it won't change between releases.

JSON 
{
  "type": "https://trueset.timileyin.dev/problems/upgrade_required",
  "title": "Forbidden",
  "status": 403,
  "code": "upgrade_required",
  "detail": "wards needs a paid plan. Subscribe at https://trueset.timileyin.dev/pricing",
  "instance": "/v1/wards"
}

Endpoints

Administrative

  • GET /lgas List local government areas Free
  • GET /lgas/{id} Get an LGA Free
  • GET /lgas/{id}/wards List the wards of an LGA Key
  • GET /states List states Free
  • GET /states/{id} Get a state Free
  • GET /states/{id}/lgas List the LGAs of a state Free
  • GET /wards List wards Key
  • GET /wards/{id} Get a ward Key
  • GET /zones List geopolitical zones Free

Electoral

  • GET /federal-constituencies List federal constituencies Key
  • GET /polling-units List polling units Key
  • GET /polling-units/{id} Get a polling unit Key
  • GET /senatorial-districts List senatorial districts Key

Finance

  • GET /banks List banks and bank codes Free
  • GET /banks/account-check Check an account number Free
  • GET /banks/{id} Get a bank Free
  • GET /crypto/prices List crypto prices Key
  • GET /crypto/prices/{symbol} Get one coin's price Key
  • GET /exchange-rates List exchange rates against the naira Key
  • GET /exchange-rates/convert Convert an amount between two currencies Key
  • GET /exchange-rates/{currency} List one currency's rate history Key

Platform

  • GET /changes Read the change feed Free
  • GET /locate Locate the area containing a point Key
  • GET /records/{id}/history Read every version of a record Key
  • GET /sources List the sources behind the data Free
  • GET /status Current platform status Free
  • GET /status/history Uptime history by day Free

Reference

  • GET /health-facilities List health facilities Key
  • GET /health-facilities/{id} Get a health facility Key
  • GET /institutions List tertiary institutions Free
  • GET /institutions/{id} Get an institution Free
  • GET /population List population figures Key

Utilities

  • GET /airports List airports Free
  • GET /airports/{id} Get an airport Free
  • GET /countries List countries with currencies and calling codes Free
  • GET /countries/{id} Get a country Free
  • GET /holidays List public holidays Free
  • GET /phone-prefixes List mobile number prefixes Free
  • GET /phone-prefixes/lookup Find the network for a phone number Free