【楽天ウェブサービス】RAKUTEN WEBSERVICE

・	オンラインドキュメント
・	楽天ウェブサービス規約
・	FAQ
・	APIステータス
・	クレジット表示
・	ウェブサービスチームブログ
・	旧ブログ

・	楽天商品検索API
・	楽天ジャンル検索API
・	楽天商品コード検索API
・	楽天商品ランキングAPI
・	楽天プロダクト製品検索API
・	楽天プロダクト製品詳細API
・	楽天プロダクトジャンル情報API
・	楽天プロダクトメーカー情報API

・	楽天ブックス総合検索API
・	楽天ブックス書籍API
・	楽天ブックスCD検索API
・	楽天ブックスDVD/Blu-ray検索API
・	楽天ブックス洋書検索API
・	楽天ブックス雑誌検索API
・	楽天ブックスゲーム検索API
・	楽天ブックスソフトウェア検索API
・	楽天ブックスジャンル検索API

・	楽天オークション商品検索API
・	楽天オークション商品コード検索API
・	楽天オークションジャンル検索API

・	楽天トラベル施設検索API
・	楽天トラベル施設情報API
・	楽天トラベル空室検索API
・	楽天トラベル地区コードAPI
・	楽天トラベルキーワード検索API
・	楽天トラベルホテルチェーンAPI
・	楽天トラベルランキングAPI
	>> 楽天トラベル系APIサンプル集

・	楽天GORAゴルフ場検索API
・	楽天GORAゴルフ場詳細API
・	楽天GORAプラン検索API
・	楽天ダイナミックアドAPI
・	楽天ダイナミックアドAPI トラベル
・	楽天アフィリエイト高料率ショップAPI

楽天トラベル空室検索API (version:2009-06-25)

このバージョンのAPIは2012年5月7日に廃止予定です。最新バージョンのAPI (version:2009-10-20)をご利用ください。詳細はこちらをご覧ください。

楽天トラベル空室検索APIとは

楽天トラベル空室検索APIは、（楽天トラベル地区コードAPIから得られる）地区コード、緯度経度、施設番号などから予約可能な部屋を検索することができます。デベロッパーは、リアルタイムな空室情報を得ることができます。

アカウント情報
・	デベロッパーIDの確認
・	アフィリエイトIDの確認

・リクエストURL
・入力パラメーター
・出力パラメーター
・アフィリエイトに関して
・エラー
・過去のバージョン

■リクエストURL（REST／JSON形式の場合）

http://api.rakuten.co.jp/rws/2.0/rest?[parameter]=[value]…
http://api.rakuten.co.jp/rws/2.0/json?[parameter]=[value]…

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

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

(1) 2009年7月1日の田沢湖で、大人2名１室で1泊できる宿を検索する場合

http://api.rakuten.co.jp/rws/2.0/rest?
developerId=[YOUR_developerID]
&operation=VacantHotelSearch
&version=2009-06-25
&largeClassCode=japan
&middleClassCode=akita
&smallClassCode=tazawa
&checkinDate=2009-07-01
&checkoutDate=2009-07-02
&adultNum=2

(2) 2009年7月1日で東京駅の半径1Km圏内において、大人1名が1泊できる宿を検索する場合

http://api.rakuten.co.jp/rws/2.0/rest?
developerId=[YOUR_developerID]
&operation=VacantHotelSearch
&version=2009-06-25
&checkinDate=2009-07-01
&checkoutDate=2009-07-02
&latitude=128440.51
&longitude=503172.21
&searchRadius=1

(3) 2009年7月1日に大人1名が8,500円以下で施設番号123456のホテルに1泊できるかどうかを検索する場合

http://api.rakuten.co.jp/rws/2.0/rest?
developerId=[YOUR_developerID]
&operation=VacantHotelSearch
&version=2009-06-25
&hotelNo=123456
&checkinDate=2009-07-01
&checkoutDate=2009-07-02
&maxCharge=8500

※	短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。

■入力パラメーター

楽天トラベル空室検索API（VacantHotelSearch) 入力パラメータ version:2009-06-25
区分	ID	項目名	フィールド名	型 (括弧内は最大バイト数）	必須	デフォルト	備考
共通パラメ \| タ \|	1	デベロッパID	developerId	String	○	---	デベロッパーID
	2	アフィリエイトID	affiliateId	String	-	指定無し	アフィリエイトID
	3	操作	operation	String	○	---	使用するAPIの操作名：VacantHotelSearch
	4	コールバック関数名	callBack	String	-	指定無し	JSONPとして出力する際のコールバック関数名（UTF-8でURLエンコードした文字列）英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上
サ \| ビス固有パラメ \| タ \|	1	バージョン	version	String	○	---	2009-06-25
	2	大区分コード	largeClassCode	String	○ (1) (2)	---	国などを示すコード。地区コード一覧は地区コードAPI（GetAreaClass) より取得してください。 (1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。 (2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
	3	中区分コード	middleClassCode	String	○ (1) (2)	---	都道府県などを示すコード。コード一覧は地区コードAPI（GetAreaClass) より取得してください。 (1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。 (2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
	4	小区分コード	smallClassCode	String	○ (1) (2)	---	市など示すコード。コード一覧は地区コードAPI（GetAreaClass) より取得してください。 (1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。 (2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
	5	細区分コード	detailClassCode	String	○ (1) (2)	---	駅や詳細地域などを示すコード。コード一覧は地区コードAPI（GetAreaClass) より取得してください。 (1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。 (2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。
	6	施設番号	hotelNo	int(10)	○ (*1)	---	楽天トラベルにおける施設を特定するためのNo (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。このフィールドは15個まで指定することができます。例）&hotelNo=12345,54321
	7	チェックイン年月日	checkinDate	date	○	---	YYYY-MM-DD
	8	チェックアウト年月日	checkoutDate	date	○	---	YYYY-MM-DD
	9	人数(大人)	adultNum	int(2)	-	1	1以上、2桁以下であること
	10	人数(小学生高学年)	upClassNum	int(2)	-	0	0以上、2桁以下であること
	11	人数(小学生低学年)	lowClassNum	int(2)	-	0	0以上、2桁以下であること
	12	人数(幼児(食事・布団付))	infantWithMBNum	int(2)	-	0	0以上、2桁以下であること
	13	人数(幼児(食事のみ))	infantWithMNum	int(2)	-	0	0以上、2桁以下であること
	14	人数(幼児(布団のみ))	infantWithBNum	int(2)	-	0	0以上、2桁以下であること
	15	人数(幼児(食事・布団不要))	infantWithoutMBNum	int(2)	-	0	0以上、2桁以下であること
	16	部屋数	roomNum	int(3)	-	1	1以上、3桁以下であること
	17	上限金額	maxCharge	long	-	指定無し	0以上、10桁以下であること
	18	下限金額	minCharge	long	-	指定無し	0以上、10桁以下であること maxChargeはminChargeより大きい必要がある
	19	緯度	latitude	decimal	○ (*1)	---	日本測地系（Tokyo Datum）、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。例）128216.17 ただし、datumTypeに1を指定した場合は、世界測地系、単位は度で指定すること。例）35.6065914 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。
	20	経度	longitude	decimal	○ (*1)	---	日本測地系（Tokyo Datum）、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。例）503259.29 ただし、datumTypeに1を指定した場合は、世界測地系、単位は度で指定すること。例）139.7513225 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号＞緯度経度＞区分コード]となります。
	21	検索半径	searchRadius	int	-	1	緯度経度検索時の検索半径(単位km) 0.1以上、3.0以下であり、小数点以下は１桁までであること
	22	絞込み条件	squeezeCondition	String	-	---	kinen：禁煙ルーム internet：インターネットが出来る部屋 daiyoku：大浴場あり onsen：温泉 breakfast：朝食あり dinner：夕食ありこのフィールドは複数指定することができます。例）禁煙ルームのある温泉宿 &squeezeCondition= kinen,onsen
	23	キャリア情報	carrier	int(1)	-	0	PC用の情報を返すのか、モバイル用の情報を返すのかを選択 PC:0 mobile:1
	24	緯度経度タイプ	datumType	int(1)	-	2	ＡＰＩで扱う(入力及び出力)緯度経度のタイプを指定する。 1：世界測地系、単位は度。 2：日本測地系、単位は秒。デフォルト値。
	25	取得件数【NEW】	hits	long	-	30(*1)	■区分コード、施設番号による検索の場合■ 1ページ毎の取得プラン件数を制限するパラメータ。 1以上、30以下の整数(2) ■経度緯度による検索の場合■ 取得施設件数を制限するパラメータ。指定された座標から近い順にソートした結果を返します。 1以上、50以下の整数(2) (1)緯度経度による検索時のみ、デフォルト値は50となります。 (2)経度緯度による検索時のみ、1から50までの整数を指定して頂けます。
	26	取得ページ【NEW】	page	int	-	1	1から100までの整数(1) (1)緯度経度検索の場合、このパラメータは無視されます。

▲上へ

■出力パラメーター

楽天トラベル空室検索API（VacantHotelSearch) 出力パラメータ version:2009-06-25
区分	ID	分類	項目名	フィールド名	備考
共通パラメ \| タ \|	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	全体情報【NEW】	検索数	recordCount	検索結果の総レコード件数
	2		ページ番号	page	現在のページ番号
	3		ページ内施設始追番	first	検索結果の何件目からか
	4		ページ内施設終追番	last	検索結果の何件目までか
	5		ヒット件数	hits	■区分コード、施設番号による検索の場合■ 1ページ毎の取得プラン件数 ■経度緯度による検索の場合■ 取得施設件数
	6		総ページ数	pageCount	最大100
	1		検索半径	searchRadius	緯度経度検索時の検索半径(単位km) (指定の半径で対象がない時は半径を大きくして検索する)
	2	部屋情報	---	room
	3		施設番号	hotelNo
	4		部屋種別	roomClass
	5		部屋名称	roomName
	6		プランID	planId
	7		プラン名称	planName
	8		プラン内容	planContents
	9		楽天ポイント付与率	pointRate	単位%
	10		夕食有無フラグ	withDinnerFlag	0:夕食無し 1:夕食有り
	11		夕食選択フラグ	dinnerSelectFlag	0:夕食選択不可 1:夕食選択可
	12		朝食有無フラグ	withBreakfastFlag	0:朝食無し 1:朝食有り
	13		朝食選択フラグ	breakfastSelectFlag	0:朝食選択不可 1:朝食選択可
	14		決済方法	settleWay
	15		予約ページURL	reserveUrl
	16		予約ページアフィリエイトURL	reserveAffiliateUrl	（入力パラメーターにアフィリエイトIDが含まれていた時のみ）
	17	料金情報(*1)	---	dailyCharge	(*1)部屋情報の子になり、宿泊数分存在します。
	18		宿泊年月日	stayDate	YYYY-MM-DD
	19		通常料金	regularCharge	宿泊年月日１泊の一般料金です。
	20		楽天料金	rakutenCharge	宿泊年月日１泊の楽天料金です。
	21	施設情報	---	hotel
	22		施設番号	hotelNo
	23		施設名称	hotelName
	24		施設かな名称	hotelKanaName
	25		施設特色	hotelSpecial
	26		チェックイン時刻	checkinTime	HH:MM
	27		チェックアウト時刻	checkoutTime	HH:MM
	28		緯度	latitude	datumType=1の場合：世界測地系（WGS）、単位は度 datumType=2の場合：日本測地系（Tokyo Datum）、単位は秒、小数点以下がミリ秒
	29		経度	longitude	datumType=1の場合：世界測地系（WGS）、単位は度 datumType=2の場合：日本測地系（Tokyo Datum）、単位は秒、小数点以下がミリ秒
	30		郵便番号	postalCode
	31		住所１	address1
	32		住所２	address2
	33		施設電話番号	telephoneNo
	34		ファックス番号	faxNo
	35		施設へのアクセス	access
	36		最寄駅名称	nearestStationName
	37		駐車場情報	parkingInformation
	38		ホテル種別コード	hotelClassCode
	39		レコード件数 (予約候補)	recordCount
	40		予約候補内最安値	lowestCharge	大人１名料金の最安値
	41		予約候補内最高値	highestCharge	大人１名料金の最高値
	42		施設画像URL	hotelImageUrl
	43		施設情報ページURL	hotelInformationUrl
	44		施設情報ページアフィリエイトURL	hotelAffiliateUrl	（入力パラメーターにアフィリエイトIDが含まれていた時のみ）
	45		宿泊予約センター電話番号	reserveTelephoneNo	楽天価格での予約が電話で可能です。

▲上へ

■アフィリエイトに関して

デベロッパーは、楽天トラベル空室検索APIからアフィリエイトURLを取得することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。
アフィリエイトURLを作るには、APIの入力パラメーターに「アフィリエイトID」を含めてリクエストしてください。APIの出力に「アフィリエイトURL」が含まれます。
入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。（2008年11月現在）

▲上へ

■エラー

エラーが起こった際は、出力中の「共通パラメーター」のStatusに下表に記載されたいずれかが表示されます。

Statusでの表示	内容
NotFound	検索結果が存在しない。
ServerError	楽天ウェブサービス側のエラー。
ClientError	デベロッパーの入力に起因するエラー。
Maintenance	メンテナンス。

▲上へ

■過去のバージョン

本APIの過去のバージョンは下記からご覧いただけます。

・楽天トラベル空室検索API（2008-11-13）

▲上へ