# 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