住所検索

/address [GET]

基本情報

概要

キーワードを指定して住所情報を取得します。

URL

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

※APIマーケットの場合はURL体系が異なります

出力形式

json

対応言語

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

出力順

キーワードの類似度と検索のランキングを考慮した株式会社ナビタイムジャパン独自のスコア降順

パラメータ

パラメータ名	必須	概要	型名	デフォルト値	上下限/選択値	備考
word	(✔)	検索ワード	文字列			住所のふりがなも指定可能です入力値によって検索結果が以下のようになる場合があります・何も HIT しない：入力の誤り、表記揺れ、存在しない住所など・HIT するが精度が悪い：小字・丁目以降の表記揺れが激しい場合など　例）「word=東京都渋谷区恵比寿１〜１〜１」→「東京都渋谷区恵比寿」が最上位 HIT codeとの併用は不可（どちらか片方を必ず指定）検索文字列の詳細についてはこちらをご覧ください
code	(✔)	住所コード	文字列			wordとの併用は不可（どちらか片方を必ず指定）
address_filter		住所フィルタ	文字列			特定住所を出力したい際に指定してください住所コードの頭に'-'を付けると、該当住所を出力から除外することができます word指定時のみ有効
level_to		住所レベルの上限	数値		最小値：1 最大値：7	指定の住所レベルまでの住所のみに絞り込みます　1：都道府県　2：市区町村　3：大字・町　4：小字・丁目　5：街区　6：地番　7：枝番例えば3と入力すると大字・町までヒットします東京都港区六本木6丁目10-1　→　東京都港区六本木 word指定時のみ有効
level_from		住所レベルの下限	数値		最小値：1 最大値：7	指定の住所レベルからの住所のみに絞り込みます　1：都道府県　2：市区町村　3：大字・町　4：小字・丁目　5：街区　6：地番　7：枝番例えば3と入力すると大字・町からヒットします東京都　→　東京都港区六本木 word指定時のみ有効
kana_row		出力結果フィルタ（子音）	文字列			レスポンスのうち、指定された行の文字から始まる住所のみを返却します　a：あ行　k：か行　s：さ行　t：た行　n：な行　h：は行　m：ま行　y：や行　r：ら行　w：わ行 code指定時のみ有効例えば該当パラメータにa、codeパラメータに13（東京都）と指定すると『東京都』に続く住所があ行から始まるもののみ出力されます（例：大田区）
sort		住所のソート順	文字列	code_asc	lexical：辞書順 level_asc：住所レベル昇順 code_asc：住所コード昇順	現在は「丁目・小字」でソートはできません。
limit		データの出力件数	数値	10	最小値：1 最大値：100	住所データの出力数
offset		データの出力開始位置	数値	0	最小値：0 最大値：5000	何件目から表示されるか(1件目が0)を指定します
options		追加出力情報	文字列		exact_coord：建物到着地点	追加で出力する情報 ※D2Dオプション申込時のみ利用可能 (APIマーケットでは利用不可)
lang		言語	文字列		ja: 日本語 en: 英語 ko: 韓国語 zh-CN: 中国語(簡体字) zh-TW: 中国語(繁体字) th: タイ語	出力する言語を指定します・ピリオド区切りで複数指定可能 ※多言語オプション申込時のみ利用可能 (APIマーケットでは利用不可)
datum		緯度経度の測地系	文字列	wgs84	wgs84：世界測地系 tokyo：旧日本測地系
coord_unit		出力データに含まれる緯度経度の単位	文字列	degree	degree：度表記の10進法 millisec：ミリ秒表記
search_old		旧住所検索の有無	真偽値	false	true：検索対象に旧住所を含める false：検索対象に旧住所を含めない	旧住所は2010年4月以降掲載の住所が対象となります。 word指定時のみ有効
sort_latest		旧住所を含む検索時のソート順	真偽値	true	true：最新住所>旧住所の順でソートする false：必ずしも最新住所が上位にならず、旧住所が上位に返却され得る	search_old=true指定時のみ有効

住所検索APIに設定する検索文字列の指定内容について

下記を推奨しています。
・住所を示す部分に「スペース」を含まない
・建物名称が含まれる場合は、住所と建物名称との間にのみ「スペース」を入れる
住所を示す部分に「スペース」がある、住所と建物名が連続している、などの場合、意図しない検索結果となる場合があります。

推奨例) 東京都港区南青山3-8-38
非推奨例) 東京都港区　南青山　3-8-38

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

・多言語に対応したレスポンスはMultilingualオブジェクトとして出力されることにご注意ください。
・wordパラメータの言語はlangパラメータの一番最初に指定する言語と一致する必要があります。
例)lang=en.jaと指定した場合、wordパラメータに指定する言語は英語

パラメータ構成例

検索ワード「代々木」で10件検索

/address?word=代々木

レスポンス

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

Countオブジェクト

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

Addressオブジェクト

名称	レスポンス名	型名	配列	Nullable	説明
住所コード	code	文字列		nullable	旧住所の場合は返却されません
住所テキスト	name	文字列/Multilingualオブジェクト			langパラメータ指定時は、Multilingualオブジェクトで出力
郵便番号	postal_code	文字列		nullable
住所の緯度経度	coord	Coordinateオブジェクト
建物到着地点の緯度経度	exact_coord	Coordinateオブジェクト	○	nullable	パラメータ「options=exact_coord」指定時かつデータが存在する場合のみ出力
レベル別の住所情報	details	AddressDetailオブジェクト	○
住所階層終端フラグ	is_end	真偽値		nullable	住所階層の深さが最下であることを表すフラグ以下のいずれかが返却される true：詳細な住所は存在しない false：詳細な住所が存在するデータが存在する場合のみ出力
旧住所フラグ	is_old	真偽値		nullable	古い住所かどうかを表すフラグ以下のいずれかが返却される true：旧住所 false：最新版の住所 search_old=trueを指定した場合のみ返却される旧住所の場合、住所コードは出力しない

Coordinateオブジェクト

名称	レスポンス名	型名	配列	Nullable	説明
各地点の代表緯度	lat	数値
各地点の代表経度	lon	数値

AddressDetailオブジェクト

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

Multilingualオブジェクト

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

住所情報が存在した場合のlangパラメータ指定言語の返却について

langパラメータの中に'ja'が含まれていた場合'ja'の値は必ず返却されます。
他の言語についてはデータが存在した場合に返却されます。

Unitオブジェクト

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

レスポンス例

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

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

{
    "count": {
        "total": 2282,
        "offset": 0,
        "limit": 10
    },
    "items": [
        {
            "code": "13113031000",
            "name": {
                "en": "Tokyo Shibuya Yoyogi",
                "ja": "東京都渋谷区代々木",
                "ko": "도쿄도시부야구요요기"
            },
            "postal_code": "1510053",
            "coord": {
                "lat": 35.682372,
                "lon": 139.698866
            },
            "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"
                }
            ],
            "is_end": false
        },
        {
            ・・・
        }
    ],
    "unit": {
        "datum": "wgs84",
        "coord_unit": "degree"
    }
}

エラー情報

エラーハンドリングについて

エラーメッセージは追加/変更/削除されることがあります。
エラーハンドリングされる場合はHTTPステータスコードをもとにご対応ください。
共通エラーについてはこちらをご参照ください。

