NAV Logo
cURL

API v5 リファレンス

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

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

エンドポイント

APIのベースURLです。

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

APIキー

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

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

APIキーの取得

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

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

クエリパラメータの場合

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

リクエストヘッダの場合

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

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

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

{
  "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
  }
}
プロパティ 値の型 説明 備考
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/v5/postcodes/1000001 \
  -G -v \
  -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に指定可能かを示しています。
部分応答可否が○のものが指定可能なプロパティです。

プロパティ 部分応答可否 備考
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/v5/postcodes/{postcode}

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

RESPONSE

[
  {
    "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": "千葉県浦安市舞浜"
  }
]

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

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

リクエスト

パスパラメータ

名前 値 説明
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/v5/postcodes

$ curl https://apis.postcode-jp.com/api/v5/postcodes \
  -G -v \
  -d "filter=postcode==100*" \
  -d "limit=2"

RESPONSE

{
  "data": [
    {
      "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": "東京都千代田区"
    },
    {
      "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リクエスト ヘッダーのどちらかに設定します。
filter string 郵便番号リソースを検索するフィルタ構文。
limit integer 取得する最大件数。1～50。(デフォルト: 10)
cursor string フェッチを開始する位置を示すカーソル (直前のレスポンスのnextCursorまたはprevCursorの値)
callback string JSONPを利用する場合のコールバック関数名。最大1000文字。
fields string レスポンスに含める項目。郵便番号リソースの部分応答を参照。
sort string 郵便番号リソースの並び替え順序。

レスポンス

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

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

フィルタ構文

クエリパラメータのfilterを使用すると、郵便番号リソースを柔軟にフィルタできます。
例えば、次のようにリソースをクエリできます。

/postcodes?filter=postcode==131*
これは郵便番号が131で始まる郵便番号リソースを検索します。

/postcodes?filter=(pref==千葉県 or pref==神奈川県) and city!=*市
これは千葉県と神奈川県の市町村名末尾が"市"ではない郵便番号リソースを検索します。

フィルタ式は、論理演算子で相互に関連付けられた1つ以上の比較で構成されます。

フィルタ構文 - 論理演算子

AND演算子が優先されます。（OR演算子よりも先に評価されます。)
ただし、括弧( )で囲まれた式を利用して評価の優先順位を変更できます。

フィルタ構文 - 比較

比較は、プロパティ名 演算子 引数 で構成されます。

フィルタ構文 - プロパティ名

プロパティ名は、フィルターを適用するフィールドたとえばpostcodeやprefCodeなどを識別します。

フィルタ構文 - 演算子

フィルタ構文 - 引数

引数は、単一の値、またはコンマで区切られた括弧内の複数の値です。
含む、含まないの引数では、一つまたは複数の引数を括弧で囲みます。

予約文字や空白を含まない値は引用符で囲むことはできません。
他の引数は一重引用符または二重引用符で囲む必要があります。
例えば引数内で括弧を利用するにはfilter=pref=re="^千.*(府|県)$"のように引用符で囲みます。

引用符で囲まれた引数内で一重引用符と二重引用符の両方を使用する必要がある場合は、\（バックスラッシュ）を使用してそれらの一方をエスケープする必要があります。
\を文字通りに使用したい場合は、\\のようにエスケープして使用します。
バックスラッシュは、引用符で囲まれていない引数内ではなく、引用符で囲まれた引数内でのみ特別な意味を持ちます。

フィルタ構文 - パターンマッチング

演算子の等しいと等しくないの引数では、パターンマッチングを使用できます。

引数の中にあるアンダースコア _ はすべての一文字とのマッチを意味し、アスタリスク * は 0 文字以上の文字列とのマッチを意味します。

フィルタ構文 - 正規表現

演算子正規表現の引数に、一般的な正規表現構文を使用できます。

APIの正規表現エンジンの構文は他の多くの正規表現エンジンの構文と同じですが、一部特徴的な違いがあります。

他の正規表現の構文との特徴的な違いは ^ と $ です。APIの正規表現の構文では ^ は行頭を表し、 $ は行末を表します。
他の多くの正規表現の構文では、 ^ はテキストの先頭を表し、 $ はテキストの最後を表します。
APIの正規表現の構文ではテキストの先頭を表す場合は \A を使い、テキストの最後を表す場合は \z を使います。

すべての構文は以下で説明されています。
https://github.com/k-takata/Onigmo/blob/master/doc/RE.ja

フィルタ構文の文法

 input          = or, EOF;
 or             = and, { ( "," | " or " ) , and };
 and            = constraint, { ( ";" | " and " ), constraint };
 constraint     = ( group | comparison );
 group          = "(", or, ")";

 comparison     = selector, comparator, arguments;
 selector       = unreserved-str;

 comparator     = comp-fiql | comp-alt;
 comp-fiql      = ( ( "=", { ALPHA } ) | "!" ), "=";
 comp-alt       = ( ">" | "<" ), [ "=" ];

 arguments      = ( "(", value, { "," , value }, ")" ) | value;
 value          = unreserved-str | double-quoted | single-quoted;

 unreserved-str = unreserved, { unreserved }
 single-quoted  = "'", { ( escaped | all-chars - ( "'" | "\" ) ) }, "'";
 double-quoted  = '"', { ( escaped | all-chars - ( '"' | "\" ) ) }, '"';

 reserved       = '"' | "'" | "(" | ")" | ";" | "," | "=" | "!" | "~" | "<" | ">" | " ";
 unreserved     = all-chars - reserved;
 escaped        = "\", all-chars;
 all-chars      = ? all unicode characters ?;

サンプル

サンプル 備考
postcode==2790031 郵便番号の完全一致
postcode==279* 郵便番号の前方一致 (比較演算子)
postcode=re=^279.*$ 郵便番号の前方一致 (正規表現)
単純なパターンマッチングは正規表現よりも比較演算子を使ったほうが高速です。
city=in=(京都市下京区,京都市上京区) 複数の市区町村内を検索
postcode>=1000100;postcode<=1000110 郵便番号の範囲指定
pref==京都府;(town==*五条*,town==*六条*) ANDとORの組み合わせ

並び替え

並び替えを利用すると、レスポンスに含まれる郵便番号リソースの出力順序を並び替えることができます。
並べ替えを指定しない場合、都道府県コード、市区町村コード、郵便番号の昇順で出力されます。

リクエストのクエリパラメータsortで並べ替えの順番を、項目のプロパティ名で指定します。
複数の項目で並び替える場合はプロパティ名をカンマ区切りで指定します。

プロパティ名の前に省略可能な+または-を付与することで、並べ替えの方向を昇順または降順にするかを指定できます。

sortクエリパラメータによる並び替えリクエスト

# sort クエリパラメータに取得するプロパティ名を指定します。
curl https://apis.postcode-jp.com/api/v5/postcodes \
  -G -v \
  -d "filter=prefCode==10" \
  -d "sort=-hiragana.city,hiragana.town" \
  -d "fields=hiragana.city,hiragana.town" \
  -d "limit=2"

レスポンスボディ

{
  "data": [
    {
      "hiragana": {
        "city": "やすなかし",
        "town": "あんなか１ちょうめ２３－１３"
      }
    },
    {
      "hiragana": {
        "city": "やすなかし",
        "town": "いそべ２ちょうめ１３－１"
      }
    }
  ],
  "size": 2,
  "limit": 2,
  "hasNext": true,
  "nextCursor": "DieS12R33auPfIuSG1Cl4Az-rT04fLOrFSXjCvVhWazaRfNt5byc8lXagLWHBNj5m_SqTad0_TLzrMjaRvbMpA",
  "hasPrev": false,
  "version": "2021-12-04T00:04:41+0900"
}

以下は、郵便番号リソースでどのプロパティがsortに指定可能かを示しています。
並び替え可否が○のものが指定可能なプロパティです。

プロパティ 並び替え可否 備考
prefCode ○
cityCode ○
postcode ○
oldPostcode ○
pref ○
city ○
town ○
office ○
allAddress ○
hiragana.pref ○
hiragana.city ○
hiragana.town ○
hiragana.office ○
hiragana.allAddress ○
halfWidthKana.pref ○
halfWidthKana.city ○
halfWidthKana.town ○
halfWidthKana.office ○
halfWidthKana.allAddress ○
fullWidthKana.pref ○
fullWidthKana.city ○
fullWidthKana.town ○
fullWidthKana.office ○
fullWidthKana.allAddress ○
generalPostcode -
officePostcode -
location.latitude -
location.longitude -

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

都道府県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/v5/prefectures

$ curl https://apis.postcode-jp.com/api/v5/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/v5/prefectures/{prefCode}/cities

$ curl https://apis.postcode-jp.com/api/v5/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/v5/postcodes/version

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

RESPONSE

{
  "versionCode": "2019-10-19T00:04:31+0900",
  "updateZipCodeCnt": 130426,
  "updateJigyousyoCnt": 22339,
  "generalCharacters": {
    "hiragana": "、あぃいうぇえおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでとどなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろわん゛・ー－０１２３４５６７８９ＡＢＣＯＰＳＸＹＺ",
    "halfWidthKana": "-0123456789ABCOPSXYZ､･ｨｪｬｭｮｯｰｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝﾞﾟ",
    "fullWidthKana": "、゛アィイウェエオカガキギクグケゲコゴサザシジスズセゼソゾタダチヂッツヅテデトドナニヌネノハバパヒビピフブプヘベペホボポマミムメモャヤュユョヨラリルレロワン・ー－０１２３４５６７８９ＡＢＣＯＰＳＸＹＺ"
  },
  "officeCharacters": {
    "hiragana": "　、ぁあぃいうぇえぉおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでとどなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろわをん゛・ー！＆（），－．／０１２３４５６７８９：＜＞ＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＱＲＳＴＵＶＷＸＹＺａｄｅｇｈｉｎｏｐｒｔｗ～",
    "halfWidthKana": " !\u0026(),-./0123456789:\u003c\u003eABCDEFGHIJKLMNOPQRSTUVWXYZadeghinoprtw~､･ｦｧｨｪｫｬｭｮｯｰｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝﾞﾟ",
    "fullWidthKana": "　、゛ァアィイウェエォオカガキギクグケゲコゴサザシジスズセゼソゾタダチヂッツヅテデトドナニヌネノハバパヒビピフブプヘベペホボポマミムメモャヤュユョヨラリルレロワヲン・ー！＆（），－．／０１２３４５６７８９：＜＞ＡＢＣＤＥＦＧＨＩＪＫＬＭＮＯＰＱＲＳＴＵＶＷＸＹＺａｄｅｇｈｉｎｏｐｒｔｗ～"
  }
}

リクエスト

クエリパラメータ

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

リリースノート

2021-12-4

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

API仕様追加

過去のバージョン

cURL