郵便番号・デジタルアドレス API とは

　「郵便番号・デジタルアドレス API」は、日本郵便株式会社が提供する「郵便番号・デジタルアドレス for Biz」のサービスラインアップの１つで、郵便番号とデジタルアドレスのそれぞれから住所を取得できる、無料のサービスです。

デジタルアドレスとは

　本 API では郵便番号を用いた住所検索の他に、2025年5月26日から開始した「デジタルアドレス」を用いて住所を検索できることが特徴です。

　デジタルアドレスとは、7桁の英数字によって利用者の住所を特定することができる、新しい仕組みです。あくまでデジタルアドレスと利用者を紐づける仕組みなので、引越しなどで住所の変更があった場合でも、デジタルアドレスの管理画面から住所を変更することで、7桁の英数字はそのままに、新しい住所を特定することが可能です。

　デジタルアドレスを利用するにはデジタルアドレスのWebサイトで利用者登録、および住所の登録をする必要があります。デジタルアドレスについてや、利用上の注意点、使える場所やサービスなどを含め、詳細はこちらの Webサイトをご覧ください。

郵便番号・デジタルアドレス API の利用開始手続き

郵便番号・デジタルアドレス for Biz のアカウント作成

　本 API を利用するには、まず郵便番号・デジタルアドレス for Biz のアカウントを作成する必要があります。

まずは [新規登録] を押して次の画面に進みます。

次に「ゆうID」を持っていなければ、ゆうID の新規登録を行います。

ゆうID の利用規約が表示されるので、内容を確認した上で問題がなければ、同意欄すべてにチェックをし、次へ進みます。

仮登録画面が表示されるので、メールアドレスを入力し、仮登録をします。

4 で入力したメールアドレス宛に仮登録完了のメールが届くので、記載されている URL から本登録画面に移り、パスワードの入力をして次へ進みます。

お客様情報の入力を行い、必須項目を埋めたら次へ進みます。

登録が完了したらログイン画面に進みます。

ゆうIDの登録の際に指定したメールアドレスとパスワードを入力し、サービスにログインします。

一旦 2 と同じ画面に移るので、次はこの画面で [ゆうID] でログインを行います。

郵便番号・デジタルアドレス for Biz の利用規約が表示されるので、内容を確認した上で、問題がなければ同意欄にチェックをし、次へ進みます。

ユーザー名を入力し、アカウントの登録を行います。

組織登録画面が表示されるので、アカウントのユーザーが所属する組織の情報を入力し、登録を行います。

これで郵便番号・デジタルアドレス for Biz のアカウント登録は完了です。

API 利用のためのシステムの登録

[サービス] -> [郵便番号・デジタルアドレスAPI] -> [システムリスト] で表示される画面で、[新規登録] を選択します。

システム登録に必要な情報を入力し、登録を行います。

登録が完了すると、API を利用するのに必要な [クライアントシークレット], [クライアントID], 入力した利用システムの固定 [IPアドレス] が表示されます。この3つは API を利用するにあたって必要な項目です。特に、クライアントシークレットはこの画面以外では確認できないので、必ず手元に控えてください。確認を終えたら、システムリストに戻ってOKです。

郵便番号・デジタルアドレス API でできること

[token]：[searchcode], [addresszip] を実行するのに必要なトークンを取得する。
[searchcode]：郵便番号, 事業所個別郵便番号, デジタルアドレスから郵便番号を検索する。
[addresszip]：住所の一部から該当する郵便番号, 住所情報を検索する。

URL から挿入を利用して API を実行する方法

はじめに

　この項では、API を実行するにあたっての最低限の設定を解説します。細かなオプションやパラメーターの意味・設定内容などについては、公式の APIリファレンスをご覧ください。

1. トークンを取得する

　[searchcode], [addresszip] を利用するのに必要なトークンの取得方法です。

【URL を指定】

　token エンドポイントを指定します。

https://api.da.pf.japanpost.jp/api/v1/j/token

【ターゲット】

　リクエストの結果を保存するフィールドまたは変数を指定します。

【cURL オプションの指定】

　リクエストメソッドは POST です。<<<systemIpAddress>>>, <<<clientId>>>, <<<clientSecret>>> には、システム登録時に入力したそれぞれの値を記述します。

curl -X POST https://stub-qz73x.da.pf.japanpost.jp/api/v1/j/token \
	-H "Content-Type: application/json" \
	-H "x-forwarded-for: <<<systemIpAddress>>>" \
	-d "{
	\"grant_type\": \"client_credentials\",
	\"client_id\": \"<<<clientId>>>\",
	\"secret_key\": \"<<<clientSecret>>>\"
}"

実行結果

