郵便番号・デジタルアドレスAPI クライアントライブラリ for Kotlin

Latte は日本郵便のデジタルアドレス・郵便番号APIにアクセスするためのKotlinマルチプラットフォームライブラリです。
JVM、Android、iOS、WebAssembly JSをサポートしています。

✅ 各種APIに対応
✅ 直接利用、あるいはプロキシ利用を想定したインターフェース
✅ トークンの自動再利用
✅ Kotlin Coroutines対応
✅ クロスプラットフォーム（JVM、Android、iOS、WebAssembly JS）

Latteは以下のコンポーネントで構成されています：

• latteCore: クライアントライブラリのコア機能を提供

  • 日本郵便APIへの直接アクセス機能
  • トークン管理機能
  • 住所・郵便番号検索機能
  • マルチプラットフォーム対応（JVM、Android、iOS、WebAssembly JS）

• server: プロキシサーバーの実装

  • APIキーによる認証機能
  • レート制限機能
  • SSL/TLS対応
  • 複数クライアントでの認証情報共有

• composeApp: サンプルアプリケーション

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        // リポジトリの設定
        mavenCentral()
        // 必要に応じてGitHubパッケージなどを追加
    }
}

// build.gradle.kts
dependencies {
    implementation("com.milkcocoa.info:latte-core:0.0.1") 
}

APIを利用するにはクライアントを作成します。
下記の例は、APIに直接接続する（=プロキシを利用しない）例です。

val latte = Latte.of(
  url = "https://stb-ssss.da.pf.japanpost.jp",
  clientId = "<your client id>",
  secretKey = "<your secret key>",
  forwardedFor = ""
)

最新のトークンを取得するには、 token() を実行します。
副作用として、 Latteインスタンス内部のトークンストアの情報が更新されます。

val token = latte.token()

また、 withToken() を用いることで、期限内のトークンを再利用しながら後続の処理が実行可能です。
なお「期限内」とは、前回の取得から420秒以内を指します。（トークンの期限が600秒）

latte.withToken { token ->

}

デジタルアドレス/郵便番号/事業所個別番号などを用いて住所を検索します。

latte.withToken { token ->
    latte.search(
        token = token,
        searchCode = "100",
        params = SearchCodeRequest(
            limit = 50,
            choiki = ChoikiType.WithoutBrackets
        )
    )
}

住所に関する複数の条件を用いて、郵便番号を検索します。

latte.withToken { token ->
    latte.addressZip(
        token = token
    ){
        this.prefCode = "13"
        this.cityName = "足立区"
    }.let {
        println(it)
    }
}

プロキシサーバーを構築することで、以下のメリットがあります：

1. クライアントアプリケーションにAPIの認証情報を埋め込む必要がなくなる
2. 複数のクライアントで認証情報を共有できる
3. APIの呼び出し回数を制限・管理できる
4. クライアント側の実装を簡素化できる

プロキシサーバーを構築するには以下が必要です：

1. JDK 17以上 (gradle要件)
2. Kotlin 2.1.21以上
3. 日本郵便デジタルアドレスAPIのアカウント（クライアントIDとシークレットキー）

プロキシサーバーは .env ファイルを使用して設定します。以下の環境変数を設定してください：

## 日本郵便APIの設定

# 本番環境やテスト環境のURLに変更してください
LATTE_ENDPOINT_URL=https://stb-ssss.da.pf.japanpost.jp  

# 日本郵便から提供されたクライアントID
LATTE_CLIENT_ID=your_client_id

# 日本郵便から提供されたシークレットキー
LATTE_SECRET_KEY=your_secret_key            

## プロキシサーバーの設定
# プロキシサーバーが使用するポート番号
LATTE_SERVER_PORT=12345                            

# レート制限のリフィル期間（秒）
LATTE_TOKEN_REFILL_PERIOD=300

# 期間内に許可するAPI実行回数
LATTE_CALL_TOKEN_COUNT=60

# ロードバランサーやプロキシの背後で動作する場合はtrueに設定
# X-Forwarded-Forヘッダーを使用してクライアントの実際のIPアドレスを取得します
LATTE_SERVER_BEHIND_PROXY=false

## SSL設定（オプション）
# SSL使用時のポート番号
# LATTE_SERVER_PORT=8443

# SSL証明書の設定
# LATTE_TLS_KEYALIAS=your_key_alias
# LATTE_TLS_KEYSTORE=/path/to/your/keystore.jks
# LATTE_TLS_KEYSTORE_PASSWORD=your_keystore_password
# LATTE_TLS_KEYSTORE_PRIV_PASSWORD=your_private_key_password

以下のコマンドでプロキシサーバーを起動します：

cd server
./gradlew run

サーバーが起動すると、設定したポートでリクエストを受け付けるようになります。

プロキシサーバーはSSL/TLSをサポートしており、HTTPS接続を使用できます。SSL/TLSを有効にするには以下の手順が必要です：

1. Java KeyStore (JKS) 形式の証明書を用意する
2. 環境変数にSSL設定を追加する
3. SSL設定でサーバーを起動する

SSL/TLSを使用するには、JKS形式の証明書が必要です。既存の証明書（PEM形式など）をJKS形式に変換するには、以下のコマンドを使用します：

# PEM形式の証明書とキーからPKCS12形式に変換
openssl pkcs12 -export -in certificate.pem -inkey private_key.pem -out certificate.p12 -name "your_key_alias"

# PKCS12形式からJKS形式に変換
keytool -importkeystore -srckeystore certificate.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS

SSL設定を有効にしてサーバーを起動するには、以下のコマンドを使用します：

cd server
./gradlew run --args='-config=application-ssl.yaml'

プロキシサーバーを利用するには、クライアントを以下のように設定します：

// プロキシサーバーのURLを指定してクライアントを作成
val latte = Latte.of("http://localhost:12345")

// SSL対応プロキシサーバーの場合
// val latte = Latte.of("https://localhost:8443")

// 通常通りAPIを利用
latte.withToken { token ->
    latte.search(
        token = token,
        searchCode = "100",
        params = SearchCodeRequest(
            limit = 50,
            choiki = ChoikiType.WithoutBrackets
        )
    )
}

プロキシサーバーはAPIキーによって保護されています：

• すべてのAPIエンドポイント（/proxytokenを除く）は認証のためにX-API-KEYヘッダーが必要です
• クライアントは/proxytokenエンドポイントを呼び出すことでAPIキーを取得できます
• DefaultCredentialsProviderは自動的にAPIキーの取得と更新を処理し、latteで提供しているプロキシサーバーと連携するように設計されています

カスタム認証を実装するには、独自のCredentialsProviderを実装することができます：

// カスタム認証プロバイダーを作成
class MyCredentialsProvider : CredentialsProvider {
    override suspend fun provide(host: String): Pair<String, String> {
        // ヘッダー名と値を返す
        return "X-API-KEY" to "あなたのAPIキー"
    }
}

// プロキシ接続で使用する
val latte = Latte.of(
    ConnectionInfo.Proxy("http://localhost:12345")
        .with(MyCredentialsProvider())
)

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細は LICENSE ファイルを参照してください。

Copyright 2025 milkcocoa0902

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.