API v2 リファレンス

PostcodeJP APIでは郵便番号データをWebクライアントやモバイルアプリケーション、Webサーバーから検索可能なAPIを提供しています。

フルマネージドの郵便番号APIを使用すれば、最新の住所を検索してユーザーに提供したり、顧客データの住所入力を自動化してユーザーエクスペリエンスを加速することができます。 APIは以下の主要な機能に対応しています。

クエリパラメータlimitによる取得件数制御
クエリパラメータcursorによる次のデータの取得、前のデータの取得
オリジン間リソース共有 (Cross-Origin Resource Sharing, CORS)
クエリパラメータcallbackによるJSONP

ベースURL

すべてのAPIはこのURLから始まります。

https://apis.postcode-jp.com/api/v2

APIキー

PostcodeJP APIは、APIキーを使用してリクエストを認証します。

認証はリクエストパラメータまたはリクエストヘッダに設定されたAPIキーを介して実行されます。すべてのAPIリクエストはHTTPSを介して行われる必要があります。

APIキーの取得

以下の手順でAPIキーを取得します。

ダッシュボードに移動します。(アカウントをお持ちでない場合はアカウントを作成してください。)
ダッシュボードの「APIキーを作成」ボタンをクリックします。
作成されたAPIキーに制限を設定します。(APIキーの盗用、不正使用を防ぐため、HTTPリファラーやIPアドレスでAPIキーを保護します。)

リクエストにAPIキーを設定する

クエリパラメータの場合

# URLの apikey クエリパラメータにAPIキーを設定します。
curl "https://apis.postcode-jp.com/api/v2/postcodes "
  -d "apikey=ここにAPIキーを設定"
  -d "postcode=1000001"

リクエストヘッダの場合

# apikey ヘッダにAPIキーを設定します。
curl "https://apis.postcode-jp.com/api/v2/postcodes "
  -H "apikey: ここにAPIキーを設定"
  -d "postcode=1000001"

住所補完JavaScriptの場合

// AutoComplementServiceのコンストラクタにAPIキーを設定します。
var autoComplement = 
  new postcodejp.address.AutoComplementService('ここにAPIキーを設定');

APIキーは、URLのクエリパラメータまたは、HTTPヘッダーのどちらかで設定することができます。

インターネットに接続されるモバイルアプリやIoTデバイス等 APIキーをIPアドレスやリファラで保護できない場合、HTTPヘッダーにAPIキーを設定してください。SSL/TLSによりAPIキーが保護されます。

郵便番号API

郵便番号APIは、日本郵便の最新郵便番号データをベースに、ユーザーが続けて入力しやすいようにカスタマイズされた高品位データを、郵便番号からまたは住所の一部から検索できるAPIです。郵便番号APIを利用すれば、郵便番号から住所を検索する機能をカスタムWebサイト、Webサーバやモバイルアプリケーションへシンプルに統合できます。

郵便番号リソース

APIで１つまたは複数の郵便番号リソースを取得することができます。郵便番号リソースには郵便番号、全国地方公共団体コードや都道府県、市区町村、町域名とそのひらがな、カタカナ等が含まれます。

郵便番号リソースのメタデータ

{
  "allCode": string,
  "prefCode": string,
  "cityCode": string,
  "postcode": string,
  "pref": string,
  "city": string,
  "town": string,
  "allAddress": string,
  "prefHalfKana": string,
  "prefFullKana": string,
  "prefFullHira": string,
  "cityHalfKana": string,
  "cityFullKana": string,
  "cityFullHira": string,
  "townHalfKana": string,
  "townFullKana": string,
  "townFullHira": string,
  "allAddressHalfKana": string,
  "allAddressFullKana": string,
  "allAddressFullHira": string,
  "office": string,
  "officeHalfKana": string,
  "officeFullKana": string,
  "officeFullHira": string,
  "generalPostcode": boolean,
  "officePostcode": boolean,
  "locaftion": {
    "latitude": number,
    "longitude": number
  }
}