　[cURL から挿入] で送信した情報に問題がない場合、以下の結果が返ってきます。これらのデータはトークンの期限の管理や他のエンドポイントへのリクエスト時に使用します。

{
	"expires_in" : <<<数値(秒)>>>,
	"scope" : "J1",
	"token" : "<<<トークン>>>",
	"token_type" : "jwt"
}

expiers_in (<<<数値(秒)>>>)：トークン期限切れまでの時間(秒) の値
token (<<<トークン>>>)：トークンの値

2. 住所を検索する

　郵便番号, 事業所個別郵便番号, デジタルアドレスのいずれかから住所を検索するための方法です。

【URL を指定】

　searchcode エンドポイントと合わせて、検索したい値を指定します。

https://api.da.pf.japanpost.jp/api/v1/searchcode/[検索する値(3桁以上7桁以下の値)]

　また、必要があれば取得するレコード数の上限や、参照するページ番号などをパラメーターとして指定することができます。

具体例）

https://api.da.pf.japanpost.jp/api/v1/searchcode/1340084?limit=50&searchtype=2

オプションの一覧

page：ページ番号 (デフォルト値:1)※1ページ100件の表示です
limit：取得する最大レコード数 (1 ~ 1,000)※公式のリファレンスにはデフォルト値 1 と書かれていますが、未指定の場合でも 1 以上値が返ってきます。
choikitype：返却する町域フィールド (指定がない場合はchoikitype=1とみなす)
- 1：カッコなし
- 2：カッコあり※どちらも試しましたが今のところ違いは見られませんでした。
searchtype：検索対象 (指定がない場合はsearchtype=1とみなす)
- 1：郵便番号, 事業所個別郵便番号, デジタルアドレス
- 2：郵便番号, デジタルアドレス

【ターゲット】

　リクエストの結果を保存するフィールドまたは変数を指定します。

【cURL オプションの指定】

　リクエストメソッドは GETです。<<<トークン>>> には、[1. トークンを取得する場合] の項で得られたトークンを記述します。

curl -X GET https://stub-qz73x.da.pf.japanpost.jp/api/v1/[検索する値(3桁以上7桁以下の値)] \
	-H "Authorization: Bearer <<<トークン>>>"

【実行結果】

　[cURL から挿入] で送信した情報に問題がない場合、以下の結果が返ってきます。複数の住所が該当した場合は、addresses の要素が複数個になり、count に該当件数が記載されます。

　※郵便番号, 事業所個別郵便番号, デジタルアドレスそれぞれのテーブル定義に差異があるため、データが無い項目については null を返します。

{
	"addresses" : 
	[
		{
			"address" : null,
			"biz_kana" : null,
			"biz_name" : null,
			"biz_roma" : null,
			"block_name" : null,
			"city_code" : "13123",
			"city_kana" : "エドガワク",
			"city_name" : "江戸川区",
			"city_roma" : "EDOGAWA-KU",
			"dgacode" : null,
			"latitude" : null,
			"longitude" : null,
			"other_name" : null,
			"pref_code" : "13",
			"pref_kana" : "トウキョウト",
			"pref_name" : "東京都",
			"pref_roma" : "TOKYO",
			"town_kana" : "ヒガシカサイ",
			"town_name" : "東葛西",
			"town_roma" : "HIGASHIKASAI",
			"zip_code" : "1340084"
		}
	],
	"count" : 1,
	"limit" : 1000,
	"page" : 1,
	"searchtype" : "zipcode"
}

count：該当件数
page：取得された結果のページ数

3. 郵便番号を検索する

　住所の一部から、該当する郵便番号, 追加の住所情報を検索するための方法です。

【URL を指定】

　addresszip エンドポイントを指定します。

https://api.da.pf.japanpost.jp/api/v1/addresszip

【ターゲット】

　リクエストの結果を保存するフィールドまたは変数を指定します。

【cURL オプションの指定】

　リクエストメソッドは POST です。<<<トークン>>> には、[1. トークンを取得する場合] の項で得られたトークンを記述します。

　また、city を指定する場合は pref を、town を指定する場合は pref と city を必ず指定する必要があります。(下位レベルの住所で検索するには上位レベルの住所の指定も必要ということ)

例) 北海道札幌市大通東で検索する場合

curl -X POST https://api.da.pf.japanpost.jp/api/v1/addresszip \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer <<<token>>>" \
	-d "{
		\"pref_name\": \"北海道\"
		\"city_name\": \"札幌市\"
		\"town_name\": \"大通東\"
	}"

リクエストパラメーターの一覧

