bendlikeabamboo/barangay-api repository overview

⁠🏃‍➡️ barangay-api

Barangay API - Simple FastAPI wrapper for barangay⁠ package.

⁠🗺️ Overview

This project is a FastAPI wrapper around the barangay package, providing a simple and efficient way to interact with the Philippine Standard Geographic Code (PSGC) data.

⁠🔦 Features

• Simple and easy to use API (OpenAPI Specification 3.1.0 - RestAPI).
• Performant barangay fuzzy-search function - can reach sub-20ms per match, minus network delays. That's roughly 1.1 million match/second!
• Access to historical PSGC data.
• FastAPI framework for high performance, auto-documentation, and validation.
• Docker-ready

⁠🌐 Live Deployment

Barangay API⁠ (no promises on reliability 😅)

⁠📦 Installation & Usage

⁠🐋 Easiest: Using Linux Docker Image

Use this when: you have docker and using linux (even WSL):

docker run -p 48573:48573 -d bendlikeabamboo/barangay-api

Try out the API in your local browser: http://localhost:48573/docs⁠

⁠🐳 Building Docker Image From Source

Use this when: you're on other platforms but have docker installed.

To get started, clone the repository.

git clone https://github.com/bendlikeabamboo/barangay-api
cd barangay-api

Build the image

docker build --tag 'barangay-api' .

Run the image

docker run -p 48573:48573 barangay-api

Try out the API in your local browser: http://localhost:48573/docs⁠

⁠🐍 Using Python From Source

Use this when: you don't have docker but have Python >3.13 installed or would like to develop & contribute.

To get started, clone the repository.

git clone https://github.com/bendlikeabamboo/barangay-api
cd barangay-api

Then install the package:

pip install .

Once successful, run using uvicorn:

uvicorn barangay_api.main:app --port 48573

Try out the API in your local browser: http://localhost:48573/docs⁠

⁠Code of Conduct

We are committed to fostering a welcoming and inclusive community. Please read our Code of Conduct⁠ before contributing.

⁠License

This project is licensed under the MIT License. See the LICENSE file for more details.