Post-kun

Service Overview

Post-kun is a free API for searching postal code data across Japan. Since its launch in 2015, it has been used by many developers and companies and has processed hundreds of millions of API calls in total.

Many services that look up addresses from postal codes push you toward paid plans or require complicated authentication. Post-kun, on the other hand, is completely free and unlimited. There’s no need to obtain an API key, so you can start using it right away.

Thanks to Cloudflare CDN, it achieves fast responses of about 70 ms wherever in Japan the request comes from. You can implement smooth address autofill without compromising the user experience.

Postal code lookups are needed everywhere: e-commerce sites, business systems, smartphone apps, and more. Post-kun was created to meet those developer needs.

Why Is It Free?

Back in 2011, few rental servers offered large-capacity storage, which made exchanging data inconvenient. Teraren began by launching a 1 TB rental server service to solve that.

Later, as we expanded from digital space (rental servers) into physical space (real estate), we adopted our mission: “Make people’s experiences simpler and more comfortable through technology.”

The postal code API is part of that. We provide the infrastructure for free so developers can focus on building services that truly matter. That is our philosophy.

How to Use It

Basic Request

Just send a GET request with a 7-digit postal code.

// JavaScript (Fetch API)
const postcode = '1000001';

fetch(`https://postcode.teraren.com/postcodes/${postcode}.json`)
  .then(response => response.json())
  .then(data => {
    console.log(data);
    // {
    //   "postcode": "1000001",
    //   "prefecture": "東京都",
    //   "city": "千代田区",
    //   "town": "千代田"
    // }
  })
  .catch(error => console.error('Error:', error));

React Example

import { useState } from 'react';

function AddressForm() {
  const [postcode, setPostcode] = useState('');
  const [address, setAddress] = useState(null);

  const handleSearch = async () => {
    const response = await fetch(
      `https://postcode.teraren.com/postcodes/${postcode}.json`
    );
    const data = await response.json();
    setAddress(data);
  };

  return (
    <div>
      <input
        type="text"
        value={postcode}
        onChange={(e) => setPostcode(e.target.value)}
        placeholder="Postal code (7 digits)"
        maxLength="7"
      />
      <button onClick={handleSearch}>Search</button>

      {address && (
        <div>
          <p>Prefecture: {address.prefecture}</p>
          <p>City: {address.city}</p>
          <p>Town: {address.town}</p>
        </div>
      )}
    </div>
  );
}

Python Example

import requests

def search_postcode(postcode):
    url = f"https://postcode.teraren.com/postcodes/{postcode}.json"
    response = requests.get(url)

    if response.status_code == 200:
        data = response.json()
        print(f"Prefecture: {data['prefecture']}")
        print(f"City: {data['city']}")
        print(f"Town: {data['town']}")
    else:
        print("Postal code not found")

# Example usage
search_postcode("1000001")

Response Format

Success (200 OK):

{
  "postcode": "1000001",
  "prefecture": "東京都",
  "city": "千代田区",
  "town": "千代田"
}

Error (404 Not Found):

{
  "error": "Postcode not found"
}

Performance and Infrastructure

Post-kun is built on the following technology stack:

• Cloudflare Workers: Edge computing for fast access from anywhere in the world
• Cloudflare KV: A low-latency key-value store
• Rust: Fast and safe backend processing
• Official Japan Post data: A highly reliable data source

By leveraging Cloudflare’s edge network, it achieves response times of about 70 ms from anywhere in Japan. That is three to five times faster than typical server-based APIs.

Data Reliability

The postal code data comes from the official data published by Japan Post. The monthly updates are imported automatically, so the data is always up to date.

New or changed postal codes are usually reflected within one to two weeks.

Troubleshooting

A postal code can’t be found

• Search with the 7-digit number without the hyphen (e.g., 100-0001 → 1000001)
• Very recent postal codes may take some time to be reflected
• Some postal codes dedicated to specific businesses may not be supported

Responses are slow

• Warming up the CDN cache can take some time
• Responses are normally around 70 ms, but the first request may take about 200 ms

I’m getting CORS errors

• Post-kun supports CORS, so you can call the API directly from the browser
• If errors persist, set up a proxy on the server side

Comparison with Competing Services

Roadmap

• Reverse lookup of postal codes from addresses
• Latitude and longitude data
• GraphQL support
• More detailed town-level information

We look forward to your feedback. If you’d like to request a feature, please feel free to contact us.