NAV Logo
cURL

API v3 リファレンス

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

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

エンドポイント

APIのベースURLです。

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

APIキー

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

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

APIキーの取得

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

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

クエリパラメータの場合

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

リクエストヘッダの場合

# apikey ヘッダにAPIキーを設定します。
curl https://apis.postcode-jp.com/api/v3/postcodes \
  -G -v \
  -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,
  "oldPostcode": string,
  "pref": string,
  "city": string,
  "town": string,
  "allAddress": string,
  "office": string,
  "hiragana": {
    "pref": string,
    "city": string,
    "town": string,
    "office": string,
    "allAddress": string
  },
  "halfWidthKana": {
    "pref": string,
    "city": string,
    "town": string,
    "office": string,
    "allAddress": string
  },
  "fullWidthKana": {
    "pref": string,
    "city": string,
    "town": string,
    "office": string,
    "allAddress": string
  },
  "generalPostcode": boolean,
  "officePostcode": boolean,
  "location": {
    "latitude": number,
    "longitude": number
  }
}
プロパティ 値の型 説明 備考
allCode string 全国地方公共団体コード 半角数字5桁
prefCode string 都道府県コード 半角数字2桁
cityCode string 市区町村町コード 半角数字3桁
postcode string 郵便番号 半角数字7桁 *2
oldPostcode string 旧郵便番号 半角数字 *8
pref string 都道府県名 漢字 *6
city string 市区町村名 漢字 *6
town string 町域名 漢字 *6
office string 大口事業所名 漢字 *1 *6
allAddress string 都道府県市区町村町域名 漢字 *6
hiragana.pref string 都道府県名 ひらがな *5
hiragana.city string 市区町村名 ひらがな *5
hiragana.town string 町域名 ひらがな *5
hiragana.office string 大口事業所名 ひらがな *1 *5
hiragana.allAddress string 都道府県市区町村町域名 ひらがな *5
halfWidthKana.pref string 都道府県名 半角カタカナ *3
halfWidthKana.city string 市区町村名 半角カタカナ *3
halfWidthKana.town string 町域名 半角カタカナ *3
halfWidthKana.office string 大口事業所名 半角カタカナ *1 *3
halfWidthKana.allAddress string 都道府県市区町村町域名 半角カタカナ *3
fullWidthKana.pref string 都道府県名 全角カタカナ *4
fullWidthKana.city string 市区町村名 全角カタカナ *4
fullWidthKana.town string 町域名 全角カタカナ *4
fullWidthKana.office string 大口事業所名 全角カタカナ *1 *4
fullWidthKana.allAddress string 都道府県市区町村町域名 全角カタカナ *4
generalPostcode boolean 一般郵便番号の場合はtrue
officePostcode boolean 大口事業所個別番号の場合はtrue
location.latitude number ロケーション 緯度 SRID=4326(WGS84地理座標系) *7
location.longitude number ロケーション 緯度 SRID=4326(WGS84地理座標系) *7

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

郵便番号リソースの部分応答

部分応答を利用すると、郵便番号リソースすべての項目を取得するのではなく必要な項目のみを取得することができます。
返されるデータを選択的にすることにより、ペイロードサイズを削減できます。
リクエストのクエリパラメータfieldsにレスポンスに必要な項目のプロパティ名をカンマ区切りで指定します。

fieldsクエリパラメータによる部分応答リクエスト

# fields クエリパラメータに取得するプロパティ名を指定します。
curl https://apis.postcode-jp.com/api/v3/postcodes \
  -G -v \
  -d "postcode=1000001" \
  -d "fields=allAddress,location,hiragana.allAddress" 

レスポンスボディ

{
  "data": [
    {
      "postcode": "1000001",
      "hiragana": {
        "allAddress": "とうきょうとちよだくちよだ"
      },
      "location": {
        "latitude": 35.683799743652344,
        "longitude": 139.7539520263672
      },
      "allAddress": "東京都千代田区千代田"
    }
  ],
  "size": 1,
  "limit": 10,
  "hasNext": false,
  "hasPrev": false,
  "version": "2019-10-19T00:04:31+0900"
}

以下は、郵便番号リソースでどのプロパティがfieldsに指定可能かを示しています。
部分応答可否のものが指定可能なプロパティです。

