Home      API一覧     楽天トラベルランキングAPI

楽天トラベルランキングAPIは、楽天トラベル内のコンテンツ「ホテル・旅館ランキング」の一部の情報を取得することが可能なAPIです。
デベロッパーは総合・温泉宿・高級ホテル/旅館という3つのジャンル別にお客様の評価の高いランキングを取得することができます。

リクエストURL


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

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

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

(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の出力方法が改善され以下のようになります。

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 ジャンル genre String Affiliate対応あり 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 を指定しなかった場合

{
    "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>