identity IT

Now, let's try to get the "address" by calling the Japan Post Digital Address API. Is this really OAuth?

Nat 2025-06-01 No Comments

Sorry for the delay in posting, as I have been feeling unwell. In the previous article, I got a Japan Post digital address and used it in the shipping label creation app provided by Japan Post. This time, I will get it via API."Postal Code/Digital Address API" pageSince it supports OAuth 2.0 and OpenID Connect, there is no choice but to do it.

Get Yu-ID Biz

Now, to access the Yu-ID API, you must register with Postal Code/Digital Address for Biz. When you go to the registration page, you will see the following screen.

It seems that you can change your username later. Once you enter a suitable name, the "Register" button will turn black and become available for pressing, so press it.

Then, the screen for organization registration will appear. It seems that you can register as both a corporation and a sole proprietor. I was fine with either, but I decided to go with the corporation option, which has more input fields. I also happen to own a company called NAT Consulting LLC.

Once you have completed the registration, you will be taken to a screen that shows a user list.

This screen not only shows the user list, but also a "Settings" menu showing the settings made by the organization, and under "Services" there are links in the left menu to a page about the "Postal Code and Digital Address API" and a page for "Searching for an address from a digital address." Let's go straight to the "Postal Code and Digital Address API" page we're looking for.

Click to open the menu.

The "System List" allows you to view a list of registered clients and register clients.

In "Test AI Credentials", you can display the client_id and client_secret for using the test API. There is also documentation for the test API reference. The first thing you need to do is create a client to call the test API, which you will need to do while looking at this. The API reference looks like this:

The "Download" button seems to download the OpenAPI Spec, but I was unable to download it. I'd like to see this fixed.

The API reference contains the production API reference.

The usage guidelines include notes on how to handle "digital address" data.

The release notes are currently blank.

The data source contains the CSV file that is the source of the data provided by this API.

Let’s try the test API now.

Now, let's try hitting the test API and see how OAuth and OpenID Connect are used.

Obtaining an Access Token

According to the documentation, it seems to supportOAuth 2.0 [RFC6749] Ofclient_credentials grant It seems that only the above is used. The access token is obtained in the above, but normally it is sent in the Authorization Header (which the server must support) or as a parameter in the request body, but it is sent in the body as JSON.

It is like this.

{
"grant_type": "client_credentials",
"client_id": "Test_Client_Identifier_String",
"secret_key": "Test_Secret_Key"
}

This is not defined in OAuth 2.0.Proprietary specificationsBy the way, if you send it using the method specified in RFC6749, it will result in a Bad Request.

This is not the only unique specification. In this case, the request must include x-forwarded-for. This is also a unique extension. I can understand the feeling, but... By the way, there is no specification as to what to put in. I think it is probably the IP address of the terminal connecting to this client. However, according to RFC7239, x-forwarded-for should be discontinued and Forwarded should be used instead.

By the way, the API endpoint can be displayed by clicking on the documentation path.

With this in mind, we send a request to the test API, which can be obtained from the API documentation.

curl -X POST https://stub-qz73x.da.pf.japanpost.jp/api/v1/j/token \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "Test_Client_Identifier_String",
    "secret_key": "Test_Secret_Key"
  }'

If you do that, you will get a response like this:

{"token":"eyJhbGciOiJSU.中略.TmrM38fAf8cgNm1QAnf-j0YFQA",
"token_type":"jwt",
"expires_in":600,
"scope":"J1"}

Oh, the access token is in JWT format. Its contents look like this:

Header

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

{
  "iss": "JPD",
  "sub": "DGA TOKEN",
  "scope": "J1",
  "clientId": "Biz_DaPfJapanpost_MockAPI_j3QKS",
  "ec_id": "8aeaf147-112f-4127-8cbb-2eff08a8e161",
  "iat": 1742886316,
  "exp": 1742886916
}

It looks like this. Oh, the typ is strange.RFC9068According to this, the type should be at+jwt.

Also, since iss is just a string, it is not possible to find the JWK and therefore cannot be verified, but this is not a problem since it is Japan Post itself that does the verification. I thought that sub would contain the client_id, but it seems that this is not the case and is a fixed string.

Now, let's try to resolve the digital address to an address.

Using this access token, we now make an OAuth request to the search endpoint. The access token can be sent in the Authorization Header. X-Forwarded-For is still sent as usual. The test API allows searches for three test digital addresses (A3E7FK2, JN2LKS4, QN2GQX6) and postal codes and individual business postal codes for Chiyoda-ku, Tokyo.

With curl it looks like this.

curl -X GET https://stub-qz73x.da.pf.japanpost.jp/api/v1/searchcode/A7E2FK2 \
  -H "Authorization: Bearer eyJhbGci..中略..QAnf-j0YFQA" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -H "Accept: application/json"

