Kenya API

RESTFul API documenting all the information about country Kenya

Features

To be added: Get general information about Kenya,its people, government, institutions, health, culture, energy, finance, infrastructure, geographical sites, etc.
Get information about the 47 counties, including population, industries, area, tribes, postal codes, etc.

Built with

Node.js
Express.js

Home

To access the base URL, https://kenya-api.onrender.com/api/v1/

To access health endpoint, https://kenya-api.onrender.com/api/v1/health

API Routes

List of all the available kenya-api base routes.

/health
/info # info about country kenya!
/county
/wards
/postal_stations
/universities
/tribes
/hospitals
/banks

Getting Started

Installation

# install dependencies

$ yarn install

# serve with hot reload at localhost:3000

$ yarn run dev

Your application will be served on port 3000 by default, you can change that by modifying the .env file.

For a detailed explanation of how things work, check out Express.js.

REST API Documentation - County Data Endpoint

This REST API endpoint allows you to retrieve information about counties based on their county code.

Get County Data

Request

Method: GET
Endpoint: /county
Parameters:
- county_code: The unique numerical code of the county (required)

Response

Status Code: 200 (OK) - Successful request
Status Code: 400 (Bad Request) - County not found or invalid county_code

Successful Response

{
  "county": {
    "code": 1,
    "name": "Mombasa",
    "capital": "Mombasa (City)",
    "contact": "[email protected]",
    "website": "https://eservices.mombasa.go.ke/site/",
    "location": "Coastal Kenya",
    "border": ["Kilifi", "Kwale", "Indian Ocean"],
    "area": "219 km2",
    "Population": "939,370",
    "Mining": ["Chrome ore", "Cement", "Salt", "Sand"]
  },
  "status": 200
}

Not found error response

{
  "error": "County with the code {county_code} not found",
  "status": 400
}

Request

GET /county?county_code=1

Response

{
  "county": {
    "code": 1,
    "name": "Mombasa",
    "capital": "Mombasa (City)",
    "contact": "[email protected]",
    "website": "https://eservices.mombasa.go.ke/site/",
    "location": "Coastal Kenya",
    "border": ["Kilifi", "Kwale", "Indian Ocean"],
    "area": "219 km2",
    "Population": "939,370",
    "Mining": ["Chrome ore", "Cement", "Salt", "Sand"]
  },
  "status": 200
}

Request

GET /county?county_code=99

Respoonse

{
  "error": "County with the code 99 not found",
  "status": 400
}

Request

GET /county

Response

{
  "counties": [
    {
      "code": 1,
      "name": "Mombasa",
      "capital": "Mombasa (City)",
      "contact": "[email protected]",
      "website": "https://eservices.mombasa.go.ke/site/",
      "location": "Coastal Kenya",
      "border": ["Kilifi", "Kwale", "Indian Ocean"],
      "area": "219 km2",
      "Population": "939,370",
      "Mining": ["Chrome ore", "Cement", "Salt", "Sand"]
    }
    // Additional counties...
  ],
  "status": 200
}

REST API Documentation - Wards Data Endpoint

This REST API endpoint allows you to retrieve information about wards based on their ward code.

Get Wards Data

Request

Method: GET
Endpoint: /wards
Parameters:
- ward_code: The unique alphanumeric code of the ward (required)

Response

Status Code: 200 (OK) - Successful request
Status Code: 400 (Bad Request) - Ward not found or invalid ward_code

Examples

Request

GET /wards?ward_code=40101

Successful Response

{
  "ward": {
    "code": "40101",
    "office": "Ahero"
  },
  "status": 200
}

Error Response

{
  "error": "Ward with the code 40101 not found",
  "status": 400
}

Request

GET /wards?ward_code=99999

Error Response

{
  "error": "Ward with the code 99999 not found",
  "status": 400
}

Request

GET /wards

Response