プロパティ	値の型	説明	備考
allCode	string	全国地方公共団体コード	半角数字5桁
prefCode	string	都道府県コード	半角数字2桁
cityCode	string	市区町村町コード	半角数字3桁
postcode	string	郵便番号	半角数字7桁 *2
pref	string	都道府県名漢字	*6
city	string	市区町村名漢字	*6
town	string	町域名漢字	*6
allAddress	string	都道府県市区町村町域名	漢字 *6
prefHalfKana	string	都道府県名半角カタカナ	*3
prefFullKana	string	都道府県名全角カタカナ	*4
prefFullHira	string	都道府県名ひらがな	*5
cityHalfKana	string	市区町村名半角カタカナ	*3
cityFullKana	string	市区町村名全角カタカナ	*4
cityFullHira	string	市区町村名ひらがな	*5
townHalfKana	string	町域名半角カタカナ	*3
townFullKana	string	町域名全角カタカナ	*4
townFullHira	string	町域名ひらがな	*5
allAddressHalfKana	string	都道府県市区町村町域名半角カタカナ	*3
allAddressFullKana	string	都道府県市区町村町域名全角カタカナ	*4
allAddressFullHira	string	都道府県市区町村町域名ひらがな	*5
office	string	大口事業所名漢字 1 6
officeHalfKana	string	大口事業所名半角カタカナ	1 3
officeFullKana	string	大口事業所名全角カタカナ	1 4
officeFullHira	string	大口事業所名ひらがな	1 5
generalPostcode	boolean	一般郵便番号の場合はtrue
officePostcode	boolean	大口事業所個別番号の場合はtrue
locaftion.latitude	number	ロケーション緯度 SRID=4326(WGS84地理座標系)	*7
locaftion.longitude	number	ロケーション緯度 SRID=4326(WGS84地理座標系)	*7

*1) 大口事業所個別番号の住所を表す場合のみ出力される。
*2) 大口事業所個別番号の住所を表す場合は大口事業所個別番号。
*3) 半角カタカナとASCII印字可能文字のみ含まれる。
*4) 全角カタカナとASCII印字可能文字の全角文字のみ含まれる。
*5) ひらがなとASCII印字可能文字の全角文字のみ含まれる。
*6) 日本郵政から提供された文字列に半角文字が含まれる場合、半角文字はそのまま出力される。
*7) 一般郵便番号の場合は郵便番号の代表位置。大口事業所個別番号の場合は事業所の位置。
*) 半角カタカナ、全角カタカナ、全角ひらがなの項目に含まれる文字は郵便番号データバージョン取得APIで確認可能。

郵便番号一覧

郵便番号の完全一致や前方一致で郵便番号リソースを検索します。
住所入力フォームで郵便番号が入力された際の住所補完用途で利用するには最適のAPIです。
クエリパラメータでその挙動をカスタマイズできます。パラメータが設定されていない場合はパラメータ固有のデフォルトの挙動になります。

リクエスト

GET https://apis.postcode-jp.com/api/v2/postcodes

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。
postcode	string	(必須) 郵便番号または大口事業所個別番号。最大8桁。クエリパラメータ normalize も参照。
startWith	boolean	クエリパラメータ postcode の前方一致で検索するにはtrueを設定。完全一致で検索するにはfalseを設定。(デフォルト: false)
office	boolean	大口事業所個別番号を検索対象とするにはtrueを設定。検索対象外とするにはfalseを設定。(デフォルト: true)
general	boolean	一般の郵便番号を検索対象とするにはtrueを設定。検索対象外とするにはfalseを設定。(デフォルト: true)
normalize	boolean	クエリパラメータ postcode をノーマライズ (全角数字は半角数字とみなす、数字以外の文字は無視する) して検索する場合はtrueを設定。ノーマライズしない場合はfalseを設定。(デフォルト: false)
limit	integer	取得する最大件数。1～20。(デフォルト: 10)
cursor	string	フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback	string	JSONPを利用する場合のコールバック関数名。最大1000文字。

レスポンス

レスポンスボディに郵便番号リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数として郵便番号リソースが出力されます。 APIを正常に実行できない場合はエラーが出力されます。

返される郵便番号リソースが１つの場合でも data にはリスト形式で出力されます。

レスポンスボディ

{
  "data": [], // 郵便番号リソースのリスト
  "size": integer,
  "limit": integer,
  "hasNext": boolean,
  "nextCursor": string,
  "hasPrev": boolean,
  "prevCursor": string,
  "version": string
}

プロパティ	値の型	説明
data	array	検索された郵便番号リソース
size	integer	dataのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	郵便番号リソースのバージョン

郵便番号取得

指定された郵便番号に完全一致する郵便番号リソースを取得します。

リクエスト

GET https://apis.postcode-jp.com/api/v2/postcodes/{postcode}

パスパラメータ

名前	値	説明
postcode	string	(必須) 郵便番号または大口事業所個別番号。最大8桁。クエリパラメータ normalize も参照。

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。
office	boolean	大口事業所個別番号を取得対象とするにはtrueを設定。対象外とするにはfalseを設定。(デフォルト: true)
general	boolean	一般の郵便番号を取得対象とするにはtrueを設定。対象外とするにはfalseを設定。(デフォルト: true)
normalize	boolean	パスパラメータ postcode をノーマライズ (全角数字は半角数字とみなす、数字以外の文字は無視する) して検索する場合はtrueを設定。ノーマライズしない場合はfalseを設定。(デフォルト: false)
callback	string	JSONPを利用する場合のコールバック関数名。最大1000文字。

レスポンス

郵便番号検索

