郵便番号検索

/address/postal_code [GET]

基本情報

概要

郵便番号を指定して住所情報を取得します。

URL

https://{HOST}/{CID}/v1/address/postal_code

※RapidAPIの場合はURL体系が異なります

出力形式

  • JSON

対応言語

  • ja, en, ko, zh-CN, zh-TW, th

出力順

  • 住所コードの昇順

パラメータ

パラメータ名 必須 概要 型名 デフォルト値 上下限/選択値 備考
postal_code 郵便番号文字列 文字列 最小:3桁
最大:7桁
limit データの出力件数 数値 10 最小値:1
最大値:100
住所データの出力数
offset データの出力開始位置 数値 0 最小値:0
最大値:2000
何件目から表示されるか(1件目が0))を指定します
lang 言語 文字列 ja: 日本語
en: 英語
ko: 韓国語
zh-CN: 中国語(簡体字)
zh-TW: 中国語(繁体字)
th: タイ語
出力する言語を指定します
・ピリオド区切りで複数指定可能
※多言語オプション申込時のみ利用可能
(RapidAPIでは利用不可)
datum 緯度経度の測地系 文字列 wgs84 wgs84:世界測地系
tokyo:旧日本測地系
coord_unit 出力データに含まれる緯度経度の単位 文字列 degree degree:度表記の10進法
millisec:ミリ秒表記

langパラメータの指定時の注意点

・多言語に対応したレスポンスはMultilingualオブジェクトとして出力されることにご注意ください。

パラメータ構成例

  • 郵便番号「1510053」の住所を10件検索
/address/postal_code?postal_code=1510053

レスポンス

名称 レスポンス名 型名 配列 説明
検索数 count Countオブジェクト レスポンスのヒット数などの情報
住所情報 items Addressオブジェクト 住所情報のまとまり
単位情報 unit Unitオブジェクト 出力される単位の情報

Countオブジェクト

名称 レスポンス名 型名 配列 説明
トータルヒット件数 total 数値 検索ヒットした件数
オフセット値 offset 数値 オフセットが設定されている場合はその値を出力
データの出力件数 limit 数値 データの出力件数に設定されている値
1件しかヒットしなかった場合でも、limit=10でリクエストしている場合は10と出力

Addressオブジェクト

名称 レスポンス名 型名 配列 説明
住所コード code 文字列
住所テキスト name 文字列/Multilingualオブジェクト langパラメータ指定時は、Multilingualオブジェクトで出力
郵便番号 postal_code 文字列
住所の緯度経度 coord Coordinateオブジェクト
レベル別の住所情報 details AddressDetailオブジェクト

Multilingualオブジェクト

名称 レスポンス名 型名 配列 説明
英語名称 en 文字列
日本語名称 ja 文字列
韓国語名称 ko 文字列
タイ語名称 th 文字列
中国語(簡体字)名称 zh-CN 文字列
中国語(繁体字)名称 zh-TW 文字列

Coordinateオブジェクト

名称 レスポンス名 型名 配列 説明
住所の代表緯度 lat 数値
住所の代表経度 lon 数値

AddressDetailオブジェクト

名称 レスポンス名 型名 配列 説明
対象レベルまでの住所コード code 文字列
対象レベルの住所テキスト name 文字列/Multilingualオブジェクト langパラメータ指定時は、Multilingualオブジェクトで出力
対象レベルの住所テキストのふりがな ruby 文字列 多言語出力指定時も日本語で出力
住所のレベル level 文字列 住所レベル
 1: 都道府県
 2: 市区町村
 3: 大字・町
 4: 小字・丁目
 5: 街区
 6: 地番
 7: 枝番

Unitオブジェクト

名称 レスポンス名 型名 配列 説明
測地系 datum 文字列
緯度経度の出力形式 coord_unit 文字列

レスポンス例

{
    "count": {
        "total": 5,
        "offset": 0,
        "limit": 10
    },
    "items": [
        {
            "code": "13113031001",
            "name": "東京都渋谷区代々木1丁目",
            "postal_code": "1510053",
            "coord": {
                "lat": 35.682655,
                "lon": 139.699269
            },
            "details": [
                {
                    "code": "13",
                    "name": "東京都",
                    "ruby": "とうきょうと",
                    "level": "1"
                },
                {
                    "code": "13113",
                    "name": "渋谷区",
                    "ruby": "しぶやく",
                    "level": "2"
                },
                {
                    "code": "13113031",
                    "name": "代々木",
                    "ruby": "よよぎ",
                    "level": "3"
                },
                {
                    "code": "13113031001",
                    "name": "1丁目",
                    "level": "4"
                }
            ]
        },
        {
            ・・・
        }
    ],
    "unit": {
        "datum": "wgs84",
        "coord_unit": "degree"
    }
}

レスポンス例(多言語返却時 ※lang=ja.en.ko指定)

{
    "count": {
        "total": 5,
        "offset": 0,
        "limit": 10
    },
    "items": [
        {
            "code": "13113031001",
            "name": {
                "en": "TokyoShibuyaYoyogi1Chome",
                "ja": "東京都渋谷区代々木1丁目",
                "ko": "도쿄도시부야구요요기1쵸메"
            },
            "postal_code": "1510053",
            "coord": {
                "lat": 35.682655,
                "lon": 139.699269
            },
            "details": [
                {
                    "code": "13",
                    "name": {
                        "en": "Tokyo",
                        "ja": "東京都",
                        "ko": "도쿄도"
                    },
                    "ruby": "とうきょうと",
                    "level": "1"
                },
                {
                    "code": "13113",
                    "name": {
                        "en": "Shibuya",
                        "ja": "渋谷区",
                        "ko": "시부야구"
                    },
                    "ruby": "しぶやく",
                    "level": "2"
                },
                {
                    "code": "13113031",
                    "name": {
                        "en": "Yoyogi",
                        "ja": "代々木",
                        "ko": "요요기"
                    },
                    "ruby": "よよぎ",
                    "level": "3"
                },
                {
                    "code": "13113031001",
                    "name": {
                        "en": "1Chome",
                        "ja": "1丁目",
                        "ko": "1쵸메"
                    },
                    "level": "4"
                }
            ]
        },
        {
            ・・・
        }
    ],
    "unit": {
        "datum": "wgs84",
        "coord_unit": "degree"
    }
}