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

・	オンラインドキュメント
・	楽天ウェブサービス規約
・	FAQ
・	クレジット表示
・	ウェブサービスチームブログ
・	旧ブログ
・	デベロッパーズ・コミュニティ

・	楽天商品検索API
・	楽天ジャンル検索API
・	楽天商品コード検索API
・	楽天カタログ検索API
・	楽天商品ランキングAPI

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

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

・	楽天トラベル施設検索API【NEW】
・	楽天トラベル施設情報API
・	楽天トラベル空室検索API【NEW】
・	楽天トラベル地区コードAPI
・	楽天トラベルキーワード検索API【NEW】
・	楽天トラベルホテルチェーンAPI
・	楽天トラベルランキングAPI
	>> 楽天トラベル系APIサンプル集
・	楽天トラベル施設リンク一括作成ツール

・	楽天ダイナミックアドAPI
・	楽天ダイナミックアドAPI トラベル

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

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

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

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

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

■リクエスト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を指定することで出力されます。

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

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

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

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

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

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

http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=VacantHotelSearch
&version=2009-10-20
&hotelNo=123456
&checkinDate=2009-12-01
&checkoutDate=2009-12-02
&maxCharge=8500

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

■SOAPについて

SOAPを用いることで、より高度なアプリケーションの開発が可能となります。
SOAPに関しての詳細は「楽天トラベル空室検索API（VacantHotelSearch)SOAP開発用」をご覧ください。

■入力パラメーター

楽天トラベル空室検索API（VacantHotelSearch) 入力パラメータ version:2009-10-20
区分	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-10-20
	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 (*1)デフォルト値は、チェックイン年月日およびチェックアウト年月日の両方が指定されなかった場合にのみ適用されます。
	8	チェックアウト年月日	checkoutDate	date	○	明日日付	YYYY-MM-DD (*1)デフォルト値は、チェックイン年月日およびチェックアウト年月日の両方が指定されなかった場合にのみ適用されます。
	9	人数(大人)	adultNum	int(2)	-	1	1以上、99以下の整数であること。
	10	人数(小学生高学年)	upClassNum	int(2)	-	0	0以上、99以下の整数であること。
	11	人数(小学生低学年)	lowClassNum	int(2)	-	0	0以上、99以下の整数であること。
	12	人数(幼児(食事・布団付))	infantWithMBNum	int(2)	-	0	0以上、99以下の整数であること。
	13	人数(幼児(食事のみ))	infantWithMNum	int(2)	-	0	0以上、99以下の整数であること。
	14	人数(幼児(布団のみ))	infantWithBNum	int(2)	-	0	0以上、99以下の整数であること。
	15	人数(幼児(食事・布団不要))	infantWithoutMBNum	int(2)	-	0	0以上、99以下の整数であること。
	16	部屋数	roomNum	int(2)	-	1	1以上、10以下の整数であること。
	17	上限金額	maxCharge	long	-	指定無し	0以上、999999999以下の整数であること。
	18	下限金額	minCharge	long	-	指定無し	0以上、999999999以下の整数であること。 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用の情報を返すのか、モバイル用の情報を返すのかを選択 0：PC 1：mobile
	24	緯度経度タイプ	datumType	int(1)		2	入力及び出力パラメータの緯度経度タイプを指定する。 1：世界測地系、単位は度。 2：日本測地系、単位は秒。
	25	1ページあたりの取得件数	hits	int	-	30	1ページ毎の取得件数を制限するパラメータ。(1) ■searchPatternに0を指定した場合（施設ごと検索）■ 1ページ毎の取得施設件数を制限する。 1以上、30以下の整数であること。 ■searchPatternに1を指定した場合（宿泊プランごと検索）■ 1ページ毎の取得プラン件数を制限する。 1以上、30以下の整数であること。 (1)pageとhitsが指定されていた場合、allReturnFlagは無効になります。
	26	取得ページ	page	int	-	1	取得対象のページ数。 1以上、100以下の整数であること。(1) (1)pageとhitsが指定されていた場合、allReturnFlagは無効になります。
	27	検索パターン【NEW】	searchPattern	int	-	0	検索パターンを指定するパラメータ 0：施設ごと 1：宿泊プランごと ■施設ごと■ 検索条件にあてはまる情報を施設単位で検索する。 ※提供されている宿泊プラン情報も施設あたり最大3件まで同時に取得可能 ■宿泊プランごと■ 検索条件にあてはまる情報を宿泊プラン・客室単位で検索する。
	28	施設画像サイズ【NEW】	hotelThumbnailSize	int(1)	-	2	出力パラメータの施設画像サムネイルURLの画像サイズを指定する。 1：小 2：中 3：大
	29	返却情報タイプ【NEW】	responseType	String	-	small	出力パラメータの返却情報タイプを指定する。 small:最低限の情報のみ middle:中くらい large:すべての情報
	30	ソート【NEW】	sort	String	-	standard	standard:おすすめ順 +roomCharge:料金が安い順 -roomCharge:料金が高い順
	31	全件返却フラグ【NEW】	allReturnFlag	int(1)	-	---	条件に該当する情報を全件返却するフラグ。(1)(2) 1：全件返却 (1)緯度経度検索で、responseTypeがsmall、searchPatternが0のときのみ有効。 (2)pageとhitsが指定されていた場合、allReturnFlagは無効になります。

