ホーム      API一覧     楽天トラベル空室検索API

楽天トラベル空室検索APIは、(楽天トラベル地区コードAPIから得られる)地区コード、緯度経度、施設番号などから予約可能な部屋を検索することができます。デベロッパーは、リアルタイムな空室情報を得ることができます。

リクエストURL


https://app.rakuten.co.jp/services/api/Travel/VacantHotelSearch/20170426?[parameter]=[value]…

※JSONP形式は、JSON形式で入力パラメーターにcallbackを指定することで出力されます。

たとえば、以下の3つのような場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)

(1) 2013年12月1日の田沢湖で、大人2名1室で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の出力方法が改善され以下のようになります。

formatVersion=1 の場合:
配列データに関して、以下の様にデータが返ります。
したがって、最初の itemName にアクセスするためにitems[0].item.itemNameとたどる必要があります。

{"items": [
    {"item": {
        "itemName": "a",
        "itemPrice": 10
    }},
    {"item": {
        "itemName": "b",
        "itemPrice": 20
    }}
]}

formatVersion=2 の場合:
下記のように、配列中の重複するオブジェクトが省略されます。
最初の itemName にアクセスするためにitems[0].itemNameでアクセスできます。

{"items": [
    {
        "itemName": "a",
        "itemPrice": 10
    },
    {
        "itemName": "b",
        "itemPrice": 20
    }
]}
区分:共通パラメーター
1 大区分コード largeClassCode String Affiliate対応あり
(*1)
(*2)
- 国などを示すコード。地区コード一覧は地区コードAPI(GetAreaClass) より取得してください。
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。
複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。
(*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
2 中区分コード middleClassCode String Affiliate対応あり
(*1)
(*2)
- 都道府県などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。
複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。
(*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
3 小区分コード smallClassCode String Affiliate対応あり
(*1)
(*2)
- 市など示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。
複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。
(*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
4 細区分コード detailClassCode String Affiliate対応あり
(*1)
(*2)
- 駅や詳細地域などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。
複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。
(*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
5 施設番号 hotelNo int(10) Affiliate対応あり
(*1)
- 楽天トラベルにおける施設を特定するためのNo
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。
複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。

このフィールドは15個まで指定することができます。
例)&hotelNo=12345,54321
6 チェックイン年月日 checkinDate date Affiliate対応あり 本日日付 YYYY-MM-DD

(*1)デフォルト値は、
チェックイン年月日およびチェックアウト年月日の両方が指定されなかった場合にのみ適用されます。
7 チェックアウト年月日 checkoutDate date Affiliate対応あり 明日日付 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 Affiliate対応あり
(*1)
- 日本測地系(Tokyo Datum)、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。
例)128216.17
ただし、datumTypeに1を指定した場合は、
世界測地系、単位は度で指定すること。
例)35.6065914
(*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。
19 経度 longitude decimal Affiliate対応あり
(*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
Affiliate対応あり Affiliate対応あり Affiliate対応あり 検索数 recordCount 検索結果の総レコード件数
2 総ページ数 pageCount 最大100
3 ページ番号 page 現在のページ番号
4 ページ内結果開始番号 first 検索結果の何件目からか
5 ページ内施設終追番 last 検索結果の何件目までか
1 施設情報
"<hotels> ~ </hotels>"
内に複数の"<hotel> ~ </hotel>"
が表示される
施設基本情報
hotelBasicInfo
Affiliate対応あり Affiliate対応あり Affiliate対応あり 施設番号 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
Affiliate対応あり Affiliate対応あり 宿泊予約センター電話番号 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
Affiliate対応あり Affiliate対応あり レコード件数 (予約候補) reserveRecordCount  
37 予約候補内最安値 lowestCharge 大人1名料金の最安値
38 予約候補内最高値 highestCharge 大人1名料金の最高値
39 部屋基本情報
roomBasicInfo
Affiliate対応あり Affiliate対応あり Affiliate対応あり 部屋種別 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 Affiliate対応あり プラン内容 planContents salesformFlagが0,2のときのみ返却されます。
52 分類:料金情報(1泊目のみ)
dailyCharge
Affiliate対応あり Affiliate対応あり Affiliate対応あり 宿泊年月日 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 を指定しなかった場合

{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}

keyword が正しい値でなかった時。(半角1文字のみ指定など)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 対象のデータが存在しなかった場合
{
    "error": "not_found",
    "error_description": "not found"
}
429 リクエスト過多 (各ユーザ制限値超過)

APIリクエスト数が上限に達した場合のエラーです。しばらく時間を空けてから、ご利用ください。

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 楽天ウェブサービス内のエラー

システムエラー。長時間続くようであれば、こちらよりごお問い合わせください。

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 メンテナンス・リクエスト過多 (全ユーザ制限値超過)

メンテナンス (XXX/XXX にはAPI名が入る)

{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}

レスポンスボディの形式は format に従います。

format エラー出力例
json
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>