232 lines
7.6 KiB
Markdown
232 lines
7.6 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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
|