楽天トラベルキーワード検索APIは、楽天トラベルの施設をキーワードで検索し、施設情報を取得することが可能なAPIです。デベロッパーは、キーワードでの施設検索をはじめ、地区コードでの絞込み検索も可能となります。
リクエストURL
https://app.rakuten.co.jp/services/api/Travel/KeywordHotelSearch/20170426?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallbackを指定することで出力されます。
フィールド名keywordに対応する[value]はUTF-8でURLエンコードされている必要があります。(リクエストURL全体をエンコードするのではなく、[value]部分を個別にエンコードしてください。)
たとえば、「品川シーサイド」という検索キーワードで施設を検索する場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)
https://app.rakuten.co.jp/services/api/Travel/KeywordHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&keyword=%E5%93%81%E5%B7%9D%E3%82%B7%E3%83%BC%E3%82%B5%E3%82%A4%E3%83%89
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天トラベルキーワード検索API(KeywordHotelSearch) 入力パラメーター 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 | キャリア情報 | carrier | int(1) | - | 0 | PC/スマートフォン用の情報を返すのか、フィーチャーフォン用の情報を返すのかを選択 0:PC/スマートフォン 1:フィーチャーフォン |
2 | 取得ページ | page | int | - | 1 | 取得対象のページ数。 1以上、100以下の整数であること。 |
3 | 1ページあたりの取得件数 | hits | int | - | 30 | 1ページ毎の取得施設件数を制限するパラメータ。 1以上、30以下の整数であること。 |
4 | 緯度経度タイプ | datumType | int(1) | - | 2 | 出力パラメータの緯度経度タイプを指定する。 1:世界測地系、単位は度。 2:日本測地系、単位は秒。 |
5 | 検索キーワード | keyword | String | - | 半角スペースで区切って複数キーワードを指定して頂いた場合、AND検索となります。 最低2文字以上を指定する必要があります。 |
|
6 | 中区分コード | middleClassCode | String | - | - | 都道府県などを示すコード。 このフィールドが指定された場合、 指定された地区に属する施設のみが検索対象となります。 コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
7 | 検索対象範囲 | searchField | int(1) | - | 0 | キーワード検索を行う対象項目を指定する。 0:施設名、プラン名、部屋名など 1:施設名のみ |
8 | ホテルチェーンコード | hotelChainCode | String | - | - | ホテルチェーンを特定するためのコード。 このフィールドが指定された場合、 指定されたホテルチェーンに属する施設のみが検索対象となります。 ホテルチェーンコード一覧はホテルチェーンAPI(GetHotelChainList) より取得してください。 このフィールドはカンマ区切りで5個まで指定することができます。 例)&hotelChainCode=JL,NK |
9 | 施設画像サイズ | hotelThumbnailSize | int(1) | - | 2 | 出力パラメータの施設画像サムネイルURLの画像サイズを指定する。 1:小 2:中 3:大 |
10 | 返却情報タイプ | responseType | String | - | middle | 返却情報タイプを指定するパラメータ。 small : 最低限の情報のみ middle : 中くらい large : すべての情報 |
11 | ソート | sort | String | - | standard | standard:キーワード適中率が高い順 +roomCharge:最安値料金(安い順) -roomCharge:最安値料金(高い順) |
出力パラメーター
楽天トラベルキーワード検索API(KeywordHotelSearch) 出力パラメーター 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)carrierがモバイルの場合、 ダイナミックパッケージ宿泊プラン一覧ページは 日付を御入力頂いた後にプラン一覧が出力されます。 |
|||||
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 | 評価詳細情報 hotelRatingInfo |
- | ★の数(サービス) | serviceAverage | ★の見方について | |||
29 | ★の数(立地) | locationAverage | ||||||
30 | ★の数(部屋) | roomAverage | ||||||
31 | ★の数(設備・アメニティ) | equipmentAverage | ||||||
32 | ★の数(風呂) | bathAverage | ||||||
33 | ★の数(食事) | mealAverage | ||||||
34 | 施設詳細情報 hotelDetailInfo |
- | - | 宿泊予約センター電話番号 | reserveTelephoneNo | 楽天価格での予約が電話で可能です。 | ||
35 | 中区分コード | middleClassCode | 都道府県などを示すコード。 コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
|||||
36 | 小区分コード | smallClassCode | 都道府県などを示すコード。 コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
|||||
37 | 地区名 | areaName | ||||||
38 | ホテル種別コード | hotelClassCode | ||||||
39 | チェックイン時刻 | checkinTime | HH:MM | |||||
40 | チェックアウト時刻 | checkoutTime | HH:MM | |||||
41 | 最終チェックイン時刻 | lastCheckinTime | HH:MM | |||||
42 | 設備情報 hotelFacilitiesInfo |
- | - | 部屋数 | hotelRoomNum | |||
43 | 部屋設備・備品 | roomFacilities | ||||||
44 | 項目名 | item | ||||||
45 | 館内設備 | hotelFacilities | ||||||
46 | 項目名 | item | ||||||
47 | 食事場所について | aboutMealPlace | ||||||
48 | 朝食 | breakfastPlace | ||||||
49 | 夕食 | dinnerPlace | ||||||
50 | 風呂について | aboutBath | ||||||
51 | 種類 | bathType | ||||||
52 | 泉質 | bathQuality | ||||||
53 | 効能 | bathBenefits | ||||||
54 | 周辺のレジャーについて | aboutLeisure | ||||||
55 | 身障者設備 | handicappedFacilities | ||||||
56 | 項目名 | item | ||||||
57 | スタッフの言語レベルについて | linguisticLevel | ||||||
58 | 宿泊条件・決済関連 hotelPolicyInfo |
- | - | 条件・注意事項・備考 | note | |||
59 | キャンセルポリシー | cancelPolicy | ||||||
60 | 使用可能なカード | availableCreditCard | ||||||
61 | > カード | card | ||||||
62 | カード利用についての注意事項 | aboutCreditCardNote | ||||||
63 | ポイント加算について | aboutPointAdd | 楽天スーパーポイント以外のポイントサービスについての情報 | |||||
64 | マイレージ加算について | aboutMileageAdd | ||||||
65 | 特典・その他 hotelOtherInfo |
- | - | 特典 | privilege | |||
66 | その他情報 | otherInformation |
アフィリエイトに関して
デベロッパーは、楽天商品検索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 |
|