郵便番号データを郵便番号や住所の一部から検索できるAPIです。検索クエリは住所の一部を示す漢字、ひらがな、カタカナに対応しています。

リクエスト

GET https://apis.postcode-jp.com/api/v2/search

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。
q	string	(必須) 検索対象とする住所の一部の語句。複数の語句を指定する場合は半角スペースで区切る。複数の語句は AND 条件で検索される。
office	boolean	大口事業所個別番号を検索対象とするにはtrueを設定。検索対象外とするにはfalseを設定。(デフォルト: true)
general	boolean	一般の郵便番号を検索対象とするにはtrueを設定。検索対象外とするにはfalseを設定。(デフォルト: true)
limit	integer	取得する最大件数。1～20。(デフォルト: 20)
cursor	string	フェッチを開始する位置を示すカーソル (直前のレスポンスのcursorの値)
callback	string	JSONPを利用する場合のコールバック関数名。最大1000文字。

レスポンス

レスポンスボディ

{
  "data": [], // 郵便番号データのリスト
  "size": integer,
  "limit": integer,
  "hasNext": boolean,
  "nextCursor": string,
  "hasPrev": boolean,
  "prevCursor": string,
  "version": string
}

プロパティ	値の型	説明
data	array	検索された郵便番号リソース
size	integer	dataのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	郵便番号リソースのバージョン

都道府県API

都道府県APIは、都道府県の一覧を取得できるAPIです。

都道府県リソース

都道府県リソースのメタデータ

{
  "prefCode": string,
  "pref": string,
  "prefHalfKana": string,
  "prefFullKana": string,
  "prefFullHira": string,
  "locaftion": {
    "latitude": number,
    "longitude": number
  }
}

プロパティ	値の型	説明	備考
prefCode	string	都道府県名コード	半角数字2桁
pref	string	都道府県名漢字
prefHalfKana	string	都道府県名半角カタカナ
prefFullKana	string	都道府県名全角カタカナ
prefFullHira	string	都道府県名ひらがな
locaftion.latitude	number	ロケーション緯度	SRID=4326(WGS84地理座標系)
locaftion.longitude	number	ロケーション緯度	SRID=4326(WGS84地理座標系)

都道府県一覧

リクエスト

GET https://apis.postcode-jp.com/api/v2/prefectures

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。
limit	integer	取得する最大数
cursor	string	フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback	string	JSONPを利用する場合のコールバック関数名。最大1000文字。

レスポンス

レスポンスボディに都道府県リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数として都道府県リソースが出力されます。 APIを正常に実行できない場合はエラーが出力されます。

レスポンスボディ

{
  "data": [], // 都道府県リソースのリスト
  "size": integer,
  "limit": integer,
  "hasNext": boolean,
  "nextCursor": string,
  "hasPrev": boolean,
  "prevCursor": string,
  "version": string
}

プロパティ	値の型	説明
data	array	都道府県リソースのリスト
size	integer	dataのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	都道府県リソースのバージョン

市区町村API

市区町村APIは、指定した都道府県の市区町村を取得できるAPIです。

郵便番号データより抽出した市区町村です。総務省のまとめに基づく市町村とは異なる場合があります。

市区町村リソース

市区町村リソースのメタデータ

{
  "cityCode": string,
  "city": string,
  "cityFullHira": string,
  "cityFullKana": string,
  "cityHalfKana": string,
  "locaftion": {
    "latitude": number,
    "longitude": number
  }
}

プロパティ	値の型	説明	備考
cityCode	string	市区町村名コード	半角数字3桁
city	string	市区町村名漢字
cityFullHira	string	市区町村名ひらがな
cityFullKana	string	市区町村名全角カタカナ
cityHalfKana	string	市区町村名半角カタカナ
locaftion.latitude	number	ロケーション緯度	SRID=4326(WGS84地理座標系)
locaftion.longitude	number	ロケーション緯度	SRID=4326(WGS84地理座標系)

市区町村一覧

リクエスト

GET https://apis.postcode-jp.com/api/v2/prefectures/{prefCode}/cities

パスパラメータ

名前	値	説明
prefCode	string	都道府県コード

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。
limit	integer	取得する最大数
cursor	string	フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback	string	JSONPを利用する場合のコールバック関数名。最大1000文字。

レスポンス

レスポンスボディに市区町村リソースが出力されます。 callbackクエリパラメータを指定した場合はcallbackの引数として市区町村リソースが出力されます。 APIを正常に実行できない場合はエラーが出力されます。

レスポンスボディ

{
  "data": [], // 市区町村リソースのリスト
  "size": integer,
  "limit": integer,
  "hasNext": boolean,
  "nextCursor": string,
  "hasPrev": boolean,
  "prevCursor": string,
  "version": string
}