プロパティ 部分応答可否 備考
allCode
prefCode
cityCode
postcode - 常に対象となる
oldPostcode
pref
city
town
office
allAddress
hiragana hiraganaに含まれるすべての項目が対象となる
hiragana.pref
hiragana.city
hiragana.town
hiragana.office
hiragana.allAddress
halfWidthKana halfWidthKanaに含まれるすべての項目が対象となる
halfWidthKana.pref
halfWidthKana.city
halfWidthKana.town
halfWidthKana.office
halfWidthKana.allAddress
fullWidthKana fullWidthKanaに含まれるすべての項目が対象となる
fullWidthKana.pref
fullWidthKana.city
fullWidthKana.town
fullWidthKana.office
fullWidthKana.allAddress
generalPostcode
officePostcode
location locationに含まれるすべての項目が対象となる
location.latitude -
location.longitude -

凡例)○:設定可能 -:設定不可

郵便番号一覧

GET /api/v3/postcodes

$ curl https://apis.postcode-jp.com/api/v3/postcodes \
  -G -v \
  -d "postcode=1000" \
  -d "startWith=true" \
  -d "limit=2"

RESPONSE

{
  "data": [
    {
      "allCode": "13101",
      "prefCode": "13",
      "cityCode": "101",
      "postcode": "1000000",
      "oldPostcode": "100",
      "hiragana": {
        "pref": "とうきょうと",
        "city": "ちよだく",
        "town": "",
        "allAddress": "とうきょうとちよだく"
      },
      "halfWidthKana": {
        "pref": "トウキョウト",
        "city": "チヨダク",
        "town": "",
        "allAddress": "トウキョウトチヨダク"
      },
      "fullWidthKana": {
        "pref": "トウキョウト",
        "city": "チヨダク",
        "town": "",
        "allAddress": "トウキョウトチヨダク"
      },
      "generalPostcode": true,
      "officePostcode": false,
      "location": {
        "latitude": 35.69400405883789,
        "longitude": 139.75360107421875
      },
      "pref": "東京都",
      "city": "千代田区",
      "town": "",
      "allAddress": "東京都千代田区"
    },
    {
      "allCode": "13101",
      "prefCode": "13",
      "cityCode": "101",
      "postcode": "1000001",
      "oldPostcode": "100",
      "hiragana": {
        "pref": "とうきょうと",
        "city": "ちよだく",
        "town": "ちよだ",
        "allAddress": "とうきょうとちよだくちよだ"
      },
      "halfWidthKana": {
        "pref": "トウキョウト",
        "city": "チヨダク",
        "town": "チヨダ",
        "allAddress": "トウキョウトチヨダクチヨダ"
      },
      "fullWidthKana": {
        "pref": "トウキョウト",
        "city": "チヨダク",
        "town": "チヨダ",
        "allAddress": "トウキョウトチヨダクチヨダ"
      },
      "generalPostcode": true,
      "officePostcode": false,
      "location": {
        "latitude": 35.683799743652344,
        "longitude": 139.7539520263672
      },
      "pref": "東京都",
      "city": "千代田区",
      "town": "千代田",
      "allAddress": "東京都千代田区千代田"
    }
  ],
  "size": 2,
  "limit": 2,
  "hasNext": true,
  "nextCursor": "znouHjPHtkTe7XNnW9bxsjld0HZEsqAkWGzZKcewCrM",
  "hasPrev": false,
  "version": "2019-10-19T00:04:31+0900"
}

郵便番号の完全一致や前方一致で郵便番号リソースを検索します。
住所入力フォームで郵便番号が入力された際の住所補完用途で利用するには最適のAPIです。

クエリパラメータでその挙動をカスタマイズできます。パラメータが設定されていない場合はパラメータ固有のデフォルトの挙動になります。

リクエスト

クエリパラメータ

名前 説明
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文字。
fields string レスポンスに含める項目。 郵便番号リソースの部分応答を参照。

レスポンス

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

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

郵便番号取得

GET /api/v3/postcodes/{postcode}

$ curl https://apis.postcode-jp.com/api/v3/postcodes/2790031 \
  -G -v 

RESPONSE