pref_code：都道府県コード
pref_name：都道府県名
pref_kana：都道府県名カナ
pref_roma：都道府県名ローマ字
city_code：市区町村コード
city_name：市区町村名
city_kana：市区町村名カナ
city_roma：市区町村名ローマ字
town_name：町域
town_kana：町域カナ
town_roma：町域ローマ字
freeword：フリーワード
flg_getcity：市区町村一覧のみ取得フラグ (デフォルト値：0)
- 0：すべての情報を取得
- 1：市区町村のみの情報を取得
flg_getpref：都道府県一覧のみ取得フラグ (デフォルト値：0)
- 0：すべての情報を取得
- 1：都道府県のみの情報を取得)
page：ページ数 (デフォルト値：1)
limit：取得最大レコード数 (デフォルト値：1,000, 最大値：1,000)

【実行結果】

{
	"addresses" : 
	[
		{
			"city_code" : "01101",
			"city_kana" : "サッポロシチュウオウク",
			"city_name" : "札幌市中央区",
			"city_roma" : "SAPPORO-SHI CHUO-KU",
			"pref_code" : "01",
			"pref_kana" : "ホッカイドウ",
			"pref_name" : "北海道",
			"pref_roma" : "HOKKAIDO",
			"town_kana" : "オオドオリヒガシ",
			"town_name" : "大通東",
			"town_roma" : "ODORIHIGASHI",
			"zip_code" : "0600041"
		}
	],
	"count" : 1,
	"level" : 3,
	"limit" : 1000,
	"page" : 1
}

count：該当件数
level：マッチングレベル
- 1：都道府県レベルで一致
- 2：市区町村レベルで一致
- 3：町域レベルで一致
page：取得された結果のページ数

FileMaker で使ってみよう

　それでは、実際に FileMaker 上で API を実行してみましょう。

処理で使用するデータの準備

　まずは API の呼び出しやスクリプトで使用するデータを準備します。今回はわかりやすくするために、すべての値をフィールドに格納します。これらのフィールドの値は、実際に API を実行する画面から参照できるようにしておきます。

　※実際にこれらの値をどのように保存するかは、ご利用の環境のセキュリティーポリシーなどに従って実装してください。

[systemIpAddress]：システム登録時に入力した利用システムの固有IPアドレスの値です。
[clientId]：システム登録時に入力したクライアントID の値です。
[clientSecret]：システム登録時に入力したクライアントシークレットの値です。
[token]：API を利用して住所や郵便番号を検索する時に必要な値です。
[expires_in]：トークン取得時に得られたトークン期限切れまでの時間(秒) の値です。　処理中に期限切れになるのを防止するために少し余裕を持たせるようにしています。
[tokenRequestTS]：トークン取得時に得られた、トークン取得処理を行った時刻です。
[tokenExpiresTS]：[expires_in] と [tokenRequestTS] をもとに計算した、トークンの再取得の目安とする時刻です。

cURL 用のテンプレートの準備

　今回は [token], [searchcode], [addresszip] それぞれのテンプレートをレコードに保存しておき、処理ごとに該当のレコードを参照する作りにしてみました。|||文字列||| の部分は、スクリプト内の Substitute 関数でシステム値や検索ワードなどに置き換える部分です。

token

searchcode

addresszip

トークンの取得スクリプト

　郵便番号の検索スクリプトと住所の検索スクリプトのサブスクリプトとして使用します。

住所の検索

　[郵便番号] フィールドに値を入力して [住所検索] ボタンを押すと、[住所] フィールドに結果が設定されるスクリプトを作成します。

スクリプト

郵便番号の検索

　[都道府県], [市区町村], [町域], [フリーワード] フィールドに値を入力して [郵便番号検索] ボタンを押すと、[郵便番号] フィールドに結果が設定されるスクリプトを作成します。

スクリプト

※今回サンプルでお見せしたスクリプトは、あくまで最低限、値を取得して設定するスクリプトです。実際の利用シーンでそのまま使える仕組みではありませんので、ご了承ください。

郵便番号・デジタルアドレス API とは

デジタルアドレスとは

郵便番号・デジタルアドレス API の利用開始手続き

郵便番号・デジタルアドレス for Biz のアカウント作成

API 利用のためのシステムの登録

郵便番号・デジタルアドレス API でできること

URL から挿入 を利用して API を実行する方法

はじめに

1. トークンを取得する

【URL を指定】

【ターゲット】

【cURL オプションの指定】

実行結果

2. 住所を検索する

【URL を指定】

【ターゲット】

【cURL オプションの指定】

【実行結果】

3. 郵便番号を検索する

【URL を指定】

【ターゲット】

【cURL オプションの指定】

【実行結果】

FileMaker で使ってみよう

処理で使用するデータの準備

cURL 用のテンプレートの準備

token

searchcode

addresszip

トークンの取得スクリプト

住所の検索

スクリプト

郵便番号の検索

スクリプト

URL から挿入を利用して API を実行する方法