Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/sooluh/kodepos

:postbox: Indonesian postal code search API by place name, village or city/regency.
https://github.com/sooluh/kodepos

api fastify indonesia javascript kode-pos kodepos nodejs postal-code typescript vercel

Last synced: 14 days ago
JSON representation

:postbox: Indonesian postal code search API by place name, village or city/regency.

Host: GitHub
URL: https://github.com/sooluh/kodepos
Owner: sooluh
License: apache-2.0
Created: 2020-09-10T03:25:02.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2024-09-18T16:21:25.000Z (about 2 months ago)
Last Synced: 2024-10-16T22:35:30.609Z (28 days ago)
Topics: api, fastify, indonesia, javascript, kode-pos, kodepos, nodejs, postal-code, typescript, vercel
Language: TypeScript
Homepage: https://kodepos.vercel.app
Size: 2.8 MB
Stars: 100
Watchers: 3
Forks: 28
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        

![@sooluh/kodepos](https://socialify.git.ci/sooluh/kodepos/image?description=1&descriptionEditable=Indonesian%20postal%20code%20search%20API%20by%20place%20name%2C%20village%20or%20city%2Fregency.&font=Jost&forks=1&issues=1&logo=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fmicrosoft%2Ffluentui-emoji%40main%2Fassets%2FPostbox%2FColor%2Fpostbox_color.svg&name=1&owner=1&pattern=Charlie%20Brown&pulls=1&stargazers=1&theme=Auto)

## Requirements

- Node.js `>= 20.x`

- npm

## Getting Started

1. Clone this repository

   ```bash

   git clone https://github.com/sooluh/kodepos.git

   ```

2. Move to the repository directory

   ```bash

   cd kodepos

   ```

3. Install dependencies

   ```bash

   npm ci

   ```

4. Run locally

   - Development mode

     ```bash

     npm run dev

     ```

   - Production mode

     1. Build first

        ```bash

        npm run build

        ```

     2. Start the app

        ```bash

        npm run start

        ```

### One-click Deployment

The fastest way to use it privately on PaaS available



  





  





  



### Open in



  

    

    

    

  





  





  



## Endpoints

### Search by Place Name

```

[ENDPOINT] /search

```


[GET] http://localhost:3000/search/?q=danasari



#### Query strings

| Params | Description     | Required |

| ------ | --------------- | :------: |

| q      | Search keywords |    ✅     |

#### Response

```json

{

  "statusCode": 200,

  "code": "OK",

  "data": [

    {

      "code": 46386,

      "village": "Danasari",

      "district": "Cisaga",

      "regency": "Ciamis",

      "province": "Jawa Barat",

      "latitude": -7.3271342,

      "longitude": 108.4577572,

      "elevation": 110,

      "timezone": "WIB"

    },

    {

      "code": 53357,

      "village": "Danasari",

      "district": "Karangjambu",

      "regency": "Purbalingga",

      "province": "Jawa Tengah",

      "latitude": -7.1857161,

      "longitude": 109.4368274,

      "elevation": 705,

      "timezone": "WIB"

    },

    {

      "code": 52314,

      "village": "Danasari",

      "district": "Pemalang",

      "regency": "Pemalang",

      "province": "Jawa Tengah",

      "latitude": -6.8649882,

      "longitude": 109.3956117,

      "elevation": 6,

      "timezone": "WIB"

    },

    {

      "code": 52465,

      "village": "Danasari",

      "district": "Bojong",

      "regency": "Tegal",

      "province": "Jawa Tengah",

      "latitude": -7.1153626,

      "longitude": 109.1850778,

      "elevation": 737,

      "timezone": "WIB"

    }

  ]

}

```

### Search by Coordinates

```

[ENDPOINT] /detect

```


[GET] http://localhost:3000/detect/?latitude=-6.547052&longitude=107.3980201



#### Query strings

| Params    | Description        | Required |

| --------- | ------------------ | :------: |

| latitude  | Location latitude  |    ✅     |

| longitude | Location longitude |    ✅     |

#### Response

```json

{

  "statusCode": 200,

  "code": "OK",

  "data": {

    "code": 41152,

    "village": "Kembangkuning",

    "district": "Jatiluhur",

    "regency": "Purwakarta",

    "province": "Jawa Barat",

    "latitude": -6.5495591,

    "longitude": 107.4121855,

    "elevation": 112,

    "timezone": "WIB",

    "distance": 1.5894826841413479

  }

}

```

### Showcase

List of awesome projects powered by this API

- [**kodepos-web**](https://github.com/dotslashf/kodepos-web)


  Simple web-app for postcode search by [dotslashf](https://github.com/dotslashf)

- [**Kode POS**](https://github.com/AzharRivaldi/Kode-POS-Indonesia)


  Indonesia postal code search application (kotlin) by [AzharRivaldi](https://github.com/AzharRivaldi)

### Ready to use!

List of server APIs ready to use publicly

> [!IMPORTANT]

> For production usage, we recommend deploying it on your own and not using the list below. The list below can be used for development or learning purposes only!

- [https://kodepos.vercel.app](https://kodepos.vercel.app/search/?q=danasari) `latest`

- [https://kodepos.onrender.com](https://kodepos.onrender.com/search/?q=danasari) `latest`

### License

This project is licensed under [Apache 2.0 License](https://github.com/sooluh/kodepos/blob/main/LICENSE).