サジェスト

API名: 

suggest/word

概要: 

指定されるフリーワードに該当するサジェストデータを返却します。
クエリパラメータの指定により一覧データと詳細データのどちらを取得するのかを選択できます。

※この機能を利用するには別途契約が必要です。

各出力データについて:
データ 説明
ジャンルデータ ジャンル名称とジャンルコードが格納されています。
駅データ ジョルダン社より提供の駅データが格納されています。
施設データ 独自に作成したスコア値を施設データに付与した、
各ジャンルの上位1500件のPOIデータが格納されています。
ただし次のデータは除きます。
ジャンルコードの区分「車・交通/高速道路」のうち「IC」、「出口」、「出入口」に該当するもの
名称が「駅」で終わるものかつ以下のもの
 - ジャンルコードの区分「レジャー/その他」のうち「待ち合わせ場所」に該当するもの
 - ジャンルコードの区分「レジャー/観光スポット」のうち「名所・観光地等」に該当するもの
住所データ 都道府県、市区町村、大字までの住所データが格納されています

URI: 

https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word

<API使用例　一覧データ取得>

https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&word=温泉&genre_cnt=3&station_cnt=3&poi_cnt=3&address_cnt=3

<API使用例　詳細データ取得>
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&sid=xxxx

リクエストパラメータ

■一覧データ取得時

パラメータ 必須 デフォルト値 説明
word 〇 - 検索ワード
検索語句を指定します。検索語句の上限は512文字です。
本パラメータを指定すると、該当するサジェスト一覧データ
(一覧データ表示テキストとそのサジェスト詳細データを取得するためのサジェストIDリスト)が返却されます。
datum   - 測地系
返却される住所代表点の測地系を指定します。

【ジャンルデータ用パラメータ】

パラメータ 必須 デフォルト値 説明
genre_cnt   20 検索結果取得件数
検索結果取得件数 0 ~ 100 を指定します。
0 を指定した場合はgenre.itemが空配列となります。
genre_searchtype   partial 検索タイプ
検索タイプを指定します。
partial 部分一致
forward 前方一致検索
genre_sort   dispnum 出力順
ジャンルデータの出力順を指定します。
デフォルトは昇順で、降順指定の場合、ソートキーの前方にマイナス（-）を付加します。
dispnum 標準の並び順

【駅データ用パラメータ】

パラメータ 必須 デフォルト値 説明
station_cnt   20 検索結果取得件数
検索結果取得件数 0 ~ 100 を指定します。
0 を指定した場合はstation.itemが空配列となります。
station_searchtype   partial 検索タイプ
検索タイプを指定します。
partial 部分一致
forward 前方一致検索
station_sort   nm 出力順
駅データの出力順を指定します。
デフォルトは昇順で、降順指定の場合、ソートキーの前方にマイナス（-）を付加します。
nm 駅名称
kn 駅名称カナ
linecnt 乗り入れ路線数

【施設データ用パラメータ】

パラメータ 必須 デフォルト値 説明
poi_cnt   20 検索結果取得件数
検索結果取得件数 0 ~ 100 を指定します。
0 を指定した場合はpoi.itemが空配列となります。
poi_searchtype   partial 検索タイプ
検索タイプを指定します。
partial 部分一致
forward 前方一致検索
poi_sort   -pscore 出力順
施設データの出力順を指定します。
デフォルトは昇順で、降順指定の場合、ソートキーの前方にマイナス（-）を付加します。
nm 施設名称
kn 施設名称カナ

【住所データ用パラメータ（大字までのデータ）】

