Let's begin with a simple example:
If we issue a query:
http://www.uniwits.com/modules/zipcode/queryxml?country=CN&zipcode=533021
The returned output, if no error found, is:
<?xml version="1.0" encoding="utf-8"?>
<zcinfolist><zc_country>CN</zc_country><zc_zipcode>533021</zc_zipcode><zc_prefecture>广西壮族自治区</zc_prefecture><zc_city>百色市</zc_city><zc_district>右江区</zc_district><zc_prefecture_read/><zc_city_read/><zc_district_read/></zcinfolist>
Format the output above, it can be viewed more clearly:
-<zcinfolist>
<zc_country>CN</zc_country>
<zc_zipcode>533021</zc_zipcode>
<zc_prefecture>广西壮族自治区</zc_prefecture>
<zc_city>百色市</zc_city>
<zc_district>右江区</zc_district>
<zc_prefecture_read/>
<zc_city_read/>
<zc_district_read/>
</zcinfolist>The query url above is simple, it has only two parameters. The country parameter is the ISO 2-byte country code that specifies which country the zipcode is of. Current only "country=CN" is supported. The zipcode parameter is the zipcode to query.
If a query is successful, the output is as the one above. Not all fields under the "zcinfolist" tag are always available.
| zc_country | The ISO 2-byte country code. |
| zc_zipcode | The zip code |
| zc_prefecture | The prefecture, or state name |
| zc_city | The city name |
| zc_district | The district name |
| zc_prefecture_read | Reading of the prefecture name |
| zc_city_read | Reading of the city name |
| zc_district_read | Reading of the district name |
If a zipcode is not found, an empty <zcinfolist/> will be returned.
If an error is detected, an "<error>" tag will be included with its content being the error message. Here is an example:
<?xml version="1.0" encoding="utf-8"?>
<zcinfolist><error>Exceed Query Limit: 50 queries/day.</error></zcinfolist>
50 queries per day per IP is a limitation. It is considered unreasonable for any single IP to query more than 50 times a day.
To use the service in productions, you can query from a web page using JavaScript (AJAX), and put at least one of the following HTML pieces in the invoking web page.
<a href="http://reserv.uniwits.com">Uniwits Online Reservation System</a>
<a href="http://www.uniwits.com">Uniwits System</a>
<a href="http://reserv.uniwits.com">Uniwits 在线预约系统</a>
<a href="http://www.uniwits.com">Uniwits 系统</a>
<a href="http://reserv.uniwits.com">Uniwits オンライン予約システム</a>
<a href="http://www.uniwits.com">Uniwits システム</a>
You can stylize these links to make them beautiful, but do not change these links. One of these links must appear within the first 8192 bytes of the caller web page.
Note: please make sure the links are accessable without user authentication.
Please use the following URL for test, it does not check query counts and links in contents of callers.
http://www.uniwits.com/modules/zipcode/testqueryxml?country=<country-code>&zipcode=<zipcode>
However, the test query only recognize the following zipcodes of China.
010072, 222006, 314007, 419409, 533021.
Totally NO warranty is available!
Please report to the following email support-module-zipcode*uniwits.com. When sending please replace the "*" with an at-mark "@".