楽天トラベル空室検索APIは、(楽天トラベル地区コードAPIから得られる)地区コード、緯度経度、施設番号などから予約可能な部屋を検索することができます。デベロッパーは、リアルタイムな空室情報を得ることができます。
リクエストURL
https://app.rakuten.co.jp/services/api/Travel/VacantHotelSearch/20170426?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallbackを指定することで出力されます。
たとえば、以下の3つのような場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)
https://app.rakuten.co.jp/services/api/Travel/VacantHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&largeClassCode=japan
&middleClassCode=akita
&smallClassCode=tazawa
&checkinDate=2013-12-01
&checkoutDate=2013-12-02
&adultNum=2
(2) 2013年12月1日で東京駅の半径1Km圏内において、大人1名が1泊できる宿を検索する場合
https://app.rakuten.co.jp/services/api/Travel/VacantHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&checkinDate=2013-12-01
&checkoutDate=2013-12-02
&latitude=128440.51
&longitude=503172.21
&searchRadius=1
(3) 2013年12月1日に大人1名が8,500円以下で施設番号123456のホテルに1泊できるかどうかを検索する場合
https://app.rakuten.co.jp/services/api/Travel/VacantHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&hotelNo=123456
&checkinDate=2013-12-01
&checkoutDate=2013-12-02
&maxCharge=8500
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天トラベル空室検索API(VacantHotelSearch) 入力パラメータ version:2017-04-26
ID | 項目名 | パラメーター | 型(括弧内は最大バイト数) | 必須 | デフォルト | 備考 |
---|---|---|---|---|---|---|
区分:共通パラメーター | ||||||
1 | アプリID | applicationId | String | - | こちらで確認できます | |
2 | アフィリエイトID | affiliateId | String | - | 指定無し | こちらで確認できます |
3 | レスポンス形式 | format | String | - | json | json か xml を選択することができます。 json を選択した場合、 callback パラメーター指定により jsonp 形式にすることもできます。 |
4 | コールバック関数名 | callback | String | - | 指定無し | JSONPとして出力する際のコールバック関数名 (UTF-8でURLエンコードした文字列) 英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上 |
5 | 出力パラメーター指定 | elements | String | - | ALL |
カンマ区切りで、必要な出力パラメータを指定した場合、 指定された出力パラメータのみを返却します。 (例)elements=reviewCount,reviewAverage |
6 | 出力フォーマットバージョン | formatVersion | int | - | 1 |
出力フォーマットのバージョン指定です。 2 を指定すると、JSONの出力方法が改善され以下のようになります。
{"items": [ {"item": { "itemName": "a", "itemPrice": 10 }}, {"item": { "itemName": "b", "itemPrice": 20 }} ]}
{"items": [ { "itemName": "a", "itemPrice": 10 }, { "itemName": "b", "itemPrice": 20 } ]} |
区分:共通パラメーター | ||||||
1 | 大区分コード | largeClassCode | String | (*1) (*2) |
- | 国などを示すコード。地区コード一覧は地区コードAPI(GetAreaClass)
より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。 複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
2 | 中区分コード | middleClassCode | String | (*1) (*2) |
- | 都道府県などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。 複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
3 | 小区分コード | smallClassCode | String | (*1) (*2) |
- | 市など示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。 複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
4 | 細区分コード | detailClassCode | String | (*1) (*2) |
- | 駅や詳細地域などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。 複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
5 | 施設番号 | hotelNo | int(10) | (*1) |
- |
楽天トラベルにおける施設を特定するためのNo (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。 複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 このフィールドは15個まで指定することができます。 例)&hotelNo=12345,54321 |
6 | チェックイン年月日 | checkinDate | date | 本日日付 | YYYY-MM-DD (*1)デフォルト値は、 チェックイン年月日およびチェックアウト年月日の両方が指定されなかった場合にのみ適用されます。 |
|
7 | チェックアウト年月日 | checkoutDate | date | 明日日付 | YYYY-MM-DD (*1)デフォルト値は、 チェックイン年月日およびチェックアウト年月日の両方が指定されなかった場合にのみ適用されます。 |
|
8 | 人数(大人) | adultNum | int(2) | - | 1 | 1以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
9 | 人数(小学生高学年) | upClassNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
10 | 人数(小学生低学年) | lowClassNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
11 | 人数(幼児(食事・布団付)) | infantWithMBNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
12 | 人数(幼児(食事のみ)) | infantWithMNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
13 | 人数(幼児(布団のみ)) | infantWithBNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
14 | 人数(幼児(食事・布団不要)) | infantWithoutMBNum | int(2) | - | 0 | 0以上、99以下の整数であること。 8~14番の各人数の合計を99人以下にする必要があります。 |
15 | 部屋数 | roomNum | int(2) | - | 1 | 1以上、10以下の整数であること。 |
16 | 上限金額 | maxCharge | long | - | 指定無し | 0以上、999999999以下の整数であること。 |
17 | 下限金額 | minCharge | long | - | 指定無し | 0以上、999999999以下の整数であること。 maxChargeはminChargeより大きい必要がある |
18 | 緯度 | latitude | decimal | (*1) |
- | 日本測地系(Tokyo Datum)、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。 例)128216.17 ただし、datumTypeに1を指定した場合は、 世界測地系、単位は度で指定すること。 例)35.6065914 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 |
19 | 経度 | longitude | decimal | (*1) |
- | 日本測地系(Tokyo Datum)、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。 例)503259.29 ただし、datumTypeに1を指定した場合は、 世界測地系、単位は度で指定すること。 例)139.7513225 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 |
20 | 検索半径 | searchRadius | int | - | 1 | 緯度経度検索時の検索半径(単位km) 0.1以上、3.0以下であり、小数点以下は1桁までであること |
21 | 絞込み条件 | squeezeCondition | String | - | - | kinen:禁煙ルーム internet:インターネットが出来る部屋 daiyoku:大浴場あり onsen:温泉 breakfast:朝食あり dinner:夕食あり このフィールドは複数指定することができます。 例)禁煙ルームのある温泉宿 &squeezeCondition= kinen,onsen |
22 | キャリア情報 | carrier | int(1) | - | 0 | PC/スマートフォン用の情報を返すのか、フィーチャーフォン用の情報を返すのかを選択 0:PC/スマートフォン 1:フィーチャーフォン |
23 | 緯度経度タイプ | datumType | int(1) | - | 2 | 入力及び出力パラメータの緯度経度タイプを指定する。 1:世界測地系、単位は度。 2:日本測地系、単位は秒。 |
24 | 1ページあたりの取得件数 | hits | int | - | 30 | 1ページ毎の取得件数を制限するパラメータ。(*1) ■searchPatternに0を指定した場合(施設ごと検索)■ 1ページ毎の取得施設件数を制限する。 1以上、30以下の整数であること。 ■searchPatternに1を指定した場合(宿泊プランごと検索)■ 1ページ毎の取得プラン件数を制限する。 1以上、30以下の整数であること。 (*1)pageとhitsが指定されていた場合、allReturnFlagは無効になります。 |
25 | 取得ページ | page | int | - | 1 | 取得対象のページ数。 1以上、100以下の整数であること。(*1) (*1)pageとhitsが指定されていた場合、allReturnFlagは無効になります。 |
26 | 検索パターン | searchPattern | int | - | 0 | 検索パターンを指定するパラメータ 0:施設ごと 1:宿泊プランごと ■施設ごと■ 検索条件にあてはまる情報を施設単位で検索する。 ※提供されている宿泊プラン情報も 施設あたり最大3件まで同時に取得可能 ■宿泊プランごと■ 検索条件にあてはまる情報を宿泊プラン・客室単位で検索する。 |
27 | 施設画像サイズ | hotelThumbnailSize | int(1) | - | 2 | 出力パラメータの施設画像サムネイルURLの画像サイズを指定する。 1:小 2:中 3:大 |
28 | 返却情報タイプ | responseType | String | - | small | 出力パラメータの返却情報タイプを指定する。 small:最低限の情報のみ middle:中くらい large:すべての情報 |
29 | ソート | sort | String | - | standard | standard:おすすめ順 +roomCharge:料金が安い順 -roomCharge:料金が高い順 |
30 | 全件返却フラグ | allReturnFlag | int(1) | - | - | 条件に該当する情報を全件返却するフラグ。(*1)(*2) 1:全件返却 (*1)緯度経度検索で、responseTypeがsmall、searchPatternが0のときのみ有効。 (*2)pageとhitsが指定されていた場合、allReturnFlagは無効になります。 |
出力パラメーター
楽天トラベル空室検索API(VacantHotelSearch) 出力パラメータ version:2017-04-26
ID | 大分類 | 分類 | small | middle | large | 項目名 | パラメーター | 備考 |
---|---|---|---|---|---|---|---|---|
1 | 全体情報 pagingInfo |
検索数 | recordCount | 検索結果の総レコード件数 | ||||
2 | 総ページ数 | pageCount | 最大100 | |||||
3 | ページ番号 | page | 現在のページ番号 | |||||
4 | ページ内結果開始番号 | first | 検索結果の何件目からか | |||||
5 | ページ内施設終追番 | last | 検索結果の何件目までか | |||||
1 | 施設情報 "<hotels> ~ </hotels>" 内に複数の"<hotel> ~ </hotel>" が表示される |
施設基本情報 hotelBasicInfo |
施設番号 | hotelNo | ||||
2 | 施設名称 | hotelName | ||||||
3 | 施設情報ページURL | hotelInformationUrl | 入力パラメーターにアフィリエイトIDが含まれていた場合、httpsではじまるアフィリエイトURLとなります。(*1) (*1)「ダイナミックパッケージ宿泊プラン一覧ページURL」「お客さまの声ページURL」はcarrierがPCの時のみ返却されます。 |
|||||
4 | 宿泊プラン一覧ページURL | planListUrl | ||||||
5 | ダイナミックパッケージ 宿泊プラン一覧ページURL |
dpPlanListUrl | ||||||
6 | お客様の声ページURL | reviewUrl | ||||||
7 | 施設かな名称 | hotelKanaName | ||||||
8 | 施設特色 | hotelSpecial | ||||||
9 | 最安料金 | hotelMinCharge | 1部屋1泊あたり、税・サービス料込みの最安値の目安 | |||||
10 | 緯度 | latitude | datumType=1の場合:世界測地系(WGS)、単位は度 datumType=2の場合:日本測地系(Tokyo Datum)、単位は秒、小数点以下がミリ秒 |
|||||
11 | 経度 | longitude | datumType=1の場合:世界測地系(WGS)、単位は度 datumType=2の場合:日本測地系(Tokyo Datum)、単位は秒、小数点以下がミリ秒 |
|||||
12 | 郵便番号 | postalCode | ||||||
13 | 住所1 | address1 | ||||||
14 | 住所2 | address2 | ||||||
15 | 施設電話番号 | telephoneNo | ||||||
16 | ファックス番号 | faxNo | ||||||
17 | 施設へのアクセス | access | ||||||
18 | 駐車場情報 | parkingInformation | ||||||
19 | 最寄駅名称 | nearestStation | ||||||
20 | 施設画像URL | hotelImageUrl | httpsではじまるお客様の声ページURLとなります | |||||
21 | 施設画像サムネイルURL | hotelThumbnailUrl | httpsではじまる施設画像URLとなります | |||||
22 | 部屋画像URL | roomImageUrl | httpsではじまる部屋画像URLとなります | |||||
23 | 部屋画像サムネイルURL | roomThumbnailUrl | httpsではじまる部屋画像サムネイルURLとなります | |||||
24 | 施設提供地図画像URL | hotelMapImageUrl | httpsではじまる施設提供地図画像URLとなります | |||||
25 | 投稿件数 | reviewCount | ||||||
26 | ★の数(総合) | reviewAverage | ★の見方について | |||||
27 | お客さまの声(1件目) | userReview | お客さまの声の最新の1件目を表示します。 | |||||
28 | 施設詳細情報 hotelDetailInfo |
- | 宿泊予約センター電話番号 | reserveTelephoneNo | 楽天価格での予約が電話で可能です。 | |||
29 | 中区分コード | middleClassCode | 都道府県などを示すコード。 コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
|||||
30 | 小区分コード | smallClassCode | 都道府県などを示すコード。 コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
|||||
31 | 地区名 | areaName | ||||||
32 | ホテル種別コード | hotelClassCode | ||||||
33 | チェックイン時刻 | checkinTime | HH:MM | |||||
34 | チェックアウト時刻 | checkoutTime | HH:MM | |||||
35 | 最終チェックイン時刻 | lastCheckinTime | HH:MM | |||||
36 | 施設予約関連 hotelReserveInfo |
- | レコード件数 (予約候補) | reserveRecordCount | ||||
37 | 予約候補内最安値 | lowestCharge | 大人1名料金の最安値 | |||||
38 | 予約候補内最高値 | highestCharge | 大人1名料金の最高値 | |||||
39 | 部屋基本情報 roomBasicInfo |
部屋種別 | roomClass | |||||
40 | 部屋名称 | roomName | ||||||
41 | プランID | planId | salesformFlagが0,2のときのみ返却されます。 | |||||
42 | プラン名称 | planName | ||||||
43 | 楽天ポイント付与率 | pointRate | 単位% | |||||
44 | 夕食有無フラグ | withDinnerFlag | 0:夕食無し 1:夕食有り |
|||||
45 | 夕食選択フラグ | dinnerSelectFlag | 0:夕食選択不可 1:夕食選択可 |
|||||
46 | 朝食有無フラグ | withBreakfastFlag | 0:朝食無し 1:朝食有り |
|||||
47 | 朝食選択フラグ | breakfastSelectFlag | 0:朝食選択不可 1:朝食選択可 |
|||||
48 | 決済方法 | payment | 0:現金 1:クレジットカード / 現金 2:クレジットカード |
|||||
49 | 予約ページURL | reserveUrl | アフィリエイトIDが設定されている場合、httpsではじまるアフィリエイトURLとなります。 (入力パラメーターにアフィリエイトIDが含まれていた時のみ) |
|||||
50 | 販売形式フラグ | salesformFlag | 0:プラン 1:部屋 2:当日限定プラン |
|||||
51 | - | - | プラン内容 | planContents | salesformFlagが0,2のときのみ返却されます。 | |||
52 | 分類:料金情報(1泊目のみ) dailyCharge |
宿泊年月日 | stayDate | YYYY-MM-DD | ||||
53 | 楽天料金 | rakutenCharge | 宿泊年月日1泊の料金です。 ■chargeFlagが0のとき■ 1人あたりの料金 ■chargeFlagが1のとき■ 1室あたりの料金 |
|||||
54 | 合計料金 | total | 宿泊年月日1泊の合計料金です。 | |||||
55 | 料金単位フラグ | chargeFlag | 0:1人あたりの料金(円/人) 1:1室あたりの料金(円/室) |
アフィリエイトに関して
デベロッパーは、楽天商品検索APIから取得した商品情報からアフィリエイトURLを作成することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。
アフィリエイトURLを作るには、APIの入力パラメーターに「アフィリエイトID」を含めてリクエストしてください。APIの出力に「アフィリエイトURL」が含まれます。
入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。(2008年11月現在)
エラー
エラー内容はHTTPステータスコードとレスポンスボディから判断できます。
HTTPステータスコード | 意味 | レスポンスボディ例 (JSON) |
---|---|---|
400 | パラメーターエラー (必須パラメータ不足) |
applicationId を指定しなかった場合
keyword が正しい値でなかった時。(半角1文字のみ指定など)
|
404 | 対象のデータが存在しなかった場合 |
|
429 | リクエスト過多 (各ユーザ制限値超過) |
APIリクエスト数が上限に達した場合のエラーです。しばらく時間を空けてから、ご利用ください。
|
500 | 楽天ウェブサービス内のエラー | システムエラー。長時間続くようであれば、こちらよりごお問い合わせください。
|
503 | メンテナンス・リクエスト過多 (全ユーザ制限値超過) |
メンテナンス (XXX/XXX にはAPI名が入る)
|
レスポンスボディの形式は format に従います。
format | エラー出力例 |
---|---|
json |
|
xml |
|