Flutterで日本郵便APIを使用する

1. 郵便番号検索 japan_postal_api_client_for_flutter

今更感はあるのですが、日本郵便が公式APIを出したとの報を聞いたのと、ちょうどこの機能が必要になったタイミングが同じで、
実際にこのAPIを使う前提のパッケージはまだなかったようなので作ってみました。

2. API利用のための準備

japan_postal_api_client_for_flutter を利用して日本郵便の公式APIにアクセスするには、いくつかの事前準備が必要です。
これは、APIの提供元である日本郵便が、サービスの適切な利用とセキュリティを確保するために設けているものです。

まず、日本郵便のAPIサービスを利用するための「利用者登録」を行っていただく必要があります。
これは、APIへのアクセス権限を得るための最初のステップです。公式サイトの手順に従って、登録を完了させてください。

登録が完了すると、APIリクエスト時に認証情報として使用する「APIキー」と「クライアントID（またはシークレットキー）」が発行されます。
これらは、皆さんが正規のAPI利用者であることを証明するための重要なクレデンシャルです。
これらの情報の取得方法については、日本郵便の公式APIドキュメントに詳細が記載されていますので、そちらをご参照ください。

3. CLIプログラムでの動作確認：手軽に試せるサンプルコード

Flutterアプリケーションに組み込む前に、パッケージの基本的な動作を手軽に確認できるよう、シンプルなCLI（コマンドラインインターフェース）プログラムのサンプルを用意しました。
このサンプルは、郵便番号を引数として渡し、対応する住所を検索する機能を提供します。

// lib/main.dart
import 'dart:io';
import 'package:japan_postal_api_client/japan_postal_api_client.dart';
import 'package:public_ip_address/public_ip_address.dart'; // IPアドレス取得のために追加

// ご自身のAPIキーとシークレットキーを設定してください
const String apiKey = 'YOUR_API_KEY';
const String secretKey = 'YOUR_SECRET_KEY';

void main(List<String> arguments) async {
  if (arguments.isEmpty) {
    print('Usage: dart run bin/main.dart <postal_code>');
    exit(1);
  }

  final String postalCode = arguments[0];

  final client = JapanPostApiClient(clientId: apiKey, secretKey: secretKey);

  final ipAddress = await (IpAddress().getIp());
  final tokenResult = await client.getToken(ipAddress);

  if (tokenResult case ApiResultError(error: final e)) {
    print('error: $e');
    exit(1);
  }

  final result = await client.searchByPostalCode(postalCode);

  switch (result) {
    case ApiResultOk(data: SearchcodeSearchRes(addresses: final data)):
      for (final address in data) {
        print('$address');
      }
    case ApiResultError(error: final e, stackTrace: final s):
      print('Error: $e, $s');
    default:
      print('something went wrong');
  }

  exit(0);
}

このコードの重要な点は、public_ip_address パッケージを使って実行環境のIPアドレスを取得し、それを利用してAPIトークンを取得していることです。
日本郵便のAPIでは、セキュリティ上の理由から、リクエストごとにトークン認証が必要となるケースがあるため、この処理は不可欠です。

CLIプログラムを実行するには、以下のコマンドをターミナルで実行します。YOUR_API_KEY と YOUR_SECRET_KEY は、ご自身のAPIキーとシークレットキーに置き換えてください。

dart lib/main.dart 1000001

このサンプルコードを通じて、パッケージの基本的な機能とAPI連携の流れを理解していただけるかと思います。

5. まとめ

日本郵便の公式APIを使っているで安心感があるかと思います(？)。
多少なりとも役に立てれば幸いです。