{
  "wards": [
    {
      "code": "40101",
      "office": "Ahero"
    },
    {
      "code": "30101",
      "office": "Ainabkoi"
    },
    {
      "code": "40139",
      "office": "Akala"
    }
    // Additional wards...
  ],
  "status": 200
}

Postal Stations API Documentation

This API endpoint allows you to retrieve information about postal stations based on their postal code.

Get Postal Station Data

Request

Method: GET
Endpoint: /postal_stations
Parameters:
- post_code: The unique numerical postal code of the station (required)

Response

Status Code: 200 (OK) - Successful request
Status Code: 400 (Bad Request) - Postal station not found or invalid post_code
Status Code: 200 (OK) - Request without post_code, returns all postal stations

Successful Response

{
  "post": {
    "code": 12345,
    "name": "Sample Postal Station",
    "location": "Sample Location",
    "district": "Sample District"
  },
  "status": 200
}

Error Response

{
  "error": "Post station with the code {postal_code} not found",
  "status": 400
}

Examples

Request

GET /postal_stations?post_code=12345

Response

{
  "post": {
    "code": 12345,
    "name": "Sample Postal Station",
    "location": "Sample Location",
    "district": "Sample District"
  },
  "status": 200
}

Request

GET /postal_stations?post_code=99999

Response

{
  "error": "Post station with the code 99999 not found",
  "status": 400
}

Request

GET /postal_stations

Response

{
  "postal_stations": [
    {
      "code": 12345,
      "name": "Sample Postal Station 1",
      "location": "Sample Location 1",
      "district": "Sample District 1"
    },
    {
      "code": 67890,
      "name": "Sample Postal Station 2",
      "location": "Sample Location 2",
      "district": "Sample District 2"
    }
    // Additional postal stations...
  ],
  "status": 200
}

Banks API Documentation

This API endpoint allows you to retrieve information about banks in Kenya. You can query by bank type, bank name, USSD code, or Paybill number.

⚠️ Caution: The information provided by this API (including Paybill numbers, USSD codes, Telephone/Fax numbers, Email addresses, and Website URLs) is for reference only. Before engaging in any financial transactions, communications, or interactions with a bank, you must independently verify these details through official and trusted sources (such as the Central Bank’s registry, the bank’s official website, or verified customer support channels).

Do not send money, share personal details, or initiate transactions based solely on this API’s data.
Be aware that malicious actors can impersonate banks using fake numbers, emails, or domains.
Always confirm legitimacy before engage in making payments, signing agreements, or providing sensitive information.

This API is provided strictly for informational and educational purposes. The maintainers of this API assume no responsibility for financial loss, fraud, or damages resulting from misuse of the data.

Get Bank Data

Request

Method: GET
Endpoint: /banks
Query Parameters:
- bank_type: Filter banks by type (optional). Valid values:
  - commercial
  - mortgage-finance-institution
  - non-operating-holding-company
- bank_name: Filter by partial/full bank name (optional, case-insensitive).
- ussd: Filter by USSD code (optional, only applies to commercial banks).
- paybill: Filter by Paybill number (optional, only applies to banks that have one).

Response

200 (OK): Successful request, returns matching bank(s).
400 (Bad Request): Invalid bank type or malformed query.
404 (Not Found): No banks match the provided query.
200 (OK): Request without filters returns all banks.

Examples

Request

GET /banks?bank_name=commercial&ussd=247

Successful Response (Filtered by Bank Name)

