API v3 リファレンス

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

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

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

エンドポイント

APIのベースURLです。

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

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

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

{
  "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 にはリスト形式で出力されます。

プロパティ	値の型	説明
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	レスポンスに含める項目。郵便番号リソースの部分応答を参照。

レスポンス

郵便番号検索

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": "まいはま２９－１",
        "office": "とうきょうでぃずに－らんどほてる",
        "allAddress": "ちばけんうらやすしまいはま２９－１　とうきょうでぃずに－らんどほてる"
      },
      "halfWidthKana": {
        "pref": "ﾁﾊﾞｹﾝ",
        "city": "ｳﾗﾔｽｼ",
        "town": "ﾏｲﾊﾏ29-1",
        "office": "ﾄｳｷｮｳﾃﾞｨｽﾞﾆ-ﾗﾝﾄﾞﾎﾃﾙ",
        "allAddress": "ﾁﾊﾞｹﾝｳﾗﾔｽｼﾏｲﾊﾏ29-1 ﾄｳｷｮｳﾃﾞｨｽﾞﾆ-ﾗﾝﾄﾞﾎﾃﾙ"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ２９－１",
        "office": "トウキョウディズニ－ランドホテル",
        "allAddress": "チバケンウラヤスシマイハマ２９－１　トウキョウディズニ－ランドホテル"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.636972,
        "longitude": 139.877995
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜２９－１",
      "office": "東京ディズニーランドホテル",
      "allAddress": "千葉県浦安市舞浜２９－１　東京ディズニーランドホテル"
    },
    {
      "allCode": "12227",
      "prefCode": "12",
      "cityCode": "227",
      "postcode": "2798519",
      "hiragana": {
        "pref": "ちばけん",
        "city": "うらやすし",
        "town": "まいはま１－１３",
        "office": "とうきょうでぃずに－し－・ほてるみらこすた",
        "allAddress": "ちばけんうらやすしまいはま１－１３　とうきょうでぃずに－し－・ほてるみらこすた"
      },
      "halfWidthKana": {
        "pref": "ﾁﾊﾞｹﾝ",
        "city": "ｳﾗﾔｽｼ",
        "town": "ﾏｲﾊﾏ1-13",
        "office": "ﾄｳｷｮｳﾃﾞｨｽﾞﾆ-ｼ-･ﾎﾃﾙﾐﾗｺｽﾀ",
        "allAddress": "ﾁﾊﾞｹﾝｳﾗﾔｽｼﾏｲﾊﾏ1-13 ﾄｳｷｮｳﾃﾞｨｽﾞﾆ-ｼ-･ﾎﾃﾙﾐﾗｺｽﾀ"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ１－１３",
        "office": "トウキョウディズニ－シ－・ホテルミラコスタ",
        "allAddress": "チバケンウラヤスシマイハマ１－１３　トウキョウディズニ－シ－・ホテルミラコスタ"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.6274255,
        "longitude": 139.8871018
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜１－１３",
      "office": "東京ディズニーシー・ホテルミラコスタ",
      "allAddress": "千葉県浦安市舞浜１－１３　東京ディズニーシー・ホテルミラコスタ"
    },
    {
      "allCode": "12227",
      "prefCode": "12",
      "cityCode": "227",
      "postcode": "2798522",
      "hiragana": {
        "pref": "ちばけん",
        "city": "うらやすし",
        "town": "まいはま２ばんち１１",
        "office": "でぃずに－あんばさだ－ほてる",
        "allAddress": "ちばけんうらやすしまいはま２ばんち１１　でぃずに－あんばさだ－ほてる"
      },
      "halfWidthKana": {
        "pref": "ﾁﾊﾞｹﾝ",
        "city": "ｳﾗﾔｽｼ",
        "town": "ﾏｲﾊﾏ2ﾊﾞﾝﾁ11",
        "office": "ﾃﾞｨｽﾞﾆ-ｱﾝﾊﾞｻﾀﾞ-ﾎﾃﾙ",
        "allAddress": "ﾁﾊﾞｹﾝｳﾗﾔｽｼﾏｲﾊﾏ2ﾊﾞﾝﾁ11 ﾃﾞｨｽﾞﾆ-ｱﾝﾊﾞｻﾀﾞ-ﾎﾃﾙ"
      },
      "fullWidthKana": {
        "pref": "チバケン",
        "city": "ウラヤスシ",
        "town": "マイハマ２バンチ１１",
        "office": "ディズニ－アンバサダ－ホテル",
        "allAddress": "チバケンウラヤスシマイハマ２バンチ１１　ディズニ－アンバサダ－ホテル"
      },
      "generalPostcode": false,
      "officePostcode": true,
      "location": {
        "latitude": 35.63302230834961,
        "longitude": 139.88729858398438
      },
      "pref": "千葉県",
      "city": "浦安市",
      "town": "舞浜２番地１１",
      "office": "ディズニーアンバサダーホテル",
      "allAddress": "千葉県浦安市舞浜２番地１１　ディズニーアンバサダーホテル"
    }
  ],
  "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	レスポンスに含める項目。郵便番号リソースの部分応答を参照。

レスポンス

プロパティ	値の型	説明
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": "、あぃいうぇえおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてでとどなにぬねのはばぱひびぴふぶぷへべぺほぼぽまみむめもゃやゅゆょよらりるれろわん゛・ー－０１２３４５６７８９ＡＢＣＯＰＳＸＹＺ",
    "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 -- メンテナンスのため一時的にオフラインです。後でもう一度やり直してください。

リリースノート

2019-10-7

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

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

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

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

郵便番号リソース

oldPostcodeプロパティを追加。
locaftionプロパティ名をlocationへ変更。
prefFullHira、cityFullHira、townFullHira、allAddressFullKana、officeFullKanaプロパティを削除し、hiraganaプロパティを追加して統合。
prefHalfKana、cityHalfKana、townHalfKana、allAddressHalfKana、officeHalfKanaプロパティを削除し、halfWidthKanaプロパティを追加して統合。
prefFullKana、cityFullKana、townFullKana、allAddressFullHira、officeFullHiraプロパティを削除し、fullWidthKanaプロパティを追加して統合。

都道府県リソース

locaftionプロパティ名をlocationへ変更。
prefHalfKanaプロパティ名を halfWidthKanaへ変更。
prefFullKanaプロパティ名を fullWidthKanaへ変更。
prefFullHiraプロパティ名を hiraganaへ変更。

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

バージョンリソース

generalHalfKanaCharacters、generalFullKanaCharacters、generalFullHiraCharactersプロパティを削除し、generalCharactersプロパティを追加して統合。
officeHalfKanaCharacters、officeFullKanaCharacters、officeFullHiraCharactersプロパティを削除し、officeCharactersプロパティを追加して統合。

過去のバージョン

API バージョン2のリファレンス

API v3 リファレンス

エンドポイント

APIキー

APIキーの取得

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

郵便番号API

郵便番号リソース

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

郵便番号一覧

リクエスト

クエリパラメータ

レスポンス

郵便番号取得

リクエスト

パスパラメータ

クエリパラメータ

レスポンス

郵便番号検索

リクエスト

クエリパラメータ

レスポンス

都道府県API

都道府県リソース

都道府県一覧

リクエスト

クエリパラメータ

レスポンス

市区町村API

市区町村リソース

市区町村一覧

リクエスト

パスパラメータ

クエリパラメータ

レスポンス

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

バージョンリソース

バージョン取得

リクエスト

クエリパラメータ

レスポンス

エラーレスポンス

リソース

HTTPステータスコード

リリースノート

2019-10-7

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

過去のバージョン

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