HTTPステータス	エラーメッセージ	発生理由
405	This http method is invalid : POST (等)	許可されていないHTTPメソッドでアクセスされた場合に発生します。
400	parameter error: word: ['required field']	必須パラメータである word と code のいずれも指定されていない場合に発生します。
400	parameter error: word: ['empty values not allowed']	word が空文字で指定された場合に発生します。
400	parameter error: word: ["'code' must not be present with 'word'"], code: ["'word' must not be present with 'code'"]	word と code を同時に指定した場合に発生します。
400	parameter error: code: required field	必須パラメータである word と code のいずれも指定されていない場合に発生します（code 側に required field エラーが出力されます）。
400	parameter error: code: ['an invalid code: {value}']	code に不正な住所コードを指定した場合に発生します（英数字のみで桁数が 2, 5, 8, 11, 16, 21, 26 のいずれかである必要があります）。
400	parameter error: code: ["'word' must not be present with 'code'", "'level_to' must not be present with 'code'", "'level_from' must not be present with 'code'", "'address_filter' must not be present with 'code'"] （等、excludes指定による組合せ）	code と word, level_to, level_from, address_filter のいずれかを同時に指定した場合に発生します。
400	parameter error: address_filter: ['an invalid address filter: {value}']	address_filter にピリオド区切りで不正な住所フィルタコードを指定した場合に発生します（各コードは先頭のハイフン任意＋英数字で構成）。
400	parameter error: address_filter: ['an invalid address code: {value}']	address_filter のコード部分の桁数が 0, 2, 5, 8, 11, 16, 21, 26 のいずれにも該当しない場合に発生します。
400	parameter error: level_to: ["field 'level_to' cannot be coerced: {value}"]	level_to に整数に変換できない文字列を指定した場合に発生します。
400	parameter error: level_to: ['min value is 1'] または level_to: ['max value is 7']	level_to に下限値（1未満）や上限値（7超過）の範囲外の値を指定した場合に発生します。
400	parameter error: level_from: ["field 'level_from' cannot be coerced: {value}"]	level_from に整数に変換できない文字列を指定した場合に発生します。
400	parameter error: level_from: ['min value is 1'] または level_from: ['max value is 7']	level_from に下限値（1未満）や上限値（7超過）の範囲外の値を指定した場合に発生します。
400	parameter error: kana_row: ['unallowed value {value}']	kana_row に a, k, s, t, n, h, m, y, r, w 以外の不正な値を指定した場合に発生します。
400	parameter error: kana_row: ["field 'code' is required"]	kana_row を指定しているが、code が指定されていない場合に発生します。
400	parameter error: sort: ['unallowed value {value}']	sort に lexical, level_asc, code_asc 以外の不正な値を指定した場合に発生します。
400	parameter error: limit: ["field 'limit' cannot be coerced: {value}"]	limit に整数に変換できない文字列を指定した場合に発生します。
400	parameter error: limit: ['min value is 1'] または limit: ['max value is 100']	limit に下限値（1未満）や上限値（100超過）の範囲外の値を指定した場合に発生します。
400	parameter error: offset: ["field 'offset' cannot be coerced: {value}"]	offset に整数に変換できない文字列を指定した場合に発生します。
400	parameter error: offset: ['min value is 0'] または offset: ['max value is 5000']	offset に下限値（0未満）や上限値（5000超過）の範囲外の値を指定した場合に発生します。
400	parameter error: options: ['unallowed value {value}']	options に exact_coord 以外の不正な値を指定した場合に発生します。
400	parameter error: datum: ['unallowed value {value}']	datum に wgs84, tokyo 以外の不正な値を指定した場合に発生します。
400	parameter error: coord_unit: ['unallowed value {value}']	coord_unit に degree, millisec 以外の不正な値を指定した場合に発生します。
400	parameter error: lang: ['an invalid item: {value}']	lang にピリオド区切りで ja, en, ko, zh-CN, zh-TW, th 以外の不正な値を指定した場合に発生します。
400	parameter error: search_old: ['unallowed value {value}']	search_old に true, false 以外の不正な値を指定した場合に発生します。
400	parameter error: search_old: ["field 'word' is required"]	search_old を指定しているが、word が指定されていない場合に発生します。
400	parameter error: sort_latest: ['unallowed value {value}']	sort_latest に true, false 以外の不正な値を指定した場合に発生します。
400	parameter error: sort_latest: ["field 'search_old' is required"]	sort_latest を指定しているが、search_old が指定されていない場合に発生します。
400	invalid combination (level_to, level_from)	level_to と level_from の両方を指定し、level_to の値が level_from の値より小さい場合に発生します。
400	bad usage on this contract　:　D2D address	options に exact_coord を指定したが、契約で D2D address オプションが有効化されていない場合に発生します。
400	bad usage on this contract　:　Multilingual	lang パラメータを指定したが、契約で多言語オプションが有効化されていない場合に発生します。