{
  "data": [
    {
      "id": 15,
      "name": "Equity Bank Kenya Limited",
      "postalAddress": "P. O. Box 75104-00200, Nairobi",
      "telephone": "+254-20- +254 20 2262000/2262956 /2262828, 0763026000, 07633026956, 0763026828",
      "fax": "+254-020-2737276",
      "email": "[email protected]",
      "website": "www.equitybankgroup.com",
      "physicalAddress": "Equity Centre, 9th Floor, Hospital Road, Upper Hill, Nairobi.",
      "dateLicensed": "28th December 2004",
      "peerGroup": "Large",
      "branches": 178,
      "agencies": 0,
      "salesCentres": 0,
      "subBranches": 13,
      "xpressUnits": 0,
      "type": "commercial",
      "ussd": "*247#",
      "payBill": 247247
    },
    {
      "id": 2,
      "name": "Equity Group Holdings Limited",
      "licensedSubsidiary": "Equity Bank Kenya Ltd",
      "postalAddress": "P.O. Box 75104 – 00200, Nairobi",
      "telephone": "+254 763 3026000 Contact Centre: +254 763 063 000",
      "email": "[email protected]",
      "website": "www.equitygroupholdings.com",
      "physicalAddress": "Equity Centre, 9th Floor, Hospital Road, Upper Hill, Nairobi",
      "dateAuthorized": "31st December 2014",
      "type": "non-operating-holding-company"
    }
  ],
  "count": 2,
  "status": 200
}

Error Response (Invalid Bank Type)

{
  "error": "Invalid bank type",
  "status": 400
}

Error Response (No Matching Results)

{
  "error": "No bank(s) found matching the provided query",
  "query": {
    "bank_name": "nonexistent-bank"
  },
  "status": 404
}

Request Without Filters

GET /banks

Response

{
  "data": [
    {
      "id": 1,
      "name": "ABSA Bank Kenya PLC",
      "postalAddress": "P. O. Box 30120 – 00100, Nairobi",
      "telephone": "+254-20-4254000, 3900000",
      "email": "[email protected]",
      "website": "www.absabank.co.ke",
      "physicalAddress": "Absa Headquarters, Waiyaki Way, Westlands, Nairobi",
      "dateLicensed": "1916",
      "peerGroup": "Large",
      "branches": 85,
      "type": "commercial",
      "ussd": "*224#",
      "payBill": 111777
    },
    {
      "id": 2,
      "name": "Equity Bank Kenya Limited",
      "postalAddress": "P. O. Box 75104 – 00200, Nairobi",
      "telephone": "+254-763-063000",
      "email": "[email protected]",
      "website": "www.equitybankgroup.com",
      "physicalAddress": "Equity Centre, Upper Hill, Nairobi",
      "dateLicensed": "1984",
      "peerGroup": "Large",
      "branches": 190,
      "type": "commercial",
      "ussd": "*247#",
      "payBill": 247247
    }
    // ... additional banks
  ],
  "count": 42,
  "status": 200
}

Contributing

Contributions are always welcome! You can contribute to this project in various ways, including but not limited to:

Updating to correct information
Adding missing information
Writing and adding tests
Fixing bugs and issues
Improving documentation
Implementing new features

See contributing.md for more details on how to get started with contributing.

Please adhere to this project's code of conduct.

Authors

John Philip

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 201 Commits
.github		.github
.vscode		.vscode
src		src
tests/api_tests		tests/api_tests
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
README.md		README.md
SECURITY.md		SECURITY.md
contribution.md		contribution.md
eslint.config.mjs		eslint.config.mjs
example.env		example.env
nodemon.json		nodemon.json
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

dxphilo/kenya-api

Folders and files

Latest commit

History

Repository files navigation

Kenya API

Features

Built with

Home

API Routes

Getting Started

REST API Documentation - County Data Endpoint

Get County Data

Request

Response

Successful Response

Not found error response

Request

Response

Request

Respoonse

Request

Response

REST API Documentation - Wards Data Endpoint

Get Wards Data

Request

Response

Examples

Request

Successful Response

Error Response

Request

Error Response

Request

Response

Postal Stations API Documentation

Get Postal Station Data

Request

Response

Successful Response

Error Response

Examples

Request

Response

Request

Response

Request

Response

Banks API Documentation

Get Bank Data

Request

Response

Examples

Request

Successful Response (Filtered by Bank Name)

Error Response (Invalid Bank Type)

Error Response (No Matching Results)

Request Without Filters

Response

Contributing

Authors

License

About

Topics

Resources

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages