リクエスト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行につなげてリクエストしてください。）

入力パラメーター

楽天トラベル空室検索API（VacantHotelSearch) 入力パラメータ version:2009-10-20

ID	項目名	パラメーター	型(括弧内は最大バイト数)	必須	デフォルト	備考
区分:共通パラメーター
1	デベロッパID	developerId	String		-	デベロッパーID（こちらで確認できるアプリケーション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	項目名	パラメーター	備考
区分:共通パラメーター
分類:Arg
1				-	User-Agent	Valueにはユーザのユーザエージェントが表示される
2				-	developerId	ValueにはデベロッパーIDが表示される
3				-	affiliateId	Valueにはユーザの指定したアフィリエイトIDが表示される
4				-	operation	Valueにはユーザの指定した操作名が表示される
5				-	version	Valueにはユーザの指定した操作のバージョンが表示される
分類:Status
6				-	Status	Success / NotFound / ServerError / ClientError / Maintenance のいずれか
分類:StatusMsg
7				-	StatusMsg	Statusに特化したメッセージを出力
区分:全体情報
1				検索数	recordCount	検索結果の総レコード件数
2				総ページ数	pageCount	最大100
3				ページ番号	page	現在のページ番号
4				ページ内施設始追番	first	検索結果の何件目からか
5				ページ内施設終追番	last	検索結果の何件目までか
区分:サービス固有パラメータ hotel
分類:施設基本情報 hotelBasicInfo
1				施設番号	hotelNo
2				施設名称	hotelName
3				施設情報ページURL	hotelInformationUrl	入力パラメーターにアフィリエイトIDが含まれていた場合、 アフィリエイトURLとなります。(*1) (*1)「ダイナミックパッケージ宿泊プラン一覧ページURL」 「お客さまの声ページURL」は carrierがPCの時のみ返却されます。
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	お客さまの声の最新の１件目を表示します。
分類:施設詳細情報 hotelDetailInfo
28	－			宿泊予約センター電話番号	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
分類:施設予約関連 hotelReserveInfo
36	－			レコード件数 (予約候補)	reserveRecordCount
37				予約候補内最安値	lowestCharge	大人１名料金の最安値
38				予約候補内最高値	highestCharge	大人１名料金の最高値
分類:部屋基本情報 roomBasicInfo
39				部屋種別	roomClass
40				部屋名称	roomName
41				プランID	planId	salesformFlagが0,2のときのみ返却されます。
42				プラン名称	planName
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,2のときのみ返却されます。
分類:料金情報（1泊目のみ） dailyCharge
52				宿泊年月日	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に下表に記載されたいずれかが表示されます。