パラメータ 必須 デフォルト値 説明
address_cnt   20 検索結果取得件数
検索結果取得件数 0 ~ 100 を指定します。
0 を指定した場合はaddress.itemが空配列となります。
address_searchtype   partial 検索タイプ
検索タイプを指定します。
partial 部分一致
forward 前方一致検索
address_sort   mod_code 出力順
ジャンルデータの出力順を指定します。
デフォルトは昇順で、降順指定の場合、ソートキーの前方にマイナス（-）を付加します。
mod_code 調整済み住所コード
※通常の住所コード順でのソートを行うと都道府県順に並べられるため、下記のように
　　「広島」で検索すると広島県広島市より上位に北海道北広島市が表示される
　　「横浜」で検索すると神奈川県横浜市より上位に青森県横浜町が表示される
といった直感的でないソートになります。
このような問題を解決するため、調整を行った住所コード順に並べるソート方式です。
nm 住所名称
kn 住所名称カナ
code 住所コード

 
■詳細データ取得時

パラメータ 必須 デフォルト値 説明
sid 〇 - サジェストID
本パラメータを指定すると、サジェストIDが示す対象のサジェスト詳細データを取得します。
sidはクエリパラメータwordを指定して別途リクエストして得たサジェスト一覧データから取得できます。
なおsidには有効期限が設定されています。期限を超えたsidを指定した場合はデータは返却されません。
datum   - 測地系
返却される住所代表点の測地系を指定します。

出力データ

出力フォーマット

{"status": {"code": "OK",
            "text": "正常終了"},
 "result": {"genre": {"info": {"hit": 1},
                      "item": [{"text": "レジャー/温泉・スパ",
                                "sid": 216字の文字列
                              }]},
            "station": {"info": {"hit": 3},
                                 "item": [{"text": "あつみ温泉駅",
                                           "sid": 216字の文字列},
                                          {"text": "あわくら温泉駅",
                                           "sid": 216字の文字列},
                                          {"text": "おごと温泉駅",
                                           "sid": 216字の文字列}]},
            "poi": {"info": {"hit": 3},
                    "item": [{"text": "いやしの温泉郷",
                              "sid": 216字の文字列},
                             {"text": "ことひら温泉琴参閣",
                              "sid": 216字の文字列},
                             {"text": "ながぬま温泉",
                              "sid": 216字の文字列}]},
            "address": {"info": {"hit": 3},
                        "item": [{"text": "兵庫県美方郡新温泉町",
                                  "sid": 216字の文字列},
                                 {"text": "長野県下高井郡野沢温泉村",
                                  "sid": 216字の文字列},
                                 {"text": "山形県山形市蔵王温泉",
                                  "sid": 216字の文字列}]}}}

■wordパラメータ指定時(一覧データ取得)

キー名 データ型 説明
status       object ステータス情報が入ります。
  code     string ステータスコードが入ります。
OK 正常終了
ERR_FORCED_TERMINATION タイムアウトが発生またはデータサイズが制限値を超えたため処理が中断された
  text     string ステータス内容に関するテキスト情報が入ります。
result       object 検索結果の情報が入ります。
  genre     object ジャンルデータの結果が入ります。
    info   object 検索結果の情報が入ります。
      hit number 検索結果総数が入ります。
    item   array 検索結果の配列となります。
検索結果が0件の場合、クエリパラメータ genre_cnt に 0 を指定した場合は
空の配列となります。
      text string ジャンル名称が入ります。
      sid string 詳細データ(ジャンル)を取得するためのサジェストIDが入ります。
  station     object 駅データの結果が入ります。
    info   object 検索結果の情報が入ります。
      hit number 検索結果総数が入ります。
    item   array 検索結果の配列となります。
検索結果が0件の場合、クエリパラメータ station_cnt に 0 を指定した場合は
空の配列となります。
      text string 駅名称が入ります。
      sid string 詳細データ(駅)を取得するためのサジェストIDが入ります。
  poi     object 施設データの結果が入ります。
    info   object 検索結果の情報が入ります。
      hit number 検索結果総数が入ります。
    item   array 検索結果の配列となります。
検索結果が0件の場合、クエリパラメータ poi_cnt に 0 を指定した場合は
空の配列となります。
      text string 施設名称が入ります。
      sid string 詳細データ(施設)を取得するためのサジェストIDが入ります。
  address     object 住所データの結果が入ります。
    info   object 検索結果の情報が入ります。
      hit number 検索結果総数が入ります。
    item   array 検索結果の配列となります。
