NAV Logo

API v2 リファレンス

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

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

ベースURL

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

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

APIキー

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

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

APIキーの取得

以下の手順で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で1つまたは複数の郵便番号リソースを取得することができます。 郵便番号リソースには郵便番号、全国地方公共団体コードや都道府県、市区町村、町域名とそのひらがな、カタカナ等が含まれます。

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

{
  "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": [], // 郵便番号リソースのリスト
  "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文字。

レスポンス

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

郵便番号検索

郵便番号データを郵便番号や住所の一部から検索できる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文字。

レスポンス

レスポンスボディに郵便番号リソースが出力されます。 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です。

都道府県リソース

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

{
  "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 -- メンテナンスのため一時的にオフラインです。後でもう一度やり直してください。