|
楽天トラベルキーワード検索APIとは
楽天トラベルキーワード検索APIは、楽天トラベルの施設をキーワードで検索し、施設情報を取得することが可能なAPIです。デベロッパーは、キーワードでの施設検索をはじめ、地区コードでの絞込み検索も可能となります。
>> サンプルコードはこちら(楽天トラベルへ) |
|
|
■リクエストURL(REST/JSON形式の場合)
http://api.rakuten.co.jp/rws/3.0/rest?[parameter]=[value]…
http://api.rakuten.co.jp/rws/3.0/json?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallBackを指定することで出力されます。
フィールド名keywordに対応する[value]はUTF-8でURLエンコードされている必要があります。(リクエストURL全体をエンコードするのではなく、[value]部分を個別にエンコードしてください。)
たとえば、「品川シーサイド」という検索キーワードで施設を検索する場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)
http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=KeywordHotelSearch
&version=2009-10-20
&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:2009-10-20 |
| 区分 |
ID |
項目名 |
フィールド名 |
型
(括弧内は
最大
バイト数) |
必須 |
デフォルト |
備考 |
共
通
パ
ラ
メ
|
タ
| |
1 |
デベロッパID |
developerId |
String |
○ |
--- |
デベロッパーID |
| 2 |
アフィリエイトID |
affiliateId |
String |
- |
指定無し |
アフィリエイトID |
| 3 |
操作 |
operation |
String |
○ |
--- |
使用するAPIの操作名:KeywordHotelSearch |
| 4 |
コールバック関数名 |
callBack |
String |
- |
指定無し |
JSONPとして出力する際のコールバック関数名
(UTF-8でURLエンコードした文字列)
英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上 |
サ
|
ビ
ス
固
有
パ
ラ
メ
|
タ
| |
1 |
バージョン |
version |
String |
○ |
--- |
2009-10-20 |
| 2 |
キャリア情報 |
carrier |
int(1) |
- |
0 |
PC用の情報を返すのか、モバイル用の情報を返すのかを選択
0:PC
1:mobile |
| 3 |
取得ページ |
page |
int |
- |
1 |
取得対象のページ数。
1以上、100以下の整数であること。 |
| 4 |
1ページあたりの取得件数 |
hits |
int |
- |
30 |
1ページ毎の取得施設件数を制限するパラメータ。
1以上、30以下の整数であること。 |
| 5 |
緯度経度タイプ |
datumType |
int(1) |
- |
2 |
出力パラメータの緯度経度タイプを指定する。
1:世界測地系、単位は度。
2:日本測地系、単位は秒。 |
| 6 |
検索キーワード |
keyword |
String |
○ |
--- |
半角スペースで区切って複数キーワードを指定して頂いた場合、AND検索となります。 |
| 7 |
中区分コード |
middleClassCode |
String |
- |
--- |
都道府県などを示すコード。
このフィールドが指定された場合、
指定された地区に属する施設のみが検索対象となります。
コード一覧は地区コードAPI(GetAreaClass) より取得してください。 |
| 8 |
検索対象範囲 |
searchField |
int(1) |
- |
0 |
キーワード検索を行う対象項目を指定する。
0:施設名、プラン名、部屋名など
1:施設名のみ |
| 9 |
ホテルチェーンコード |
hotelChainCode |
String |
- |
--- |
ホテルチェーンを特定するためのコード。
このフィールドが指定された場合、
指定されたホテルチェーンに属する施設のみが検索対象となります。
ホテルチェーンコード一覧はホテルチェーンAPI(GetHotelChainList) より取得してください。
このフィールドはカンマ区切りで5個まで指定することができます。
例)&hotelChainCode=JL,NK |
| 10 |
施設画像サイズ |
hotelThumbnailSize |
int(1) |
- |
2 |
出力パラメータの施設画像サムネイルURLの画像サイズを指定する。
1:小
2:中
3:大 |
| 11 |
返却情報タイプ |
responseType |
String |
- |
middle |
返却情報タイプを指定するパラメータ。
small : 最低限の情報のみ
middle : 中くらい
large : すべての情報
|
| 12 |
ソート |
sort |
String |
- |
standard |
standard:キーワード適中率が高い順
+roomCharge:最安値料金(安い順)
-roomCharge:最安値料金(高い順) |
|
■出力パラメーター
※ 返却タイプ値によって、返却される情報が変化します。
| 楽天トラベルキーワード検索API(KeywordHotelSearch) 出力パラメーター version:2009-10-20 |
| 区分 |
ID |
分類 |
small |
middle |
large |
項目名 |
フィールド名 |
備考 |
共 通 パ ラ メ | タ | |
1 |
Arg |
○ |
○ |
○ |
--- |
User-Agent |
Valueにはユーザのユーザエージェントが表示される |
| 2 |
--- |
developerId |
ValueにはデベロッパーIDが表示される |
| 3 |
--- |
affiliateId |
Valueにはユーザの指定したアフィリエイトIDが表示される |
| 4 |
--- |
operation |
Valueにはユーザの指定した操作名が表示される |
| 5 |
--- |
version |
Valueにはユーザの指定した操作のバージョンが表示される |
| 6 |
Status |
○ |
○ |
○ |
--- |
Status |
Success / NotFound / ServerError / ClientError / Maintenance のいずれか |
| 7 |
StatusMsg |
○ |
○ |
○ |
--- |
StatusMsg |
Statusに特化したメッセージを出力 |
全 体 情 報 |
1 |
全体情報 pagingInfo |
○ |
○ |
○ |
検索結果総数 |
recordCount |
検索結果のレコード件数 |
| 2 |
総ページ数 |
pageCount |
最大100 |
| 3 |
ページ番号 |
page |
現在のページ番号 |
| 4 |
ページ内結果開始番号 |
first |
検索結果の何件目からか |
| 5 |
ページ内結果終了番号 |
last |
検索結果の何件目までか |
サ | ビ ス 固 有 パ ラ メ | タ |
1 |
施設情報 hotel |
施設基本情報 hotelBasicInfo |
○ |
○ |
○ |
施設番号 |
hotelNo |
|
| 2 |
施設名称 |
hotelName |
|
| 3 |
施設情報ページURL |
hotelInformationUrl |
入力パラメーターにアフィリエイトIDが含まれていた場合、
アフィリエイト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 |
|
| 21 |
施設画像サムネイルURL |
hotelThumbnailUrl |
|
| 22 |
部屋画像URL |
roomImageUrl |
|
| 23 |
部屋画像サムネイルURL |
roomThumbnailUrl |
|
| 24 |
施設提供地図画像URL |
hotelMapImageUrl |
|
| 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月現在)
■エラー
エラーが起こった際は、出力中の「共通パラメーター」のStatusに下表に記載されたいずれかが表示されます。
| Statusでの表示 |
内容 |
| NotFound |
検索結果が存在しない。 |
| ServerError |
楽天ウェブサービス側のエラー。 |
| ClientError |
デベロッパーの入力に起因するエラー。 |
| Maintenance |
メンテナンス。 |
|
■過去のバージョン
本APIの過去のバージョンは下記からご覧いただけます。
|