Japan Post Service API Client

📖 日本語版のREADMEはこちらをご覧ください / For Japanese README, please see here

A TypeScript client for the Japan Post Service API. This library provides convenient methods to interact with the official Japan Post API endpoints for authentication and address/zipcode search.

Refer to the service's official documentation for details.

Features

Here are the key features:

• ✅ Obtain authentication tokens using client credentials
• 🔍 Search for addresses by postal codes, business postal codes, and digital addresses
• 🏠 Search for zip codes by address components
• 🔄 Automatic token refresh handling
• 📄 Easy pagination for search API calls
• ⚡ Automatic retry with rate limit handling
• 🛡️ Robust error handling (authentication, rate limits, network errors)
• ✅ Automatic input parameter validation
• 🔧 Circuit breaker pattern for fault tolerance

Installation

npm i japanpost-api

Basic Usage

import { JapanPostAPI } from 'japanpost-api';

const client = new JapanPostAPI({
  client_id: process.env.JAPAN_POST_CLIENT_ID!,
  secret_key: process.env.JAPAN_POST_SECRET_KEY!,
});

// Search for addresses by postal codes, business postal codes, and digital addresses
const search = await client.searchcode({
  search_code: 'A7E2FK2',
});
console.log(search.addresses);

// Search for zip codes by address components
const addresszip = await client.addresszip({
  pref_code: '13',
  city_code: '13101',
});
console.log(addresszip.addresses);

// Auto-pagination for searchcode API
for await (const page of client.searchcodeAll({
  search_code: 'A7E2FK2',
  limit: 10,
})) {
  console.log(page);
}

// Auto-pagination for addresszip API
for await (const page of client.addresszipAll({
  pref_code: "13",
  city_code: "13101",
  limit: 10,
})) {
  console.log(page);
}

Advanced Configuration

Auto-retry and Circuit Breaker

import { 
  JapanPostAPI, 
  RetryOptions, 
  CircuitBreakerOptions 
} from 'japanpost-api';

const retryOptions: RetryOptions = {
  maxRetries: 5,        // Maximum number of retries
  baseDelay: 2000,      // Base delay in milliseconds
  maxDelay: 30000,      // Maximum delay in milliseconds
  backoffMultiplier: 2, // Exponential backoff multiplier
};

const circuitBreakerOptions: CircuitBreakerOptions = {
  failureThreshold: 3,  // Failure threshold
  resetTimeout: 60000,  // Reset timeout in milliseconds
};

const client = new JapanPostAPI(
  {
    client_id: process.env.JAPAN_POST_CLIENT_ID!,
    secret_key: process.env.JAPAN_POST_SECRET_KEY!,
  },
  {
    retryOptions,
    circuitBreakerOptions,
    enableValidation: true, // Enable validation (default: true)
  }
);

Custom Error Handler

import { 
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NetworkError
} from 'japanpost-api';

try {
  const result = await client.searchcode({ search_code: '1000001' });
  console.log(result);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication error:', error.message);
    // Logic to re-acquire token
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit error:', error.message);
    if (error.retryAfter) {
      console.log(`Please retry after ${error.retryAfter} seconds`);
    }
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
    console.error('Problematic field:', error.field);
    console.error('Problematic value:', error.value);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
    console.error('Original error:', error.originalError);
  } else {
    console.error('Other error:', error);
  }
}

Input Validation

import { 
  validateSearchcodeRequest,
  validateAddresszipRequest,
  isValidPrefCode,
  getPrefCodeFromName
} from 'japanpost-api';

// Manual Validation
try {
  validateSearchcodeRequest({ search_code: '1000001' });
  console.log('Validation successful');
} catch (error) {
  console.error('Validation error:', error.message);
}

// Validate a given prefecture code
if (isValidPrefCode('13')) {
  console.log('Valid prefecture code');
}

// Look up prefecture code from its name
const prefCode = getPrefCodeFromName('Tokyo');
console.log(prefCode); // '13'

Monitoring Circuit Breaker's State

// Get circuit breaker state
const state = client.getCircuitBreakerState();
console.log(`Current state: ${state.state}`);
console.log(`Failure count: ${state.failureCount}`);

// Reset if necessary
if (state.state === 'OPEN') {
  client.resetCircuitBreaker();
  console.log('Circuit breaker has been reset');
}

// Dynamically update retry settings
client.updateRetryOptions({
  maxRetries: 10,
  baseDelay: 5000,
});

Error Types

This library provides the following error types:

• AuthenticationError - Authentication error (401)
• AuthorizationError - Authorization error (403)
• RateLimitError - Rate limit error (429)
• ClientError - Client error (4xx)
• ServerError - Server error (5xx)
• NetworkError - Network error
• ValidationError - Validation error
• GeneralAPIError - Other API errors

Validation Features

Automatic validation of input parameters includes the following checks:

SearchcodeRequest

• search_code: Postal code or digital address with 3 or more characters
• page: Integer of 1 or greater
• limit: Integer in the range 1-1000
• choikitype: 1 or 2
• searchtype: 1 or 2

AddresszipRequest

• At least one search condition is required
• pref_code: Prefecture code 01-47
• city_code: 5-digit city code
• Mutual exclusion control of flg_getcity and flg_getpref

TypeScript Support

Full TypeScript support enables type-safe development:

import { SearchcodeRequest, SearchcodeResponse, PrefCode } from 'japanpost-api';

const request: SearchcodeRequest = {
  search_code: '1000001',
  limit: 100,
};

const prefCode: PrefCode = '13'; // Type-safe prefecture code

Contributing

We welcome contributions! This project uses automated releases based on Conventional Commits.

Quick Start for Contributors

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes with proper commit messages:
   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
4. Run tests: npm test
5. Create a pull request

Automated Releases

Releases are automatically published when changes are merged to the main branch:

• feat: → Minor version bump
• fix: → Patch version bump
• feat!: or BREAKING CHANGE: → Major version bump

For detailed information, see CONTRIBUTING.md.

License

This project is licensed under the MIT License. See LICENSE.txt for details.