{
  "allCode": "12227",
  "prefCode": "12",
  "cityCode": "227",
  "postcode": "2790031",
  "oldPostcode": "279",
  "hiragana": {
    "pref": "ちばけん",
    "city": "うらやすし",
    "town": "まいはま",
    "allAddress": "ちばけんうらやすしまいはま"
  },
  "halfWidthKana": {
    "pref": "チバケン",
    "city": "ウラヤスシ",
    "town": "マイハマ",
    "allAddress": "チバケンウラヤスシマイハマ"
  },
  "fullWidthKana": {
    "pref": "チバケン",
    "city": "ウラヤスシ",
    "town": "マイハマ",
    "allAddress": "チバケンウラヤスシマイハマ"
  },
  "generalPostcode": true,
  "officePostcode": false,
  "location": {
    "latitude": 35.63948059082031,
    "longitude": 139.88424682617188
  },
  "pref": "千葉県",
  "city": "浦安市",
  "town": "舞浜",
  "allAddress": "千葉県浦安市舞浜"
}

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

リクエスト

パスパラメータ

名前 説明
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文字。
fields string レスポンスに含める項目。 郵便番号リソースの部分応答を参照。

レスポンス

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

GET /api/v3/search

$ curl https://apis.postcode-jp.com/api/v3/search \
  -G -v \
  --data-urlencode "q=ディズニー ホテル" 

RESPONSE

{
  "data": [
    {
      "allCode": "12227",
      "prefCode": "12",
      "cityCode": "227",
      "postcode": "2798505",
      "hiragana": {
        "pref": "ちばけん",
        "city": "うらやすし",
        "town": "まいはま29-1",
        "office": "とうきょうでぃずに-らんどほてる",
        "allAddress": "ちばけんうらやすしまいはま29-1 とうきょうでぃずに-らんどほてる"
      },
      "halfWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ29-1",
        "office": "トウキョウディズニ-ランドホテル",
        "allAddress": "チバケンウラヤスシマイハマ29-1 トウキョウディズニ-ランドホテル"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ29-1",
        "office": "トウキョウディズニ-ランドホテル",
        "allAddress": "チバケンウラヤスシマイハマ29-1 トウキョウディズニ-ランドホテル"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.636972,
        "longitude": 139.877995
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜29-1",
      "office": "東京ディズニーランドホテル",
      "allAddress": "千葉県浦安市舞浜29-1 東京ディズニーランドホテル"
    },
    {
      "allCode": "12227",
      "prefCode": "12",
      "cityCode": "227",
      "postcode": "2798519",
      "hiragana": {
        "pref": "ちばけん",
        "city": "うらやすし",
        "town": "まいはま1-13",
        "office": "とうきょうでぃずに-し-・ほてるみらこすた",
        "allAddress": "ちばけんうらやすしまいはま1-13 とうきょうでぃずに-し-・ほてるみらこすた"
      },
      "halfWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ1-13",
        "office": "トウキョウディズニ-シ-・ホテルミラコスタ",
        "allAddress": "チバケンウラヤスシマイハマ1-13 トウキョウディズニ-シ-・ホテルミラコスタ"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ1-13",
        "office": "トウキョウディズニ-シ-・ホテルミラコスタ",
        "allAddress": "チバケンウラヤスシマイハマ1-13 トウキョウディズニ-シ-・ホテルミラコスタ"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.6274255,
        "longitude": 139.8871018
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜1-13",
      "office": "東京ディズニーシー・ホテルミラコスタ",
      "allAddress": "千葉県浦安市舞浜1-13 東京ディズニーシー・ホテルミラコスタ"
    },
    {
      "allCode": "12227",
      "prefCode": "12",
      "cityCode": "227",
      "postcode": "2798522",
      "hiragana": {
        "pref": "ちばけん",
        "city": "うらやすし",
        "town": "まいはま2ばんち11",
        "office": "でぃずに-あんばさだ-ほてる",
        "allAddress": "ちばけんうらやすしまいはま2ばんち11 でぃずに-あんばさだ-ほてる"
      },
      "halfWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ2バンチ11",
        "office": "ディズニ-アンバサダ-ホテル",
        "allAddress": "チバケンウラヤスシマイハマ2バンチ11 ディズニ-アンバサダ-ホテル"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ2バンチ11",
        "office": "ディズニ-アンバサダ-ホテル",
        "allAddress": "チバケンウラヤスシマイハマ2バンチ11 ディズニ-アンバサダ-ホテル"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.63302230834961,
        "longitude": 139.88729858398438
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜2番地11",
      "office": "ディズニーアンバサダーホテル",
      "allAddress": "千葉県浦安市舞浜2番地11 ディズニーアンバサダーホテル"
    }
  ],
  "size": 3,
  "limit": 20,
  "hasNext": false,
  "hasPrev": false,
  "version": "2019-10-19T00:04:31+0900"
}

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

