楽天トラベルランキングAPIは、楽天トラベル内のコンテンツ「ホテル・旅館ランキング」の一部の情報を取得することが可能なAPIです。
デベロッパーは総合・温泉宿・高級ホテル/旅館という3つのジャンル別にお客様の評価の高いランキングを取得することができます。
リクエストURL
https://app.rakuten.co.jp/services/api/Travel/HotelRanking/20170426?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallbackを指定することで出力されます。
たとえば、以下の3つのような場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)
https://app.rakuten.co.jp/services/api/Travel/HotelRanking/20170426?
applicationId=[アプリID]
&format=xml
&carrier=0
&genre=all
(2)「温泉宿」のランキング情報を取得する場合
https://app.rakuten.co.jp/services/api/Travel/HotelRanking/20170426?
applicationId=[アプリID]
&format=json
&carrier=0
&genre=onsen
(3)「総合」「温泉宿」のランキング情報を2種類同時に取得する場合
https://app.rakuten.co.jp/services/api/Travel/HotelRanking/20170426?
applicationId=[アプリID]
&format=slimxml
&carrier=0
&genre=all,onsen
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天トラベルランキングAPI(HotelRanking) 入力パラメーター 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 | ジャンル | genre | String | all | all : 総合ランキング onsen : 温泉宿ランキング premium : 高級ホテル/旅館ランキング このフィールドはCSV形式で複数指定することができます。 例) &genre=all,onsen 上記を指定した場合、 総合ランキングと温泉宿ランキングの2種類のランキングを返却します。 |
|
2 | キャリア | carrier | int(1) | - | 0 | PC/スマートフォン用の情報を返すのか、フィーチャーフォン用の情報を返すのかを選択 0:PC/スマートフォン 1:フィーチャーフォン |
出力パラメーター
楽天トラベルランキングAPI(HotelRanking) 出力パラメーター version:2017-04-26
ID | 大分類 | 分類 | 項目名 | パラメーター | 備考 |
---|---|---|---|---|---|
区分:サービス固有パラメーター | |||||
1 | 施設ランキング情報 Rankings "<Rankings> ~ </Rankings>"内に複数の" <Ranking> ~ </Ranking>"が表示される |
ジャンル | genre | ||
2 | タイトル | title | |||
3 | 最終更新時間 | lastBuildDate | |||
4 | 施設ランク情報 "<hotels> ~ </hotels>" 内に複数の"<hotel> ~ </hotel>" が表示される |
順位 | rank | 1~10 | |
5 | 施設番号 | hotelNo | |||
6 | 施設名 | hotelName | |||
7 | 地区中区分名称 | middleClassName | 施設の所在都道府県 | ||
8 | お客さまの声 | userReview | 集計時点での最新のお客さまの声情報となります。 | ||
9 | お客さまの声件数 | reviewCount | 集計時点での最新のお客さまの声件数となります。 | ||
10 | 施設情報ページURL | hotelInformationUrl | httpsではじまる施設情報ページURLとなります | ||
11 | 宿泊プラン一覧URLページURL | planListUrl | httpsではじまる宿泊プラン一覧URLページURLとなります | ||
12 | 空室検索URL | checkAvailableUrl | httpsではじまる空室検索URLとなります | ||
13 | お客様の声ページURL | reviewUrl | httpsではじまるお客様の声ページURLとなります | ||
14 | 施設画像URL | hotelImageUrl | httpsではじまる施設画像URLとなります | ||
15 | 施設画像サムネイルURL | hotelThumbnailUrl | httpsではじまる施設画像サムネイルURLとなります | ||
16 | 星の数 | reviewAverage | |||
17 | キャリア | carrier | 0:PC 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 |
|