▲上へ

■出力パラメーター

楽天トラベル空室検索API（VacantHotelSearch) 出力パラメータ 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	検索結果の何件目までか
サ \| ビス固有パラメ \| タ \| h o t e l	1	施設情報 hotelInfo	施設基本情報 hotelBasicInfo	○	○	○	施設番号	hotelNo
	2						施設名称	hotelName
	3						施設情報ページURL	hotelInformationUrl	入力パラメーターにアフィリエイトIDが含まれていた場合、アフィリエイトURLとなります。(1) (1)「ダイナミックパッケージ宿泊プラン一覧ページURL」「お客様の声ページURL」は carrierがPCのときのみ返却されます。モバイルは11月初旬より対応予定です。
	4						宿泊プラン一覧ページURL	planListUrl
	5						ダイナミックパッケージ宿泊プラン一覧ページURL	dbPlanListUrl
	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						住所１	address1
	14						住所２	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	★の見方について (http://travel.rakuten.co.jp/share/toukou/explain_ws.html)
	27						お客さまの声（1件目）	userReview	お客さまの声の最新の１件目を表示します。
	28		施設詳細情報 hotelDetailInfo	－	○	○	宿泊予約センター電話番号	reserveTelephoneNo	楽天価格での予約が電話で可能です。
	29						中区分コード	middleClassCode	都道府県などを示すコード。コード一覧は地区コードAPI（GetAreaClass) より取得してください。
	30						小区分コード	smallClassCode	市など示すコード。コード一覧は地区コードAPI（GetAreaClass) より取得してください。
	31						地区名	areaName
	32						ホテル種別コード	hotelClassCode
	33						チェックイン時刻	checkinTime	HH:MM
	34						チェックアウト時刻	checkoutTime	HH:MM
	35						最終チェックイン時刻	lastCheckinTime	HH:MM
	36		施設予約関連 hotelReserveInfo	－	○	○	レコード件数 (予約候補)	reserveRecordCount
	37						予約候補内最安値	lowestCharge	大人１名料金の最安値
	38						予約候補内最高値	highestCharge	大人１名料金の最高値
	39	部屋情報 roomInfo	部屋基本情報 roomBasicInfo	○	○	○	部屋種別	roomClass
	40						部屋名称	roomName
	41						プランID	planId	salesformFlagが0のときのみ返却されます。
	42						プラン名称	planName	salesformFlagが0のときのみ返却されます。
	43						楽天ポイント付与率	pointRate	単位%
	44						夕食有無フラグ	withDinnerFlag	0:夕食無し 1:夕食有り
	45						夕食選択フラグ	dinnerSelectFlag	0:夕食選択不可 1:夕食選択可
	46						朝食有無フラグ	withBreakfastFlag	0:朝食無し 1:朝食有り
	47						朝食選択フラグ	breakfastSelectFlag	0:朝食選択不可 1:朝食選択可
	48						決済方法	payment	0:現地決済 1:現地決済 / オンラインカード決済 2:オンラインカード決済
	49						予約ページURL	reserveUrl	アフィリエイトIDが設定されている場合、アフィリエイトURLとなります。（入力パラメーターにアフィリエイトIDが含まれていた時のみ）
	50						販売形式フラグ	salesformFlag	0:プラン 1:部屋 2:当日限定部屋
	51			－	－	○	プラン内容	planContents	salesformFlagが0のときのみ返却されます。
	52		料金情報 (1泊目のみ) dailyCharge	○	○	○	宿泊年月日	stayDate	YYYY-MM-DD
	53						楽天料金	rakutenCharge	宿泊年月日１泊の料金です。 ■chargeFlagが0のとき■ 1人あたりの料金 ■chargeFlagが1のとき■ 1室あたりの料金
	54						合計料金	total	宿泊年月日１泊の合計料金です。
	55						料金単位フラグ	chargeFlag	0:1人あたりの料金（円/人） 1:1室あたりの料金（円/室）

▲上へ

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

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

▲上へ

■エラー

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

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

▲上へ

■過去のバージョン

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

・楽天トラベル空室検索API（2007-02-28）

・楽天トラベル空室検索API（2007-03-14）

・楽天トラベル空室検索API（2007-03-28）

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

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

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

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

・楽天トラベル空室検索API（2009-06-25）

▲上へ