リクエスト

GET https://apis.postcode-jp.com/api/v3/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文字。
fields string レスポンスに含める項目。 郵便番号リソースの部分応答を参照。

レスポンス

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

プロパティ 値の型 説明 備考
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,
  "halfWidthKana": string,
  "fullWidthKana": string,
  "hiragana": string,
  "location": {
    "latitude": number,
    "longitude": number
  }
}
プロパティ 値の型 説明 備考
prefCode string 都道府県名コード 半角数字2桁
pref string 都道府県名 漢字
halfWidthKana string 都道府県名 半角カタカナ
fullWidthKana string 都道府県名 全角カタカナ
hiragana string 都道府県名 ひらがな
location.latitude number ロケーション 緯度 SRID=4326(WGS84地理座標系)
location.longitude number ロケーション 緯度 SRID=4326(WGS84地理座標系)

都道府県一覧

GET /api/v3/prefectures

$ curl https://apis.postcode-jp.com/api/v3/prefectures \
  -G -v 

RESPONSE

{
  "data": [
    {
      "prefCode": "01",
      "pref": "北海道",
      "halfWidthKana": "ホッカイドウ",
      "fullWidthKana": "ホッカイドウ",
      "hiragana": "ほっかいどう",
      "location": {
        "latitude": 43.064613342285156,
        "longitude": 141.3468017578125
      }
    },
    {
      "prefCode": "02",
      "pref": "青森県",
      "halfWidthKana": "アオモリケン",
      "fullWidthKana": "アオモリケン",
      "hiragana": "あおもりけん",
      "location": {
        "latitude": 40.82430648803711,
        "longitude": 140.74000549316406
      }
    },
    {
      "prefCode": "03",
      "pref": "岩手県",
      "halfWidthKana": "イワテケン",
      "fullWidthKana": "イワテケン",
      "hiragana": "いわてけん",
      "location": {
        "latitude": 39.70362091064453,
        "longitude": 141.15267944335938
      }
    },
    {
      "prefCode": "04",
      "pref": "宮城県",
      "halfWidthKana": "ミヤギケン",
      "fullWidthKana": "ミヤギケン",
      "hiragana": "みやぎけん",
      "location": {
        "latitude": 38.268836975097656,
        "longitude": 140.87210083007812
      }
    },
    {
      "prefCode": "05",
      "pref": "秋田県",
      "halfWidthKana": "アキタケン",
      "fullWidthKana": "アキタケン",
      "hiragana": "あきたけん",
      "location": {
        "latitude": 39.71861267089844,
        "longitude": 140.1023712158203
      }
    },
    {
      "prefCode": "06",
      "pref": "山形県",
      "halfWidthKana": "ヤマガタケン",
      "fullWidthKana": "ヤマガタケン",
      "hiragana": "やまがたけん",
      "location": {
        "latitude": 38.24043655395508,
        "longitude": 140.36363220214844
      }
    },
    {
      "prefCode": "07",
      "pref": "福島県",
      "halfWidthKana": "フクシマケン",
      "fullWidthKana": "フクシマケン",
      "hiragana": "ふくしまけん",
      "location": {
        "latitude": 37.75029754638672,
        "longitude": 140.46754455566406
      }
    },
    {
      "prefCode": "08",
      "pref": "茨城県",
      "halfWidthKana": "イバラキケン",
      "fullWidthKana": "イバラキケン",
      "hiragana": "いばらきけん",
      "location": {
        "latitude": 36.34181213378906,
        "longitude": 140.44679260253906
      }
    },
    {
      "prefCode": "09",
      "pref": "栃木県",
      "halfWidthKana": "トチギケン",
      "fullWidthKana": "トチギケン",
      "hiragana": "とちぎけん",
      "location": {
        "latitude": 36.56572341918945,
        "longitude": 139.88356018066406
      }
    },
    {
      "prefCode": "10",
      "pref": "群馬県",
      "halfWidthKana": "グンマケン",
      "fullWidthKana": "グンマケン",
      "hiragana": "ぐんまけん",
      "location": {
        "latitude": 36.39066696166992,
        "longitude": 139.06040954589844
      }
    },
    {
      "prefCode": "11",
      "pref": "埼玉県",
      "halfWidthKana": "サイタマケン",
      "fullWidthKana": "サイタマケン",
      "hiragana": "さいたまけん",
      "location": {
        "latitude": 35.856998443603516,
        "longitude": 139.6488494873047
      }
    },
    {
      "prefCode": "12",
      "pref": "千葉県",
      "halfWidthKana": "チバケン",
      "fullWidthKana": "チバケン",
      "hiragana": "ちばけん",
      "location": {
        "latitude": 35.60505676269531,
        "longitude": 140.12330627441406
      }
    },
    {
      "prefCode": "13",
      "pref": "東京都",
      "halfWidthKana": "トウキョウト",
      "fullWidthKana": "トウキョウト",
      "hiragana": "とうきょうと",
      "location": {
        "latitude": 35.68948745727539,
        "longitude": 139.69171142578125
      }
    },
    {
      "prefCode": "14",
      "pref": "神奈川県",
      "halfWidthKana": "カナガワケン",
      "fullWidthKana": "カナガワケン",
      "hiragana": "かながわけん",
      "location": {
        "latitude": 35.447505950927734,
        "longitude": 139.64234924316406
      }
    },
    {
      "prefCode": "15",
      "pref": "新潟県",
      "halfWidthKana": "ニイガタケン",
      "fullWidthKana": "ニイガタケン",
      "hiragana": "にいがたけん",
      "location": {
        "latitude": 37.90255355834961,
        "longitude": 139.02310180664062
      }
    },
    {
      "prefCode": "16",
      "pref": "富山県",
      "halfWidthKana": "トヤマケン",
      "fullWidthKana": "トヤマケン",
      "hiragana": "とやまけん",
      "location": {
        "latitude": 36.695289611816406,
        "longitude": 137.21133422851562
      }
    },
    {
      "prefCode": "17",
      "pref": "石川県",
      "halfWidthKana": "イシカワケン",
      "fullWidthKana": "イシカワケン",
      "hiragana": "いしかわけん",
      "location": {
        "latitude": 36.59468078613281,
        "longitude": 136.62557983398438
      }
    },
    {
      "prefCode": "18",
      "pref": "福井県",
      "halfWidthKana": "フクイケン",
      "fullWidthKana": "フクイケン",
      "hiragana": "ふくいけん",
      "location": {
        "latitude": 36.06517791748047,
        "longitude": 136.22152709960938
      }
    },
    {
      "prefCode": "19",
      "pref": "山梨県",
      "halfWidthKana": "ヤマナシケン",
      "fullWidthKana": "ヤマナシケン",
      "hiragana": "やまなしけん",
      "location": {
        "latitude": 35.66415786743164,
        "longitude": 138.56845092773438
      }
    },
    {
      "prefCode": "20",
      "pref": "長野県",
      "halfWidthKana": "ナガノケン",
      "fullWidthKana": "ナガノケン",
      "hiragana": "ながのけん",
      "location": {
        "latitude": 36.65129852294922,
        "longitude": 138.1809539794922
      }
    },
    {
      "prefCode": "21",
      "pref": "岐阜県",
      "halfWidthKana": "ギフケン",
      "fullWidthKana": "ギフケン",
      "hiragana": "ぎふけん",
      "location": {
        "latitude": 35.39122772216797,
        "longitude": 136.7222900390625
      }
    },
    {
      "prefCode": "22",
      "pref": "静岡県",
      "halfWidthKana": "シズオカケン",
      "fullWidthKana": "シズオカケン",
      "hiragana": "しずおかけん",
      "location": {
        "latitude": 34.97711944580078,
        "longitude": 138.38308715820312
      }
    },
    {
      "prefCode": "23",
      "pref": "愛知県",
      "halfWidthKana": "アイチケン",
      "fullWidthKana": "アイチケン",
      "hiragana": "あいちけん",
      "location": {
        "latitude": 35.1801872253418,
        "longitude": 136.9065704345703
      }
    },
    {
      "prefCode": "24",
      "pref": "三重県",
      "halfWidthKana": "ミエケン",
      "fullWidthKana": "ミエケン",
      "hiragana": "みえけん",
      "location": {
        "latitude": 34.730281829833984,
        "longitude": 136.5085906982422
      }
    },
    {
      "prefCode": "25",
      "pref": "滋賀県",
      "halfWidthKana": "シガケン",
      "fullWidthKana": "シガケン",
      "hiragana": "しがけん",
      "location": {
        "latitude": 35.00453186035156,
        "longitude": 135.86859130859375
      }
    },
    {
      "prefCode": "26",
      "pref": "京都府",
      "halfWidthKana": "キョウトフ",
      "fullWidthKana": "キョウトフ",
      "hiragana": "きょうとふ",
      "location": {
        "latitude": 35.02124786376953,
        "longitude": 135.75559997558594
      }
    },
    {
      "prefCode": "27",
      "pref": "大阪府",
      "halfWidthKana": "オオサカフ",
      "fullWidthKana": "オオサカフ",
      "hiragana": "おおさかふ",
      "location": {
        "latitude": 34.68629837036133,
        "longitude": 135.5196533203125
      }
    },
    {
      "prefCode": "28",
      "pref": "兵庫県",
      "halfWidthKana": "ヒョウゴケン",
      "fullWidthKana": "ヒョウゴケン",
      "hiragana": "ひょうごけん",
      "location": {
        "latitude": 34.69126892089844,
        "longitude": 135.18307495117188
      }
    },
    {
      "prefCode": "29",
      "pref": "奈良県",
      "halfWidthKana": "ナラケン",
      "fullWidthKana": "ナラケン",
      "hiragana": "ならけん",
      "location": {
        "latitude": 34.685333251953125,
        "longitude": 135.83274841308594
      }
    },
    {
      "prefCode": "30",
      "pref": "和歌山県",
      "halfWidthKana": "ワカヤマケン",
      "fullWidthKana": "ワカヤマケン",
      "hiragana": "わかやまけん",
      "location": {
        "latitude": 34.22598648071289,
        "longitude": 135.16751098632812
      }
    },
    {
      "prefCode": "31",
      "pref": "鳥取県",
      "halfWidthKana": "トットリケン",
      "fullWidthKana": "トットリケン",
      "hiragana": "とっとりけん",
      "location": {
        "latitude": 35.50389099121094,
        "longitude": 134.23773193359375
      }
    },
    {
      "prefCode": "32",
      "pref": "島根県",
      "halfWidthKana": "シマネケン",
      "fullWidthKana": "シマネケン",
      "hiragana": "しまねけん",
      "location": {
        "latitude": 35.472293853759766,
        "longitude": 133.05050659179688
      }
    },
    {
      "prefCode": "33",
      "pref": "岡山県",
      "halfWidthKana": "オカヤマケン",
      "fullWidthKana": "オカヤマケン",
      "hiragana": "おかやまけん",
      "location": {
        "latitude": 34.66175079345703,
        "longitude": 133.9344024658203
      }
    },
    {
      "prefCode": "34",
      "pref": "広島県",
      "halfWidthKana": "ヒロシマケン",
      "fullWidthKana": "ヒロシマケン",
      "hiragana": "ひろしまけん",
      "location": {
        "latitude": 34.39656066894531,
        "longitude": 132.45962524414062
      }
    },
    {
      "prefCode": "35",
      "pref": "山口県",
      "halfWidthKana": "ヤマグチケン",
      "fullWidthKana": "ヤマグチケン",
      "hiragana": "やまぐちけん",
      "location": {
        "latitude": 34.18595504760742,
        "longitude": 131.47064208984375
      }
    },
    {
      "prefCode": "36",
      "pref": "徳島県",
      "halfWidthKana": "トクシマケン",
      "fullWidthKana": "トクシマケン",
      "hiragana": "とくしまけん",
      "location": {
        "latitude": 34.06571960449219,
        "longitude": 134.55935668945312
      }
    },
    {
      "prefCode": "37",
      "pref": "香川県",
      "halfWidthKana": "カガワケン",
      "fullWidthKana": "カガワケン",
      "hiragana": "かがわけん",
      "location": {
        "latitude": 34.34014892578125,
        "longitude": 134.04344177246094
      }
    },
    {
      "prefCode": "38",
      "pref": "愛媛県",
      "halfWidthKana": "エヒメケン",
      "fullWidthKana": "エヒメケン",
      "hiragana": "えひめけん",
      "location": {
        "latitude": 33.84162521362305,
        "longitude": 132.76568603515625
      }
    },
    {
      "prefCode": "39",
      "pref": "高知県",
      "halfWidthKana": "コウチケン",
      "fullWidthKana": "コウチケン",
      "hiragana": "こうちけん",
      "location": {
        "latitude": 33.55970764160156,
        "longitude": 133.5310821533203
      }
    },
    {
      "prefCode": "40",
      "pref": "福岡県",
      "halfWidthKana": "フクオカケン",
      "fullWidthKana": "フクオカケン",
      "hiragana": "ふくおかけん",
      "location": {
        "latitude": 33.60657501220703,
        "longitude": 130.41830444335938
      }
    },
    {
      "prefCode": "41",
      "pref": "佐賀県",
      "halfWidthKana": "サガケン",
      "fullWidthKana": "サガケン",
      "hiragana": "さがけん",
      "location": {
        "latitude": 33.24944305419922,
        "longitude": 130.29978942871094
      }
    },
    {
      "prefCode": "42",
      "pref": "長崎県",
      "halfWidthKana": "ナガサキケン",
      "fullWidthKana": "ナガサキケン",
      "hiragana": "ながさきけん",
      "location": {
        "latitude": 32.749839782714844,
        "longitude": 129.8675994873047
      }
    },
    {
      "prefCode": "43",
      "pref": "熊本県",
      "halfWidthKana": "クマモトケン",
      "fullWidthKana": "クマモトケン",
      "hiragana": "くまもとけん",
      "location": {
        "latitude": 32.789825439453125,
        "longitude": 130.74166870117188
      }
    },
    {
      "prefCode": "44",
      "pref": "大分県",
      "halfWidthKana": "オオイタケン",
      "fullWidthKana": "オオイタケン",
      "hiragana": "おおいたけん",
      "location": {
        "latitude": 33.2381706237793,
        "longitude": 131.6126251220703
      }
    },
    {
      "prefCode": "45",
      "pref": "宮崎県",
      "halfWidthKana": "ミヤザキケン",
      "fullWidthKana": "ミヤザキケン",
      "hiragana": "みやざきけん",
      "location": {
        "latitude": 31.911094665527344,
        "longitude": 131.42388916015625
      }
    },
    {
      "prefCode": "46",
      "pref": "鹿児島県",
      "halfWidthKana": "カゴシマケン",
      "fullWidthKana": "カゴシマケン",
      "hiragana": "かごしまけん",
      "location": {
        "latitude": 31.56014633178711,
        "longitude": 130.5579833984375
      }
    },
    {
      "prefCode": "47",
      "pref": "沖縄県",
      "halfWidthKana": "オキナワケン",
      "fullWidthKana": "オキナワケン",
      "hiragana": "おきなわけん",
      "location": {
        "latitude": 26.212400436401367,
        "longitude": 127.6809310913086
      }
    }
  ],
  "size": 47,
  "hasNext": false,
  "hasPrev": false,
  "version": "2019-10-19T00:04:31+0900"
}

