API reference¶

Base URL: https://api.nationkit.site — every data endpoint needs X-API-Key (see Getting started). All responses are JSON. Country ISO codes are case-insensitive (alpha-2 or alpha-3).

Meta¶

GET /v1/meta

Platform info: platform, version, totalCountries, apiDocsUrl. No key required.

Countries¶

GET /v1/countries                    → Country[]
GET /v1/countries/{iso}              → Country          (404 → NotFoundError)
GET /v1/countries/{iso}/languages    → string[]

A Country carries isoAlpha2, isoAlpha3, isoNumeric, phoneCode, defaultLang, capitalLat/capitalLng, dataVersion, officialSource and the languages list the division names are available in.

curl -H "X-API-Key: nk_live_..." https://api.nationkit.site/v1/countries/dz

Divisions¶

GET /v1/countries/{iso}/divisions?level=&lang=&page=&perPage=   → Page<Division>
GET /v1/countries/{iso}/divisions/levels                        → DivisionLevel[]
GET /v1/countries/{iso}/divisions/{code}                        → Division
GET /v1/countries/{iso}/divisions/{code}/children               → Division[]

Algeria (DZ): level 1 = wilaya (69), level 2 = daïra (548), level 3 = commune (1,541)
Tunisia (TN): level 1 = governorate (24), level 2 = delegation (279)
A Division has code, level, levelKey, names (map of language → name), parentCode, lat/lng and childrenCount.

# All 69 wilayas of Algeria, one page
curl -H "X-API-Key: nk_live_..." \
  "https://api.nationkit.site/v1/countries/dz/divisions?level=1&perPage=2500"

# Children of wilaya 1 (Adrar): its 6 daïras
curl -H "X-API-Key: nk_live_..." \
  "https://api.nationkit.site/v1/countries/dz/divisions/1/children"

Pagination¶

List endpoints return Page<T>: items plus paging metadata taken from the response headers.

Header	Meaning
`X-Total-Count`	total rows across all pages
`X-Page`	current page (starts at 1)
`X-Per-Page`	rows per page

Limits: divisions default/max perPage = 2500 (a whole country fits one page); postal codes default 50, max 500. Omitted parameters are never sent as empty values.

Postal codes¶

GET /v1/countries/{iso}/postal-codes?divisionCode=&page=&perPage=  → Page<PostalCode>
GET /v1/countries/{iso}/postal-codes/{code}                        → PostalCode

A PostalCode has code (string — leading zeros preserved), optional divisionCode and optional officeName. Algeria ships 4,147 codes, Tunisia 971.

Search¶

GET /v1/countries/{iso}/search?q=   → SearchResult[]
GET /v1/search?q=                   → SearchResult[]   (all countries)

Multilingual, case-insensitive substring search (PostgreSQL pg_trgm) over division names in fr / ar / en. Results are ranked by matchScore (0..1), descending. An empty q is a 400.

curl -H "X-API-Key: nk_live_..." "https://api.nationkit.site/v1/search?q=Tunis"

[{ "countryIso": "TN", "code": 1122, "level": 2, "levelKey": "delegation",
   "names": { "ar": "تونس", "fr": "Tunis" },
   "parentCode": 11, "lat": 36.8188, "lng": 10.1658, "matchScore": 1.0 }]

Client accounts¶

POST /v1/clients/register   {name, email, password, companyName?}  → Registration (full key!)
POST /v1/clients/login      {email, password}                      → ClientAccount (key prefix only)

Both need no API key. register is the only time the full key is returned.

Operators (admin)¶

POST /v1/auth/login                     → JWT (SuperAdmin)
GET  /v1/operators                      → Operator[]        (JWT, SuperAdmin)
POST /v1/operators                      → Operator          (JWT, SuperAdmin)

Not for data clients — see the dashboard instead.