Stop Building Postal Code Lookups: This API Serves Japan's Data as Static JSON

You're building a form that needs a Japanese address autocomplete, or maybe you're localizing an app for the Japanese market. Either way, you've just realized you need to look up addresses by postal code, and the options aren't great—you could scrape data, maintain a database, or pay for a third-party service. What if you could just fetch a JSON file and be done with it? That's exactly what jp-postal-code-api offers: a free, open-source API that serves Japanese postal code data as static JSON via GitHub Pages.

What It Does

This project takes the official postal code data published by Japan Post and converts it into a simple, predictable REST API. Each endpoint follows the pattern https://jp-postal-code-api.ttskch.com/api/v1/{postal_code}.json, where you drop in a 7-digit postal code (hyphens optional) and get back structured address data.

The response includes Japanese addresses in both kanji (ja) and kana (kana) scripts, plus English translations (en). It also returns a prefecture code for each address. If a single postal code covers multiple municipalities—which happens more often than you'd think in Japan—the API returns an array of addresses in the addresses field.

Under the hood, it's built with modern PHP and inspired by an older project called madefor/postal-code-api that stopped being maintained. The data pipeline runs on GitHub Actions, which regenerates the JSON files daily from Japan Post's latest data. Because everything is served as static files on GitHub Pages, there's no server to maintain and no database to keep in sync.

Why It's Cool

The architecture here is genuinely clever, and it solves real problems you'd run into with other approaches.

• Static files mean high availability. There's no application server that can crash, no database connection pool to exhaust, no rate limiting to worry about. GitHub Pages serves these files from a CDN, which means the API is fast and resilient. For a lookup endpoint that might get hit from client-side JavaScript, that's a huge win.

• It's always fresh. The project runs a scheduled GitHub Action every day to pull the latest data from Japan Post and regenerate the JSON files. You don't have to do anything—the data stays current automatically. That's a nice touch for something like postal codes, which do change when municipalities merge or get renamed.

• You can fork it and own it. This is the killer feature for me. The README explicitly addresses the concern about GitHub Pages usage limits or repository longevity: just fork the repo and run your own instance. For client work where you need to guarantee uptime or keep data within a specific infrastructure, that's a level of control you won't get from a hosted API.

• The response format is thoughtful. Including ja, kana, and en in a single response means you can support multiple display languages without making additional API calls. The address4 field (which handles things like building names or street-level details) is there even when empty, so your parser doesn't need to handle missing keys.

• It handles edge cases gracefully. The example with postal code 6180000 shows a real-world scenario where one code spans two prefectures (Kyoto and Osaka). The API just returns both addresses in the array, and your code can decide which one applies based on context.

How to Try It

You can start using this right now without installing anything. Just hit the demo endpoint with any Japanese postal code:

curl https://jp-postal-code-api.ttskch.com/api/v1/1000014.json

That returns the address for Tokyo's Nagatacho district (where the National Diet Building is), with Japanese, kana, and English representations.

If you want to run your own instance—say, for a client project or to avoid depending on someone else's GitHub Pages—head over to the repository and fork it. The README is in Japanese, but the setup is straightforward: fork the repo, enable GitHub Pages, and the existing workflows should handle building and deploying the JSON files. You'll need to update the base URL in your code to point to your fork's Pages URL.

The project also maintains a live demo at https://jp-postal-code-api.ttskch.com if you want to poke around before committing to anything.

Final Thoughts

This is one of those projects that feels obvious in hindsight—why wouldn't you serve static lookup data as static files? It's not flashy, but it's practical and dependable. If you're working on anything that needs Japanese address lookup, whether it's a web form, a mobile app, or a backend service, this is worth a look. The daily data refresh and the fork-and-run flexibility make it a solid choice for both personal projects and client work. And honestly, it's nice to see a project that takes the "just use static files" approach to its logical conclusion.

Follow @githubprojects for more developer tools and open source projects.