Japan Postal Code

This module provides a Japan postal code data and API for them. This fetches the csv file from the Japan post office website and insert it into the local database. After getting the data, it doesn't depend on any external service.

This fetch process from Japan post office website may fail with a timeout error because it takes a long time (it may be over 1 minute depending on the environment).

This module is only for developers. It provides only APIs and doesn't provide any UI.

Similar projects

• Addressfield - Japanese Postal Code - This module uses an external service "ajaxzip3" and provides an end-user functionality with Address Field module.

Installation

1. Enable this module.
2. Go to the admin page admin/config/services/japan-postal-code and click the button in the page to fetch Japan postal code data from Japan post office website. This process takes a long time because it has large amount of data (over 100,000). Actually the file size is not so large but inserting them into the database table takes a long time.
3. Then, you can start to use the Japan postal code data with API. For detail on the API, please see below. Please don't forget to give a permission "Use Japan postal code service" (machine name "use japan postal code service") to service consumer user roles.

Usage

This module provides 3 ways to use postal code data stored in local Database table.

1. Functions
2. Request handlers
3. JavaScript utility functions

1.

There are 2 functions as API: japan_postal_code_get_address_by_postal_code() and japan_postal_code_get_addresses_by_postal_code(). These are for backend developers. Both of them takes a 7-digit postal code in Japan (it may contain - like 100-0001) and returns an address/addresses related with the postal code. The difference is that japan_postal_code_get_address_by_postal_code() returns only one address and japan_postal_code_get_addresses_by_postal_code() returns multiple addresses.

The returned address is a stdClass object with 5 members: postal_code, prefecture, city, address_under_city and name. For example, japan_postal_code_get_address_by_postal_code('1000001') returns the following object loaded from the database table.

    object(
      "postal_code": "1000001",
      "prefecture": "東京都",
      "city": "千代田区",
      "address_under_city": "千代田",
      "name": "",
    )

In the above example, the name is empty. name is used only for special addresses. In Japan, limited organizations have unique postal code and name represents the name of organization. If an invalid postal code is passed, the returned value is FALSE.

2.

Request handlers are set for paths: japan-postal-code/address/% and japan-postal-code/addresses/%. This is for front-end developers. This page takes a postal code in the path and returns a json output containing an address/addresses data which match the postal code. It check the permission "Use Japan postal code service" (machine name: use japan postal code service) for access. So make sure that a user has that permission before testing it.

For example, if one who has the above permission visits the page with path japan-postal-code/address/1000001, Drupal returns a json output like:

    {
      "status": true, 
      "data": {
        "postal_code": "1000001",
        "prefecture": "東京都",
        "city": "千代田区",
        "address_under_city": "千代田"
      }
    }

In the above example, status is the result status for the request. If the status is true, it means the matched address is found. On the other hand, false status represents the postal code is invalid or no matched address is found. The value of the member data is same as the returned value of the function japan_postal_code_get_address_by_postal_code().

japan-postal-code/address/% uses japan_postal_code_get_address_by_postal_code() to return single address. On the other hand, japan-postal-code/addresses/% uses japan_postal_code_get_addresses_by_postal_code() to return multiple addresses.

3.

There are also JavaScript utility functions: Drupal.japan_postal_code.fetchOne() and Drupal.japan_postal_code.fetchAll(). These are simple wrappers around $.getJSON(). You can use these function as following:

Drupal.japan_postal_code.fetchOne('1000001', function (data) {
  if (data.status) {
    // data.data is an object.
    console.log(data.data.prefecture);  // => '東京都'
  }
});

Drupal.japan_postal_code.fetchAll('1000001', function (data) {
  if (data.status) {
    // data.data is an array of objects.
    console.log(data.data[0].prefecture);  // => '東京都'
  }
});

These JavaScript functions are not loaded automatically for performance reason. When using them, please don't forget to include the JavaScript file in the module directory. As you know, there are 2 ways to add JavaScript file to page dynamically: drupal_add_js() and #js in render array. If you prefer drupal_add_js(), drupal_add_js(drupal_get_path('module', 'japan_postal_code') .'/js/japan_postal_code.js', 'file'); is the line you should insert into a page callback.

Test

You can see this functionality easily by creating a node with body full_html format and pasting the following code in the body:

    <form id="myform" action="">
      <input type="text" name="postalcode" id="myform-postalcode" placeholder="postal code">
      <button type="button" id="myform-autocomplete">autocomplete</button>
      <input type="text" name="address" id="myform-address" placeholder="address">
    </form>

    <script>
    $ = jQuery;
    $('#myform-autocomplete').click(function(){
      var postalcode = $('#myform-postalcode').val();
      $.getJSON('/japan-postal-code/address/' + postalcode, null, fillInAddress);
      return false;
    });

    function fillInAddress(data) {
      if (data.status) {
        var d = data.data;
        var address = d.prefecture + d.city + d.address_under_city + d.name;
        $('#myform-address').val(address);
      }
    }
    </script>

This one is a test node for the request handler. If you also want to test the function japan_postal_code_get_address_by_postal_code(), please try using it in drush php or similar functionality.