Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dxphilo/kenya-api

⚡️RESTFul API documenting information about country Kenya ⚡️
https://github.com/dxphilo/kenya-api

kenya kenya-api kenya-communities kenya-constituencies kenya-counties kenya-divisions kenya-s-administrative-unit kenyan

Last synced: about 2 months ago
JSON representation

⚡️RESTFul API documenting information about country Kenya ⚡️

Host: GitHub
URL: https://github.com/dxphilo/kenya-api
Owner: dxphilo
Created: 2021-10-23T17:15:10.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-03-20T21:00:05.000Z (10 months ago)
Last Synced: 2024-04-23T18:35:50.138Z (8 months ago)
Topics: kenya, kenya-api, kenya-communities, kenya-constituencies, kenya-counties, kenya-divisions, kenya-s-administrative-unit, kenyan
Language: TypeScript
Homepage: https://kenya-api.onrender.com/health
Size: 670 KB
Stars: 9
Watchers: 2
Forks: 1
Open Issues: 6
Metadata Files:
- Readme: README.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

README

Kenya API

RESTFul API documenting all the information about country Kenya

![Blogsite website](https://cdn.britannica.com/15/15-050-B075588A/Flag-Kenya.jpg)

## 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](https://kenya-api.onrender.com/health)

### API Routes

List of all the available kenya-api base routes.

- `/health`
- `/country`
- `/county`
- `/wards`
- `/postal_stations`

## Getting Started

Installation

```bash

# install dependencies

$ yarn install

# serve with hot reload at localhost:3000

$ yarn run dev

```

Your application will be served on port [3000](http://localhost:3000/) by default, you can change that by modifying the .env file.

For a detailed explanation of how things work, check out [Express.js](https://expressjs.com/en/starter/hello-world.html).

### 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

```json
{
"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

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

```

#### Request

```bash
GET /county?county_code=1

```
#### Response

```
#### Request

```bash
GET /county?county_code=99

```
#### Respoonse

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

#### Request

```bash
GET /county
```

#### Response

```json
{
"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

```bash
GET /wards?ward_code=40101
```
#### Successful Response

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

#### Error Response

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

```

#### Request

```bash
GET /wards?ward_code=99999

```

#### Error Response

```json
{
"error": "Ward with the code 99999 not found",
"status": 400
}
```
#### Request

```bash
GET /wards

```

#### Response

```json
{
"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

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

#### Error Response

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

```
### Examples
#### Request

```bash

GET /postal_stations?post_code=12345
```
### Response

```json

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

```bash
GET /postal_stations?post_code=99999
```
#### Response

```json

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

```
#### Request

```bash
GET /postal_stations
```
#### Response

```json

{
"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
}

```

## 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](https://www.github.com/dxphilo)

## License

[MIT](https://choosealicense.com/licenses/mit/)