kzykhys / portable-zipcode-api
Easy, portable, self-hosting Japan postal code API
1.0.0
2013-04-18 10:36 UTC
Requires
- php: >=5.3.3
- doctrine/dbal: >=2.2.0,<2.4.0-dev
- doctrine/orm: >=2.2.0,<2.4.0-dev
- kzykhys/php-csv-parser: dev-master
- silex/silex: 1.0.*@dev
- symfony/console: >=2.1,<2.3-dev
- symfony/finder: >=2.1,<2.3-dev
- symfony/serializer: >=2.1,<2.3-dev
This package is not auto-updated.
Last update: 2024-10-26 15:03:26 UTC
README
Easy, portable, self-hosting Japan postal code API
Live Example
Requirements
- PHP5.3.3 or later
- SQLite support (maybe installed on default PHP build)
- Latest jQuery
Installation
- Download portable-zip-api.zip
- Extract archive
- Upload zip.phar.php and zip.sqlite.db to same directory on your web server (eg.
http://www.example.com/API/zip.phar.php
)
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]
</IfModule>
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
URL
GET /zip.phar.php/version
Return value
An object with mime type 'application/json'
{ "version": "1.0.0" }
/api
Get Javascript API
URL
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
URL
GET /zip.phar.php/search/{code}
GET /zip.phar.php/search/{code}.{format}
POST /zip.phar.php/search
Arguments
- 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"?> <response> <result>1</result> <data> <id>38201</id> <code>1600022</code> <pref>東京都</pref> <city>新宿区</city> <town>新宿</town> </data> </response>
Format: php
A PHP serialized string with mime type 'text/plain'
a:2:{s:6:"result";b:1;s:4:"data";a:5:{s:4:"city";s:9:"新宿区";s:4:"code";s:7:"1600022";s:2:"id";s:5:"38201";s:4:"pref";s:9:"東京都";s:4:"town";s:6:"新宿";}}
JavaScript API
Configure and Paste the code above
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></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) { console.log(json.data.pref); console.log(json.data.city); console.log(json.data.town); } else { console.log('Address not found for code: ' + json.data.code); } });
Update address database
Download full source code from repository
$ git clone https://github.com/kzykhys/portable-zipcode-api.git zipapi
$ cd zipapi
Install dependencies via Composer
$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar install
Download CSV (Lzh archive) from official website
Download lzh archive from http://www.post.japanpost.jp/zipcode/dl/kogaki.html
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
Author
Kazuyuki Hayashi (@kzykhys)
LICENSE
The MIT License