住所検索
/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指定時のみ有効 |
langパラメータの指定時の注意点
・多言語に対応したレスポンスはMultilingualオブジェクトとして出力されることにご注意ください。
・wordパラメータの言語はlangパラメータの一番最初に指定する言語と一致する必要があります。
例)lang=en.jaと指定した場合、wordパラメータに指定する言語は英語
パラメータ構成例
- 検索ワード「代々木」で10件検索
/address?word=代々木
レスポンス
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 検索数 | count | Countオブジェクト | レスポンスのヒット数などの情報 | |
| 住所情報 | items | Addressオブジェクト | ○ | 住所情報のまとまり |
| 単位情報 | unit | Unitオブジェクト | 出力される単位の情報 |
Countオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| トータルヒット件数 | total | 数値 | 検索ヒットした件数 | |
| オフセット値 | offset | 数値 | オフセットが設定されている場合はその値を出力 | |
| データの出力件数 | limit | 数値 | データの出力件数に設定されている値 1件しかヒットしなかった場合でも、limit=10でリクエストしている場合は10と出力 |
Addressオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 住所コード | code | 文字列 | 旧住所の場合は返却されません | |
| 住所テキスト | name | 文字列/Multilingualオブジェクト | langパラメータ指定時は、Multilingualオブジェクトで出力 | |
| 郵便番号 | postal_code | 文字列 | ||
| 住所の緯度経度 | coord | Coordinateオブジェクト | ||
| 建物到着地点の緯度経度 | exact_coord | Coordinateオブジェクト | ○ | パラメータ「options=exact_coord」指定時かつデータが存在する場合のみ出力 |
| レベル別の住所情報 | details | AddressDetailオブジェクト | ○ | |
| 住所階層終端フラグ | is_end | 真偽値 | 住所階層の深さが最下であることを表すフラグ 以下のいずれかが返却される true：詳細な住所は存在しない false：詳細な住所が存在する データが存在する場合のみ出力 |
|
| 旧住所フラグ | is_old | 真偽値 | 古い住所かどうかを表すフラグ 以下のいずれかが返却される true：旧住所 false：最新版の住所 search_old=trueを指定した場合のみ返却される 旧住所の場合、住所コードは出力しない |
Coordinateオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 各地点の代表緯度 | lat | 数値 | ||
| 各地点の代表経度 | lon | 数値 |
AddressDetailオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 対象レベルまでの住所コード | code | 文字列 | ||
| 対象レベルの住所テキスト | name | 文字列/Multilingualオブジェクト | langパラメータ指定時は、Multilingualオブジェクトで出力 | |
| 対象レベルの住所テキストのふりがな | ruby | 文字列 | 多言語出力指定時も日本語で出力 | |
| 住所のレベル | level | 文字列 | 住所レベル 1: 都道府県 2: 市区町村 3: 大字・町 4: 小字・丁目 5: 街区 6: 地番 7: 枝番 |
Multilingualオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 英語名称 | en | 文字列 | ||
| 日本語名称 | ja | 文字列 | ||
| 韓国語名称 | ko | 文字列 | ||
| タイ語名称 | th | 文字列 | ||
| 中国語(簡体字)名称 | zh-CN | 文字列 | ||
| 中国語(繁体字)名称 | zh-TW | 文字列 |
Unitオブジェクト
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| 測地系 | 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"
}
}