Assist_Design/docs/integrations/japanpost/api-reference.md

Japan Post Digital Address API Reference

Version: 1.0.1.250707

The Digital Address API provides features such as token issuance, ZIP Code search, company-specific ZIP Code search, and Digital Address lookup.

ZIP Code refers to Postal Code

---

Authentication

Obtaining the API Usage Token (1-1028)

Based on the grant_type of client_credentials in OAuth2.0, the API returns a usage token in response to the token request.

Endpoint: POST /api/v1/j/token

Header Parameters

Parameter	Required	Description
x-forwarded-for	Yes	Source IP address

Request Body

{
  "grant_type": "client_credentials",
  "client_id": "TEST7t6fj7eqC5v6UDaHlpvvtesttest",
  "secret_key": "testGzhSdzpZ1muyICtest0123456789"
}

Field	Required	Description
grant_type	Yes	Fixed as "client_credentials"
client_id	Yes	Client ID
secret_key	Yes	Secret Key

Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

Field	Type	Description
token	string	Access Token (JWT format)
token_type	string	Token Type
expires_in	integer	Validity duration (seconds)
scope	string	Scope

Error Responses

Status	Description
400	Bad Request - Invalid client_id or secret_key
401	Unauthorized
403	Forbidden
500	Internal Server Error

Error Response Format:

{
  "request_id": "(API execution tracking ID)",
  "error_code": "400-1028-0001",
  "message": "クライアントIDまたはシークレットキーが違います"
}

---

Endpoints

Code Number Search (1-1029)

Unified search endpoint for ZIP Code, Unique Corporate ZIP Code, and Digital Address.

Endpoint: GET /api/v1/searchcode/{search_code}

Authorization: Bearer token

Path Parameters

Parameter	Required	Description
search_code	Yes	ZIP Code (min 3 digits), Unique Corporate ZIP Code, or Digital Address

Query Parameters

Parameter	Default	Description
page	1	Page number
limit	1000	Maximum records to retrieve (max: 1000)
ec_uid	-	Provider's user ID
choikitype	1	Town field format: 1 = without brackets, 2 = with brackets
searchtype	1	Search target: 1 = ZIP + Corporate ZIP + Digital Address, 2 = ZIP + Digital Address only

Response (200 OK)

{
  "addresses": [{}, {}],
  "searchtype": "bizzipcode",
  "limit": 10,
  "count": 1,
  "page": 1
}

Error Responses

Status	Description
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

Error Response Format:

{
  "request_id": "string",
  "error_code": "string",
  "message": "string"
}

---

ZIP Code Search by Address (1-1018/1-1019)

Search for the corresponding ZIP Code and address information from part of the address.

Endpoint: POST /api/v1/addresszip

Authorization: Bearer token

Request Body

{
  "pref_code": "13",
  "city_code": "13102",
  "flg_getcity": 0,
  "flg_getpref": 0,
  "page": 1,
  "limit": 100
}

Field	Description
pref_code	Prefecture Code
pref_name	Prefecture Name
pref_kana	Prefecture Name (Kana)
pref_roma	Prefecture Name (Romanized)
city_code	City Code
city_name	City Name
city_kana	City Name (Kana)
city_roma	City Name (Romanized)
town_name	Town
town_kana	Town (Kana)
town_roma	Town (Romanized)
freeword	Free Word search
flg_getcity	Flag for city list only (0: all, 1: city only)
flg_getpref	Flag for prefecture list only (0: all, 1: prefecture only)
page	Page Number (default: 1)
limit	Max records (default: 1000, max: 1000)

Priority Notes:

• If both pref_code and pref_name are provided, pref_code takes priority
• If both city_code and city_name are provided, city_code takes priority

Response (200 OK)

{
  "addresses": [[], []],
  "level": 2,
  "limit": 100,
  "count": 2,
  "page": 1
}

Matching Levels:

• Level 1: Matches at prefecture level
• Level 2: Matches at city/ward/town/village level
• Level 3: Matches at town area level

---

Environment Variables

Variable	Required	Description
JAPAN_POST_API_URL	Yes	Base URL for Japan Post Digital Address API
JAPAN_POST_CLIENT_ID	Yes	OAuth client ID
JAPAN_POST_CLIENT_SECRET	Yes	OAuth client secret
JAPAN_POST_TIMEOUT	No	Request timeout in ms (default: 10000)

---

Error Codes Reference

Error Code Pattern	HTTP Status	Description
400-1028-0001	400	Invalid client_id or secret_key
401-*	401	Token invalid or expired
404-*	404	Resource not found
500-*	500	Internal server error

---

Notes

• ZIP codes must be 7 digits (hyphens are stripped automatically)
• If fewer than 7 digits are provided, the API searches for codes starting with the entered value
• Token is JWT format and should be cached until near expiration
• Rate limiting may apply - implement exponential backoff for retries