プロパティ	値の型	説明
data	array	市区町村リソースのリスト
size	integer	dataのサイズ
limit	integer	制限された最大件数
hasNext	string	次のリソースがある場合はtrue
nextCursor	string	次のリソースをフェッチするためのカーソル
hasPrev	string	前のリソースがある場合はtrue
prevCursor	string	前のリソースをフェッチするためのカーソル
version	string	都道府県リソースのバージョン

郵便番号データバージョンAPI

取り扱っている郵便番号データの情報を取得するAPIです。

バージョンリソース

バージョンリソースのメタデータ

{
  "version": string,
  "updateZipCodeCnt": integer,
  "updateJigyousyoCnt": integer,
  "generalHalfKanaCharacters": string,
  "generalFullKanaCharacters": string,
  "generalFullHiraCharacters": string,
  "officeHalfKanaCharacters": string,
  "officeFullKanaCharacters": string,
  "officeFullHiraCharacters": string
}

プロパティ	値の型	説明	備考
version	string	郵便番号データのバージョン	ISO 8601 "YYYY-MM-DDThh:mm:ss+09:00"
updateZipCodeCnt	integer	一般郵便番号の件数
updateJigyousyoCnt	integer	大口事業所個別番号の件数
generalHalfKanaCharacters	string	一般郵便番号の半角カタカナ項目に含まれる全ての文字
generalFullKanaCharacters	string	一般郵便番号の全角カタカナ項目に含まれる全ての文字
generalFullHiraCharacters	string	一般郵便番号の全角ひらがな項目に含まれる全ての文字
officeHalfKanaCharacters	string	大口事業所個別番号の半角カタカナ項目に含まれる全ての文字
officeFullKanaCharacters	string	大口事業所個別番号の全角カタカナ項目に含まれる全ての文字
officeFullHiraCharacters	string	大口事業所個別番号の全角ひらがな項目に含まれる全ての文字

バージョン取得

リクエスト

GET https://apis.postcode-jp.com/api/v2/postcodes/version

クエリパラメータ

名前	値	説明
apiKey	string	APIキーをこのクエリパラメータもしくは、HTTPリクエストヘッダーのどちらかに設定します。

レスポンス

レスポンスボディにバージョンリソースが出力されます。

エラー

PostcodeJP APIは、HTTPレスポンスコードを使ってAPIリクエストの成功または失敗を示します。2xxの範囲のコードは成功を示します。

APIを正常に実行できない場合、HTTPステータスコードが 2xx以外でレスポンスボディにはデバッグ目的でのみ利用可能なエラーリソースが出力されます。 APIによってハンドリングできない致命的なエラーが発生した場合 HTTPステータスコードは 5xxで返却されますが、エラーリソースが出力される保証はありません。

4xxの範囲のコードは不正なリクエストパラメータやリクエストの制限により失敗したエラーであることを示しています。

5xxの範囲のコードは、PostcodeJP APIのサーバにエラーがあることを示しています。

リソース

エラーのメタデータ

{
  "httpStatusCode": integer,
  "code": string,
  "message": string,
  "validationErrors": [
    {
      "message": string,
      "paramName": string,
      "invalidValue": string
    }
  ]
}

プロパティ	値の型	説明
httpStatusCode	integer	HTTPステータスコード
code	string	エラーコード
message	string	メッセージ
validationErrors.message	string	エラーメッセージ
validationErrors.paramName	string	エラーとなったパラメータ名
validationErrors.invalidValue	string	エラーとなったパラメータの値

HTTPステータスコード

コード	説明
400	Bad Request -- リクエストパラメータが不正です。
401	Unauthorized -- APIキーが不正です。
403	Forbidden -- リクエストが許可されていません。
404	Not Found -- リソースが存在しません。
405	Method Not Allowed -- HTTPメソッドが不正です。
406	Not Acceptable -- 受付できないリクエストです。
429	Too Many Requests -- リクエスト回数制限またはリクエストレート制限中です。
500	Internal Server Error -- サーバに異常が発生しています。後でもう一度やり直してください。
503	Service Unavailable -- メンテナンスのため一時的にオフラインです。後でもう一度やり直してください。

API v2 リファレンス

ベースURL

APIキー

APIキーの取得

リクエストにAPIキーを設定する

郵便番号API

郵便番号リソース

郵便番号一覧

リクエスト

クエリパラメータ

レスポンス

郵便番号取得

リクエスト

パスパラメータ

クエリパラメータ

レスポンス

郵便番号検索

リクエスト

クエリパラメータ

レスポンス

都道府県API

都道府県リソース

都道府県一覧

リクエスト

クエリパラメータ

レスポンス

市区町村API

市区町村リソース

市区町村一覧

リクエスト

パスパラメータ

クエリパラメータ

レスポンス

郵便番号データ バージョンAPI

バージョンリソース

バージョン取得

リクエスト

クエリパラメータ

レスポンス

エラー

リソース

HTTPステータスコード

郵便番号データバージョンAPI