{"id":19874732,"url":"https://github.com/dxphilo/kenya-api","last_synced_at":"2025-10-20T09:16:59.873Z","repository":{"id":37791126,"uuid":"420475829","full_name":"dxphilo/kenya-api","owner":"dxphilo","description":"⚡️RESTFul API documenting information about country Kenya ⚡️","archived":false,"fork":false,"pushed_at":"2025-04-28T22:39:08.000Z","size":596,"stargazers_count":16,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-28T23:41:52.341Z","etag":null,"topics":["kenya","kenya-api","kenya-communities","kenya-constituencies","kenya-counties","kenya-divisions","kenya-s-administrative-unit","kenyan"],"latest_commit_sha":null,"homepage":"https://kenya-api.onrender.com/api/v1/health","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dxphilo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-23T17:15:10.000Z","updated_at":"2025-04-28T22:39:04.000Z","dependencies_parsed_at":"2023-02-13T03:01:04.255Z","dependency_job_id":"78c2b3f6-9ac4-4df4-bfad-a27e85f004f9","html_url":"https://github.com/dxphilo/kenya-api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxphilo%2Fkenya-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxphilo%2Fkenya-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxphilo%2Fkenya-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dxphilo%2Fkenya-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dxphilo","download_url":"https://codeload.github.com/dxphilo/kenya-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252023283,"owners_count":21682156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kenya","kenya-api","kenya-communities","kenya-constituencies","kenya-counties","kenya-divisions","kenya-s-administrative-unit","kenyan"],"created_at":"2024-11-12T16:25:12.490Z","updated_at":"2025-10-20T09:16:59.868Z","avatar_url":"https://github.com/dxphilo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003eKenya API\u003c/h1\u003e\n\nRESTFul API documenting all the information about country Kenya\n\n\u003c/div\u003e\n\n![Blogsite website](https://cdn.britannica.com/15/15-050-B075588A/Flag-Kenya.jpg)\n\n## Features\n\n- To be added: Get general information about Kenya,its people, government, institutions, health, culture, energy, finance, infrastructure, geographical sites, etc.\n\n- Get information about the 47 counties, including population, industries, area, tribes, postal codes, etc.\n\n#### Built with\n\n- Node.js\n- Express.js\n\n### Home\n\nTo access the base URL, [https://kenya-api.onrender.com/api/v1/](https://kenya-api.onrender.com/api/v1/)\n\nTo access health endpoint, [https://kenya-api.onrender.com/api/v1/health](https://kenya-api.onrender.com/api/v1/health)\n\n### API Routes\n\nList of all the available kenya-api base routes.\n\n- `/health`\n- `/info` # info about country kenya!\n- `/county`\n- `/wards`\n- `/postal_stations`\n- `/universities`\n- `/tribes`\n- `/hospitals`\n- `/banks`\n\n## Getting Started\n\nInstallation\n\n```bash\n\n# install dependencies\n\n$ yarn install\n\n# serve with hot reload at localhost:3000\n\n$ yarn run dev\n\n```\n\nYour application will be served on port [3000](http://localhost:3000/) by default, you can change that by modifying the .env file.\n\nFor a detailed explanation of how things work, check out [Express.js](https://expressjs.com/en/starter/hello-world.html).\n\n### REST API Documentation - County Data Endpoint\n\nThis REST API endpoint allows you to retrieve information about counties based on their county code.\n\n### Get County Data\n\n#### Request\n\n- Method: GET\n- Endpoint: `/county`\n- Parameters:\n  - `county_code`: The unique numerical code of the county (required)\n\n### Response\n\n- Status Code: 200 (OK) - Successful request\n- Status Code: 400 (Bad Request) - County not found or invalid `county_code`\n\n#### Successful Response\n\n```json\n{\n  \"county\": {\n    \"code\": 1,\n    \"name\": \"Mombasa\",\n    \"capital\": \"Mombasa (City)\",\n    \"contact\": \"esupport@mombasa.go.ke\",\n    \"website\": \"https://eservices.mombasa.go.ke/site/\",\n    \"location\": \"Coastal Kenya\",\n    \"border\": [\"Kilifi\", \"Kwale\", \"Indian Ocean\"],\n    \"area\": \"219 km2\",\n    \"Population\": \"939,370\",\n    \"Mining\": [\"Chrome ore\", \"Cement\", \"Salt\", \"Sand\"]\n  },\n  \"status\": 200\n}\n```\n\n#### Not found error response\n\n```json\n{\n  \"error\": \"County with the code {county_code} not found\",\n  \"status\": 400\n}\n```\n\n#### Request\n\n```bash\nGET /county?county_code=1\n\n```\n\n#### Response\n\n```json\n{\n  \"county\": {\n    \"code\": 1,\n    \"name\": \"Mombasa\",\n    \"capital\": \"Mombasa (City)\",\n    \"contact\": \"esupport@mombasa.go.ke\",\n    \"website\": \"https://eservices.mombasa.go.ke/site/\",\n    \"location\": \"Coastal Kenya\",\n    \"border\": [\"Kilifi\", \"Kwale\", \"Indian Ocean\"],\n    \"area\": \"219 km2\",\n    \"Population\": \"939,370\",\n    \"Mining\": [\"Chrome ore\", \"Cement\", \"Salt\", \"Sand\"]\n  },\n  \"status\": 200\n}\n```\n\n#### Request\n\n```bash\nGET /county?county_code=99\n\n```\n\n#### Respoonse\n\n```json\n{\n  \"error\": \"County with the code 99 not found\",\n  \"status\": 400\n}\n```\n\n#### Request\n\n```bash\nGET /county\n```\n\n#### Response\n\n```json\n{\n  \"counties\": [\n    {\n      \"code\": 1,\n      \"name\": \"Mombasa\",\n      \"capital\": \"Mombasa (City)\",\n      \"contact\": \"esupport@mombasa.go.ke\",\n      \"website\": \"https://eservices.mombasa.go.ke/site/\",\n      \"location\": \"Coastal Kenya\",\n      \"border\": [\"Kilifi\", \"Kwale\", \"Indian Ocean\"],\n      \"area\": \"219 km2\",\n      \"Population\": \"939,370\",\n      \"Mining\": [\"Chrome ore\", \"Cement\", \"Salt\", \"Sand\"]\n    }\n    // Additional counties...\n  ],\n  \"status\": 200\n}\n```\n\n### REST API Documentation - Wards Data Endpoint\n\nThis REST API endpoint allows you to retrieve information about wards based on their ward code.\n\n### Get Wards Data\n\n#### Request\n\n- Method: GET\n- Endpoint: `/wards`\n- Parameters:\n  - `ward_code`: The unique alphanumeric code of the ward (required)\n\n#### Response\n\n- Status Code: 200 (OK) - Successful request\n- Status Code: 400 (Bad Request) - Ward not found or invalid `ward_code`\n\n### Examples\n\n#### Request\n\n```bash\nGET /wards?ward_code=40101\n```\n\n#### Successful Response\n\n```json\n{\n  \"ward\": {\n    \"code\": \"40101\",\n    \"office\": \"Ahero\"\n  },\n  \"status\": 200\n}\n```\n\n#### Error Response\n\n```json\n{\n  \"error\": \"Ward with the code 40101 not found\",\n  \"status\": 400\n}\n```\n\n#### Request\n\n```bash\nGET /wards?ward_code=99999\n\n```\n\n#### Error Response\n\n```json\n{\n  \"error\": \"Ward with the code 99999 not found\",\n  \"status\": 400\n}\n```\n\n#### Request\n\n```bash\nGET /wards\n\n```\n\n#### Response\n\n```json\n{\n  \"wards\": [\n    {\n      \"code\": \"40101\",\n      \"office\": \"Ahero\"\n    },\n    {\n      \"code\": \"30101\",\n      \"office\": \"Ainabkoi\"\n    },\n    {\n      \"code\": \"40139\",\n      \"office\": \"Akala\"\n    }\n    // Additional wards...\n  ],\n  \"status\": 200\n}\n```\n\n# Postal Stations API Documentation\n\nThis API endpoint allows you to retrieve information about postal stations based on their postal code.\n\n## Get Postal Station Data\n\n### Request\n\n- Method: GET\n- Endpoint: `/postal_stations`\n- Parameters:\n  - `post_code`: The unique numerical postal code of the station (required)\n\n### Response\n\n- Status Code: 200 (OK) - Successful request\n- Status Code: 400 (Bad Request) - Postal station not found or invalid `post_code`\n- Status Code: 200 (OK) - Request without `post_code`, returns all postal stations\n\n#### Successful Response\n\n```json\n{\n  \"post\": {\n    \"code\": 12345,\n    \"name\": \"Sample Postal Station\",\n    \"location\": \"Sample Location\",\n    \"district\": \"Sample District\"\n  },\n  \"status\": 200\n}\n```\n\n#### Error Response\n\n```json\n{\n  \"error\": \"Post station with the code {postal_code} not found\",\n  \"status\": 400\n}\n```\n\n### Examples\n\n#### Request\n\n```bash\n\nGET /postal_stations?post_code=12345\n```\n\n### Response\n\n```json\n{\n  \"post\": {\n    \"code\": 12345,\n    \"name\": \"Sample Postal Station\",\n    \"location\": \"Sample Location\",\n    \"district\": \"Sample District\"\n  },\n  \"status\": 200\n}\n```\n\n#### Request\n\n```bash\nGET /postal_stations?post_code=99999\n```\n\n#### Response\n\n```json\n{\n  \"error\": \"Post station with the code 99999 not found\",\n  \"status\": 400\n}\n```\n\n#### Request\n\n```bash\nGET /postal_stations\n```\n\n#### Response\n\n```json\n{\n  \"postal_stations\": [\n    {\n      \"code\": 12345,\n      \"name\": \"Sample Postal Station 1\",\n      \"location\": \"Sample Location 1\",\n      \"district\": \"Sample District 1\"\n    },\n    {\n      \"code\": 67890,\n      \"name\": \"Sample Postal Station 2\",\n      \"location\": \"Sample Location 2\",\n      \"district\": \"Sample District 2\"\n    }\n    // Additional postal stations...\n  ],\n  \"status\": 200\n}\n```\n\n---\n\n# Banks API Documentation\n\nThis API endpoint allows you to retrieve information about banks in Kenya. You can query by bank type, bank name, USSD code, or Paybill number.\n\n---\n\n⚠️ **Caution**:\nThe information provided by this API (including **Paybill numbers**, **USSD codes**, **Telephone/Fax numbers**, **Email addresses**, and **Website URLs**) is for **reference only**.\nBefore 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).\n\n- Do **not** send money, share personal details, or initiate transactions based solely on this API’s data.\n- Be aware that malicious actors can impersonate banks using fake numbers, emails, or domains.\n- Always confirm legitimacy before engage in making payments, signing agreements, or providing sensitive information.\n\nThis 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.\n\n---\n\n## Get Bank Data\n\n### Request\n\n- **Method:** `GET`\n- **Endpoint:** `/banks`\n- **Query Parameters:**\n\n  - `bank_type`: Filter banks by type (optional). Valid values:\n\n    - `commercial`\n    - `mortgage-finance-institution`\n    - `non-operating-holding-company`\n\n  - `bank_name`: Filter by partial/full bank name (optional, case-insensitive).\n  - `ussd`: Filter by USSD code (optional, only applies to commercial banks).\n  - `paybill`: Filter by Paybill number (optional, only applies to banks that have one).\n\n---\n\n## Response\n\n- **200 (OK):** Successful request, returns matching bank(s).\n- **400 (Bad Request):** Invalid bank type or malformed query.\n- **404 (Not Found):** No banks match the provided query.\n- **200 (OK):** Request without filters returns all banks.\n\n---\n\n### Examples\n\n#### Request\n\n```bash\n\nGET /banks?bank_name=commercial\u0026ussd=247\n```\n\n### Successful Response (Filtered by Bank Name)\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": 15,\n      \"name\": \"Equity Bank Kenya Limited\",\n      \"postalAddress\": \"P. O. Box 75104-00200, Nairobi\",\n      \"telephone\": \"+254-20- +254 20 2262000/2262956 /2262828, 0763026000, 07633026956, 0763026828\",\n      \"fax\": \"+254-020-2737276\",\n      \"email\": \"info@equitybank.co.ke\",\n      \"website\": \"www.equitybankgroup.com\",\n      \"physicalAddress\": \"Equity Centre, 9th Floor, Hospital Road, Upper Hill, Nairobi.\",\n      \"dateLicensed\": \"28th December 2004\",\n      \"peerGroup\": \"Large\",\n      \"branches\": 178,\n      \"agencies\": 0,\n      \"salesCentres\": 0,\n      \"subBranches\": 13,\n      \"xpressUnits\": 0,\n      \"type\": \"commercial\",\n      \"ussd\": \"*247#\",\n      \"payBill\": 247247\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Equity Group Holdings Limited\",\n      \"licensedSubsidiary\": \"Equity Bank Kenya Ltd\",\n      \"postalAddress\": \"P.O. Box 75104 – 00200, Nairobi\",\n      \"telephone\": \"+254 763 3026000 Contact Centre: +254 763 063 000\",\n      \"email\": \"info@equitygroupholdings.com\",\n      \"website\": \"www.equitygroupholdings.com\",\n      \"physicalAddress\": \"Equity Centre, 9th Floor, Hospital Road, Upper Hill, Nairobi\",\n      \"dateAuthorized\": \"31st December 2014\",\n      \"type\": \"non-operating-holding-company\"\n    }\n  ],\n  \"count\": 2,\n  \"status\": 200\n}\n```\n\n---\n\n### Error Response (Invalid Bank Type)\n\n```json\n{\n  \"error\": \"Invalid bank type\",\n  \"status\": 400\n}\n```\n\n---\n\n### Error Response (No Matching Results)\n\n```json\n{\n  \"error\": \"No bank(s) found matching the provided query\",\n  \"query\": {\n    \"bank_name\": \"nonexistent-bank\"\n  },\n  \"status\": 404\n}\n```\n\n---\n\n### Request Without Filters\n\n```bash\nGET /banks\n```\n\n#### Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": 1,\n      \"name\": \"ABSA Bank Kenya PLC\",\n      \"postalAddress\": \"P. O. Box 30120 – 00100, Nairobi\",\n      \"telephone\": \"+254-20-4254000, 3900000\",\n      \"email\": \"absa.kenya@absa.africa\",\n      \"website\": \"www.absabank.co.ke\",\n      \"physicalAddress\": \"Absa Headquarters, Waiyaki Way, Westlands, Nairobi\",\n      \"dateLicensed\": \"1916\",\n      \"peerGroup\": \"Large\",\n      \"branches\": 85,\n      \"type\": \"commercial\",\n      \"ussd\": \"*224#\",\n      \"payBill\": 111777\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Equity Bank Kenya Limited\",\n      \"postalAddress\": \"P. O. Box 75104 – 00200, Nairobi\",\n      \"telephone\": \"+254-763-063000\",\n      \"email\": \"info@equitybank.co.ke\",\n      \"website\": \"www.equitybankgroup.com\",\n      \"physicalAddress\": \"Equity Centre, Upper Hill, Nairobi\",\n      \"dateLicensed\": \"1984\",\n      \"peerGroup\": \"Large\",\n      \"branches\": 190,\n      \"type\": \"commercial\",\n      \"ussd\": \"*247#\",\n      \"payBill\": 247247\n    }\n    // ... additional banks\n  ],\n  \"count\": 42,\n  \"status\": 200\n}\n```\n\n## Contributing\n\nContributions are always welcome! You can contribute to this project in various ways, including but not limited to:\n\n- Updating to correct information\n- Adding missing information\n- Writing and adding tests\n- Fixing bugs and issues\n- Improving documentation\n- Implementing new features\n\nSee `contributing.md` for more details on how to get started with contributing.\n\nPlease adhere to this project's `code of conduct`.\n\n#### Authors\n\n- [John Philip](https://www.github.com/dxphilo)\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxphilo%2Fkenya-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdxphilo%2Fkenya-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdxphilo%2Fkenya-api/lists"}