リクエスト

クエリパラメータ

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

レスポンス

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

プロパティ 値の型 説明 備考
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,
  "hiragana": string,
  "fullWidthKana": string,
  "halfWidthKana": string,
  "location": {
    "latitude": number,
    "longitude": number
  }
}
プロパティ 値の型 説明 備考
cityCode string 市区町村名コード 半角数字3桁
city string 市区町村名 漢字
hiragana string 市区町村名 ひらがな
fullWidthKana string 市区町村名 全角カタカナ
halfWidthKana string 市区町村名 半角カタカナ
location.latitude number ロケーション 緯度 SRID=4326(WGS84地理座標系)
location.longitude number ロケーション 緯度 SRID=4326(WGS84地理座標系)

市区町村一覧

GET /api/v3/prefectures/{prefCode}/cities

$ curl https://apis.postcode-jp.com/api/v3/prefectures/05/cities \
  -G -v \
  -d "limit=3"

RESPONSE

{
  "data": [
    {
      "cityCode": "201",
      "city": "秋田市",
      "hiragana": "あきたし",
      "fullWidthKana": "アキタシ",
      "halfWidthKana": "アキタシ",
      "location": {
        "latitude": 39.71992111206055,
        "longitude": 140.10357666015625
      }
    },
    {
      "cityCode": "202",
      "city": "能代市",
      "hiragana": "のしろし",
      "fullWidthKana": "ノシロシ",
      "halfWidthKana": "ノシロシ",
      "location": {
        "latitude": 40.211891174316406,
        "longitude": 140.0269775390625
      }
    },
    {
      "cityCode": "203",
      "city": "横手市",
      "hiragana": "よこてし",
      "fullWidthKana": "ヨコテシ",
      "halfWidthKana": "ヨコテシ",
      "location": {
        "latitude": 39.31378173828125,
        "longitude": 140.566650390625
      }
    }
  ],
  "size": 3,
  "limit": 3,
  "hasNext": true,
  "nextCursor": "siqW0xgYZW22qmXd-yogVdyDJz3CE3YtZWK943NV1iA",
  "hasPrev": false,
  "version": "2019-10-19T00:04:31+0900"
}