Then it will come back with something like this:

{
	"page": 1,
	"limit": 1000,
	"count": 1,
	"searchtype": "dgacode",
	"addresses": [
		{
			"dgacode": "A7E2FK2",
			"zip_code": "100-0005",
			"pref_code": "13",
			"pref_name": "東京都",
			"pref_kana": null,
			"pref_roma": null,
			"city_code": "13101",
			"city_name": "千代田区",
			"city_kana": null,
			"city_roma": null,
			"town_name": "丸の内",
			"town_kana": null,
			"town_roma": null,
			"biz_name": null,
			"biz_kana": null,
			"biz_roma": null,
			"block_name": "２丁目７−２",
			"other_name": "部屋番号：サンプル１",
			"address": "東京都千代田区丸の内２丁目７−２部屋番号：サンプル１",
			"longitude": null,
			"latitude": null
		}
	]
}

Well, the response is not the OpenID Connect UserInfo response, but is unique.

By the way, if you specify a digital address other than the three above,

{
"request_id":"848f5369-56fb-4488-aecd-b82599a1b2f9",
"error_code":"404-1029-0001",
"message":"該当するデジアドがありませんでした"
}

and come back.

Accessing the production environment

Ok, so that worked, now let's try accessing the production environment.

The process is the same as for testing, except that the destination, client_id, and client_secret are changed. The client_id and client_secret for production can be obtained by registering the client in the "System List" menu.

To get the token, go to https://api.da.pf.japanpost.jp/api/v1/j/token Please change it to and request.

curl -X POST https://api.da.pf.japanpost.jp/api/v1/j/token \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "クライアントID",
    "secret_key": "クライアントシークレット"
  }'

An Access Token will be returned, so use it to make a request. The JSON shown above will be returned. You can also specify a zip code instead of a digital address.

  curl -X GET https://api.da.pf.japanpost.jp/api/v1/searchcode/6180000 \
  -H "Authorization: Bearer eyJhbGciOiJS..中略..wV0si0TiQ" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -H "Accept: application/json"

するとこんなふうに帰ってきます。
{
  "page": 1,
  "limit": 1000,
  "count": 2,
  "searchtype": "zipcode",
  "addresses": [
    {
      "dgacode": null,
      "zip_code": "6180000",
      "pref_code": "26",
      "pref_name": "京都府",
      "pref_kana": "キョウトフ",
      "pref_roma": "KYOTO",
      "city_code": "26303",
      "city_name": "乙訓郡大山崎町",
      "city_kana": "オトクニグンオオヤマザキチョウ",
      "city_roma": "OTOKUNI-GUN OYAMAZAKI-CHO",
      "town_name": "",
      "town_kana": "",
      "town_roma": "",
      "biz_name": null,
      "biz_kana": null,
      "biz_roma": null,
      "block_name": null,
      "other_name": null,
      "address": null,
      "longitude": null,
      "latitude": null
    },
    {
      "dgacode": null,
      "zip_code": "6180000",
      "pref_code": "27",
      "pref_name": "大阪府",
      "pref_kana": "オオサカフ",
      "pref_roma": "OSAKA",
      "city_code": "27301",
      "city_name": "三島郡島本町",
      "city_kana": "ミシマグンシマモトチョウ",
      "city_roma": "MISHIMA-GUN SHIMAMOTO-CHO",
      "town_name": "",
      "town_kana": "",
      "town_roma": "",
      "biz_name": null,
      "biz_kana": null,
      "biz_roma": null,
      "block_name": null,
      "other_name": null,
      "address": null,
      "longitude": null,
      "latitude": null
    }
  ]
}

My Feelings, Then and Now

So, to summarize.

  1. Digital Ad Conversion APIRFC6749The Access Token is obtained using a unique specification similar to the client credentials grant. This Access Token is a JWT, but the typ RFC9068As specified, it is not at+jwt but JWT.
  2. Now, use the obtained Access TokenRFC6750The code is sent in this format to obtain the character string (not necessarily an address) registered to the digital address.
    • You can register any string, so for example, you could register something like "A letter from Tokyo said, 'You do not exist.' I don't show up in the mirror, and people don't notice. I quietly vanished." as an address.1.
  3. I can't find anything that looks like OpenID Connect yet.
  4. You can also get addresses by specifying the postal code instead of the digital address. If there are duplicates, multiple addresses will be returned in an array.

By the way, there are a lot of duplicate postal codes. According to information, there are as many as 1,341 duplicates. Some of them are even duplicates for different prefectures... How did this happen...?

Pin

footnote

  1. Well, the same goes for the address claim in OpenID Connect.

Leave a comment

This site uses Akismet to reduce spam.For details of how to process comment data, please click here.