bensin-api

bensin-api is a free public API that provides fuel price data from Pertamina, Indonesia's state-owned oil company. The data is served as static JSON files hosted on GitHub Pages, organized by province, and updated automatically every hour via a scheduled GitHub Actions workflow.

The project exists because the official Pertamina API returns messy, inconsistent data. Prices come back as strings in some places and integers in others, product names are inconsistent, and the same timestamp is repeated redundantly on every item in the response. bensin-api fetches that raw data, cleans it, and republishes it in a normalized format where prices are plain integers, unavailable products are marked clearly, and redundant fields are removed. The cleaned files are roughly 43 percent smaller than the originals.

There are three main endpoints. The per-province endpoint returns fuel products and prices for a single province, identified by a URL slug such as "dki-jakarta" or "aceh". The national index endpoint lists all provinces with their file sizes, product counts, and path references, which is useful for building navigation in an app without downloading all prices at once. The full national endpoint returns all provinces and their products in one request, suited for seeding a local database or building a price comparison dashboard.

The update workflow runs on a cron schedule. GitHub Actions fetches fresh data from Pertamina, normalizes it with a Python script, validates the structure, and opens a pull request to a staging branch rather than pushing directly to main. This avoids merge conflicts and keeps the update history auditable.

For developers who want to run the project locally, the README includes setup instructions for a Python virtual environment, dependency installation, running the data generator with or without a live fetch from Pertamina, and running the test suite.