検索結果が0件の場合、クエリパラメータ address_cnt に 0 を指定した場合は
空の配列となります。
      text string 住所名称が入ります。
      sid string 詳細データ(住所)を取得するためのサジェストIDが入ります。

出力例

[通常出力例 一覧データ取得]

https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&word=温泉&genre_cnt=3&station_cnt=3&poi_cnt=3&address_cnt=3
{"status": {"code": "OK",
            "text": "正常終了"},
 "result": {"genre": {"info": {"hit": 1},
                      "item": [{"text": "レジャー/温泉・スパ",
                                "sid": 216字の文字列
                              }]},
            "station": {"info": {"hit": 3},
                                 "item": [{"text": "あつみ温泉駅",
                                           "sid": 216字の文字列},
                                          {"text": "あわくら温泉駅",
                                           "sid": 216字の文字列},
                                          {"text": "おごと温泉駅",
                                           "sid": 216字の文字列}]},
            "poi": {"info": {"hit": 3},
                    "item": [{"text": "いやしの温泉郷",
                              "sid": 216字の文字列},
                             {"text": "ことひら温泉琴参閣",
                              "sid": 216字の文字列},
                             {"text": "ながぬま温泉",
                              "sid": 216字の文字列}]},
            "address": {"info": {"hit": 3},
                        "item": [{"text": "兵庫県美方郡新温泉町",
                                  "sid": 216字の文字列},
                                 {"text": "長野県下高井郡野沢温泉村",
                                  "sid": 216字の文字列},
                                 {"text": "山形県山形市蔵王温泉",
                                  "sid": 216字の文字列}]}}}

[検索失敗の例　wordパラメータ指定で検索結果が0件]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&word=xxxx

