Easy, portable, self-hosting Japan postal code API

1.0.0 2013-04-18 10:36 UTC

This package is not auto-updated.

Last update: 2024-05-11 12:54:45 UTC


Easy, portable, self-hosting Japan postal code API

Live Example

Try the demo!


  • PHP5.3.3 or later
  • SQLite support (maybe installed on default PHP build)
  • Latest jQuery


  • Download
  • Extract archive
  • Upload zip.phar.php and zip.sqlite.db to same directory on your web server (eg.

If you prefer clean URLs, you'll need mod_rewrite and .htaccess files like this:

<IfModule mod_rewrite.c>
    RewriteEngine On
    #RewriteBase /path/to/app
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ zip.phar.php [L]

API Reference

General notes

  • Every string passed to and from the API needs to be UTF-8 encoded.
  • You can rename zip.phar.php to anything you like.

/version Get version


GET /zip.phar.php/version

Return value

An object with mime type 'application/json'

    "version": "1.0.0"

/api Get Javascript API


GET /zip.phar.php/api

Return value

The content of Javascript API with mime type 'text/javascript'

/search/{code}.{format} Find an address by zip-code


GET  /zip.phar.php/search/{code}
GET  /zip.phar.php/search/{code}.{format}
POST /zip.phar.php/search


  • code (string/integer) The code to search (9999999/999-9999)
  • format (string) The format (json|xml|php) Default:json

Return value

Format: json

An object with mime type 'application/json'

    "result": true,
    "data": {
        "id":   "38201",
        "code": "1600022",
        "pref": "\u6771\u4eac\u90fd",
        "city": "\u65b0\u5bbf\u533a",
        "town": "\u65b0\u5bbf"

Format: xml

A xml document with mime type 'application/xml'

<?xml version="1.0"?>
Format: php

A PHP serialized string with mime type 'text/plain'


JavaScript API

Configure and Paste the code above

<script src="//"></script>
<script src="/path/to/zip.phar.php/api" type="text/javascript"></script>

Call the API through jQuery

$.zipSearch('950-2014').done(function(json) {
    if (json.result) {
    } else {
        console.log('Address not found for code: ' +;

Update address database

Download full source code from repository

$ git clone zipapi
$ cd zipapi

Install dependencies via Composer

$ curl -sS | php
$ php composer.phar install

Download CSV (Lzh archive) from official website

Download lzh archive from

or just run

$ php app/console.php csv:download

Extract Lzh archive

If you have lha command, just type

$ cd ./csv
$ find . -type f -exec lha x {} \;

Setup database

$ php app/console.php doctrine:schema:update --force
$ php app/console.php csv:import ./csv

Rebuild phar archive

$ php app/console.php build:phar


Kazuyuki Hayashi (@kzykhys)


The MIT License