リクエスト

パスパラメータ

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

クエリパラメータ

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

レスポンス

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

プロパティ 値の型 説明 備考
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,
  "generalCharacters": {
    "hiragana": string,
    "halfWidthKana": string,
    "fullWidthKana": string
  },
  "officeCharacters": {
    "hiragana": string,
    "halfWidthKana": string,
    "fullWidthKana": string
  }
}
プロパティ 値の型 説明 備考
version string 郵便番号データのバージョン ISO 8601 "YYYY-MM-DDThh:mm:ss+09:00"
updateZipCodeCnt integer 一般郵便番号の件数
updateJigyousyoCnt integer 大口事業所個別番号の件数
generalCharacters.halfWidthKana string 一般郵便番号の半角カタカナ項目に含まれる全ての文字
generalCharacters.fullWidthKana string 一般郵便番号の全角カタカナ項目に含まれる全ての文字
generalCharacters.hiragana string 一般郵便番号の全角ひらがな項目に含まれる全ての文字
officeCharacters.halfWidthKana string 大口事業所個別番号の半角カタカナ項目に含まれる全ての文字
officeCharacters.fullWidthKana string 大口事業所個別番号の全角カタカナ項目に含まれる全ての文字
officeCharacters.hiragana string 大口事業所個別番号の全角ひらがな項目に含まれる全ての文字