{"status":{"code":"OK",
           "text":"正常終了"},
 "result":{"genre":{"info":{"hit":0},
                    "item":[]},
           "station":{"info":{"hit":0},
                      "item":[]},
           "poi":{"info":{"hit":0},
                  "item":[]}
           "address":{"info":{"hit":0},
                      "item":[]}}

■sidパラメータ指定時(詳細データ取得)
データ種別(ジャンル、駅、施設、住所)ごとに返却フォーマットが異なります。
【ジャンルデータ】

キー名 データ型 説明
status     object ステータス情報が入ります。
  code   string ステータスコードが入ります。
OK 正常終了
ERR_SID_EXPIRE サジェストIDの有効期限切れエラー
ERR_INVALID_SID 不正なサジェストID指定エラー
  text   string ステータス内容に関するテキスト情報が入ります。
result     object 指定したサジェストIDに対応する詳細データが入ります。
status.code が"OK"以外の場合は null となります。
  type   string データの種別が入ります。
ジャンルデータのサジェストID指定の場合は"genre"固定となります。
  data   object 指定したサジェストIDに対応する詳細データ(ジャンル)が入ります。
    code string ジャンルコードが入ります。
    text string ジャンル名称が入ります。
【駅データ】
キー名 データ型 説明
status     object ステータス情報が入ります。
  code   string ステータスコードが入ります。
OK 正常終了
ERR_SID_EXPIRE サジェストIDの有効期限切れエラー
ERR_INVALID_SID 不正なサジェストID指定エラー
  text   string ステータス内容に関するテキスト情報が入ります。
result     object 指定したサジェストIDに対応する詳細データが入ります。
status.code が"OK"以外の場合は null となります。
  type   string データの種別が入ります。
駅データのサジェストID指定の場合は"station"固定となります。
  data   object 指定したサジェストIDに対応する詳細データ(駅)が入ります。
    code string 駅施設コードが入ります。
    text string 駅名称が入ります。
    kana string 駅名称カナが入ります。
    addressText string 住所が入ります。
    phoneNumber string 電話番号
不明の場合 null となります。
    point string 代表点緯度経度が入ります。

【施設データ】

キー名 データ型 説明
status     object ステータス情報が入ります。
  code   string ステータスコードが入ります。
OK 正常終了
ERR_SID_EXPIRE サジェストIDの有効期限切れエラー
ERR_INVALID_SID 不正なサジェストID指定エラー
  text   string ステータス内容に関するテキスト情報が入ります。
result     object 指定したサジェストIDに対応する詳細データが入ります。
status.code が"OK"以外の場合は null となります。
  type   string データの種別が入ります。
施設データのサジェストID指定の場合は"poi"固定となります。
  data   object 指定したサジェストIDに対応する詳細データ(施設)が入ります。
    code string 施設コードが入ります。
    text string 施設名称が入ります。
    kana string 施設名称カナが入ります。
    addressText string 住所が入ります。
    phoneNumber string 電話番号
不明の場合 null となります。
    point string 代表点緯度経度が入ります。

【住所データ】

キー名 データ型 説明
status     object ステータス情報が入ります。
  code   string ステータスコードが入ります。
OK 正常終了
ERR_SID_EXPIRE サジェストIDの有効期限切れエラー
ERR_INVALID_SID 不正なサジェストID指定エラー
  text   string ステータス内容に関するテキスト情報が入ります。
result     object 指定したサジェストIDに対応する詳細データが入ります。
status.code が"OK"以外の場合は null となります。
  type   string データの種別が入ります。
住所データのサジェストID指定の場合は"address"固定となります。
  data   object 指定したサジェストIDに対応する詳細データ(住所)が入ります。
    code string 住所コードが入ります。
    text string 住所名称が入ります。
    kana string 住所名称カナが入ります。
    level string 住所レベルが入ります。
tod 都道府県
shk 市区町村
oaz 大字
    point string 代表点緯度経度が入ります。

出力例

[通常出力例 ジャンルデータのサジェストIDを指定した場合]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&sid=xxxx

{"status":{"code":"OK",
           "text":"正常終了"},
 "result":{"type": "genre",
           "data": {"code":"0012000160",
                    "text":"レジャー/温泉・スパ"}}}

[通常出力例 駅データのサジェストIDを指定した場合]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&sid=xxxx

{"status":{"code":"OK",
           "text":"正常終了"},
 "result":{"type": "station",
           "data": {"code":"5036",
                    "text":"おごと温泉駅",
                    "kana":"おごとおんせんえき",
                    "addressText":"滋賀県大津市雄琴北１丁目３－１２",
                    "phoneNumber":null,
                    "point":{"lat":35.0942272,
                             "lon":135.8978825}}}}

[通常出力例 施設データのサジェストIDを指定した場合]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&sid=xxxx

{"status":{"code":"OK",
           "text":"正常終了"},
 "result":{"type": "poi",
           "data": {"code":"00000000000002584450",
                    "text":"あまくさ温泉ホテル四季咲館",
                    "kana":"アマクサオンセンホテルシキサキカン",
                    "addressText":"熊本県天草郡苓北町富岡２４０３",
                    "phoneNumber":"0969-35-3533",
                    "point":{"lat":32.5186778,
                             "lon":130.0329306}}}}

[通常出力例 住所データのサジェストIDを指定した場合]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&sid=xxxx

{"status":{"code":"OK",
           "text":"正常終了"},
 "result":{"type": "address",
           "data": {"code":"06201098",
                    "text":"山形県山形市蔵王温泉",
                    "kana":"ヤマガタケンヤマガタシザオウオンセン",
                    "level":"oaz",
                    "point":{"lat":38.1644111,
                             "lon":140.3992167}}}}

[検索失敗の例　sidパラメータ指定で不正なsid]
https://test.core.its-mo.com/zmaps/api/apicore/core/v1_0/suggest/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&word=xxxx

{"status": {"code": "ERR_INVALID_SID",
　　　　　　　"text": "不正なサジェストID指定エラー"},
 "result": null}

Copyright(C) 2024 ZENRIN DataCom CO.,LTD. All Rights Reserved.