Home      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 項目名 パラメーター 型(括弧内は最大バイト数) 必須 デフォルト 備考
Division: Shared parameters
1 App ID applicationId String 必須 - Check here
2 Affiliate ID affiliateId String - - Check here
3 Response format format String - json Either JSON or XML
When JSON is specified the callback parameter can also be set in order to use JSONP.
4 Callback function name callback String - - Function name to be used with the JSONP output
(UTF-8 URL encoded string)
Alphanumeric characters, periods, or underscores
5 Choosing output fields elements String - - By default, API response all of the fields. You can change response fields by this parameter.
This parameter's data is separated by comma(,).
For example, following request will response only itemName, itemPrice and itemUrl.
elements=itemName,itemPrice,itemUrl
6 Format version formatVersion int - 1

Response format version.

If formatVersion=2 is set, the response format (JSON) will be improved.

In case of formatVersion=1 :
Our API response will be returned in Array format as the followings.
You would need to use notation items[0].item.itemName To access itemName parameter.

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

In case of formatVersion=2 :
Our API response will be returned in Array format as the followings.
You can use notation items[0].itemName To access itemName parameter.

{"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月現在)

Error

Error messages are displayed in the form of HTTP status code and its response body

HTTP Status Code Description Response body example (JSON)
400 Parameter error (or required parameters were insufficient)

If applicationId is not set

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

If keyword is not valid (only 1 character given, etc.)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 If data not found.
{
    "error": "not_found",
    "error_description": "not found"
}
429 Too many requests

This error will be displayed if the number of API requests has been exceeded.
Please try access again after an amount of time.

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 Internal error in Rakuten Web Service

An internal system error occured. If you continue seeing this message for a long period, please give your inquiry via this link

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 Unavailable due to maintenance or overloaded

Maintenance (the API name will be displayed in XXX/XXX)

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

Response body format is display in format.

format Error output example
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>