Latte
0.0.1indexedAccess Japan Post Digital Address and Postal Code APIs. Offers direct or proxy-based API access, automatic token management, coroutine support, and a secure proxy server setup.
0
Stars
—
Used by
dependents
—
Health
/ 100
Latte
郵便番号・デジタルアドレスAPI クライアントライブラリ for Kotlin
Latte は日本郵便のデジタルアドレス・郵便番号APIにアクセスするためのKotlinマルチプラットフォームライブラリです。
JVM、Android、iOS、WebAssembly JSをサポートしています。
特徴
✅ 各種APIに対応
✅ 直接利用、あるいはプロキシ利用を想定したインターフェース
✅ トークンの自動再利用
✅ Kotlin Coroutines対応
✅ クロスプラットフォーム（JVM、Android、iOS、WebAssembly JS）
アーキテクチャ
Latteは以下のコンポーネントで構成されています：
導入方法
Gradle
// 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)
}
}
利用方法（プロキシの構築）
プロキシサーバーを構築することで、以下のメリットがあります：
- クライアントアプリケーションにAPIの認証情報を埋め込む必要がなくなる
- 複数のクライアントで認証情報を共有できる
- APIの呼び出し回数を制限・管理できる
- クライアント側の実装を簡素化できる
前提条件
プロキシサーバーを構築するには以下が必要です：
- JDK 17以上 (gradle要件)
- Kotlin 2.1.21以上
- 日本郵便デジタルアドレスAPIのアカウント（クライアントIDとシークレットキー）
環境変数の設定
プロキシサーバーは .env ファイルを使用して設定します。以下の環境変数を設定してください：
プロキシサーバーの起動
以下のコマンドでプロキシサーバーを起動します：
cd server
./gradlew run
サーバーが起動すると、設定したポートでリクエストを受け付けるようになります。
SSL対応プロキシサーバーの設定
プロキシサーバーはSSL/TLSをサポートしており、HTTPS接続を使用できます。SSL/TLSを有効にするには以下の手順が必要です：
- Java KeyStore (JKS) 形式の証明書を用意する
- 環境変数にSSL設定を追加する
- SSL設定でサーバーを起動する
JKS証明書の準備
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設定でのサーバー起動
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
}
}
latte = Latte.of(
ConnectionInfo.Proxy()
.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 the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.