バージョン取得

GET /api/v3/postcodes/version

$ curl https://apis.postcode-jp.com/api/v3/postcodes/version \
  -G -v 

RESPONSE

{
  "versionCode": "2019-10-19T00:04:31+0900",
  "updateZipCodeCnt": 130426,
  "updateJigyousyoCnt": 22339,
  "generalCharacters": {
    "hiragana": "、あぃいうぇえおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでとどなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろわん゛・ー-0123456789ABCOPSXYZ",
    "halfWidthKana": "-0123456789ABCOPSXYZ、・ィェャュョッーアイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワン゙゚",
    "fullWidthKana": "、゛アィイウェエオカガキギクグケゲコゴサザシジスズセゼソゾタダチヂッツヅテデトドナニヌネノハバパヒビピフブプヘベペホボポマミムメモャヤュユョヨラリルレロワン・ー-0123456789ABCOPSXYZ"
  },
  "officeCharacters": {
    "hiragana": " 、ぁあぃいうぇえぉおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでとどなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろわをん゛・ー!&(),-./0123456789:<>ABCDEFGHIJKLMNOPQRSTUVWXYZadeghinoprtw~",
    "halfWidthKana": " !\u0026(),-./0123456789:\u003c\u003eABCDEFGHIJKLMNOPQRSTUVWXYZadeghinoprtw~、・ヲァィェォャュョッーアイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワン゙゚",
    "fullWidthKana": " 、゛ァアィイウェエォオカガキギクグケゲコゴサザシジスズセゼソゾタダチヂッツヅテデトドナニヌネノハバパヒビピフブプヘベペホボポマミムメモャヤュユョヨラリルレロワヲン・ー!&(),-./0123456789:<>ABCDEFGHIJKLMNOPQRSTUVWXYZadeghinoprtw~"
  }
}

リクエスト

クエリパラメータ

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

リリースノート

2019-10-7

API v3 をリリースしました。

リソースのプロパティ名変更と統合

各リソースのプロパティ名の変更、ひらがな、全角かな、半角かなプロパティの統合が行われました。

郵便番号リソース

都道府県リソース

市区町村リソース
* locaftionプロパティ名をlocationへ変更。
* cityHalfKanaプロパティ名を halfWidthKanaへ変更。
* cityFullKanaプロパティ名を fullWidthKanaへ変更。
* cityFullHiraプロパティ名を hiraganaへ変更。

バージョンリソース

過去のバージョン