楽天トラベル施設検索APIは、楽天トラベルの施設を施設番号、緯度経度、区分コードなどで検索し、施設情報を取得することが可能なAPIです。
リクエストURL
https://app.rakuten.co.jp/services/api/Travel/SimpleHotelSearch/20170426?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallbackを指定することで出力されます。
たとえば、以下の3つのような場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)
https://app.rakuten.co.jp/services/api/Travel/SimpleHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&largeClassCode=japan
&middleClassCode=akita
&smallClassCode=tazawa
(2)東京駅の半径1Km圏内の宿を検索する場合
https://app.rakuten.co.jp/services/api/Travel/SimpleHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&latitude=128440.51
&longitude=503172.21
&searchRadius=1
(3)施設番号123456の宿と654321の宿を検索する場合
https://app.rakuten.co.jp/services/api/Travel/SimpleHotelSearch/20170426?
applicationId=[アプリID]
&format=xml
&hotelNo=123456,654321
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天トラベル施設検索API(SimpleHotelSearch) 入力パラメーター version:2017-04-26
ID | 項目名 | パラメーター | 型(括弧内は最大バイト数) | 必須 | デフォルト | 備考 |
---|---|---|---|---|---|---|
Division: Shared parameters | ||||||
1 | App ID | applicationId | String | - | Check here | |
2 | Affiliate ID | affiliateId | String | - | - | Check here |
3 | Response format | format | String | - | json | Either JSON or XML When JSON is specified the callback parameter can also be set in order to use JSONP. |
4 | Callback function name | callback | String | - | - | Function name to be used with the JSONP output (UTF-8 URL encoded string) Alphanumeric characters, periods, or underscores |
5 | Choosing output fields | elements | String | - | - |
By default, API response all of the fields. You can change response fields by this parameter. This parameter's data is separated by comma(,). For example, following request will response only itemName, itemPrice and itemUrl. elements=itemName,itemPrice,itemUrl
|
6 | Format version | formatVersion | int | - | 1 |
Response format version. If
In case of {"items": [ {"item": { "itemName": "a", "itemPrice": 10 }}, {"item": { "itemName": "b", "itemPrice": 20 }} ]}
In case of {"items": [ { "itemName": "a", "itemPrice": 10 }, { "itemName": "b", "itemPrice": 20 } ]} |
区分:サービス固有パラメーター | ||||||
1 | 大区分コード | largeClassCode | String | (*1) (*2) |
- | 国などを示すコード。地区コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
2 | 中区分コード | middleClassCode | String | (*1) (*2) |
- | 都道府県などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
3 | 小区分コード | smallClassCode | String | (*1) (*2) |
- | 市など示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
4 | 細区分コード | detailClassCode | String | (*1) (*2) |
- | 駅や詳細地域などを示すコード。コード一覧は地区コードAPI(GetAreaClass) より取得してください。 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 (*2)地区コード一覧において子の区分が存在する場合、必ず子の区分まで指定する必要があります。 |
5 | 施設番号 | hotelNo | int(10) | (*1) |
- | 楽天トラベルにおける施設を特定するためのNo (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 このフィールドは15個まで指定することができます。 例)&hotelNo=12345,54321 |
6 | 緯度 | latitude | decimal | (*1) |
- | 日本測地系(Tokyo Datum)、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。 例)128216.17 ただし、datumTypeに1を指定した場合は、 世界測地系、単位は度で指定すること。 例)35.6065914 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 |
7 | 経度 | longitude | decimal | (*1) |
- | 日本測地系(Tokyo Datum)、単位は秒、ミリ秒は小数点以下2桁以内で指定すること。 例)503259.29 ただし、datumTypeに1を指定した場合は、 世界測地系、単位は度で指定すること。 例)139.7513225 (*1)区分コード、施設番号、緯度経度いずれかが指定されていることが必須です。複数指定された場合の優先順位は[施設番号>緯度経度>区分コード]となります。 |
8 | 検索半径 | searchRadius | int | - | 1 | 緯度経度検索時の検索半径(単位km) 0.1以上、3.0以下であり、小数点以下は1桁までであること |
9 | 絞込み条件 | squeezeCondition | String | - | - | kinen:禁煙ルーム internet:インターネットが出来る部屋 daiyoku:大浴場あり onsen:温泉 このフィールドは複数指定することができます。 例)禁煙ルームのある温泉宿 &squeezeCondition=kinen,onsen |
10 | キャリア情報 | carrier | int(1) | - | 0 | PC/スマートフォン用の情報を返すのか、フィーチャーフォン用の情報を返すのかを選択 0:PC/スマートフォン 1:フィーチャーフォン |
11 | 緯度経度タイプ | datumType | int(1) | - | 2 | 入力及び出力パラメータの緯度経度タイプを指定する。 1:世界測地系、単位は度。 2:日本測地系、単位は秒。 |
12 | 取得ページ | page | int | - | 1 | 取得対象のページ数。 1以上、100以下の整数であること。(*1) (*1)緯度経度検索でallReturnFlagが指定されていた場合、 pageとhitsは無効になります。 |
13 | 1ページあたりの取得件数 | hits | int | - | 30 | 1ページ毎の取得件数を制限するパラメータ。 1以上、30以下の整数であること。(*1) (*1)緯度経度検索でallReturnFlagが指定されていた場合、 pageとhitsは無効になります。 |
14 | 施設画像サイズ | hotelThumbnailSize | int(1) | - | 2 | 出力パラメータの施設画像サムネイルURLの画像サイズを指定する。 1:小 2:中 3:大 |
15 | 返却情報タイプ | responseType | String | - | middle | 出力パラメータの返却情報タイプを指定する。 small:最低限の情報のみ middle:中くらい large:すべての情報 |
16 | ソート | sort | String | - | standard | standard:おすすめ順(*1) +roomCharge:最安値料金(安い順) -roomCharge:最安値料金(高い順) (*1)おすすめ順とは・・・ ■区分コード、施設番号による検索の場合■ standard:施設番号順 ■経度緯度による検索の場合■ standard:指定された座標から近い順 |
17 | 全件返却フラグ | allReturnFlag | int(1) | - | - | 条件に該当する情報を全件返却するフラグ。(*1)(*2) 1:全件返却 (*1)緯度経度検索のときのみ有効。 (*2)allReturnFlagが指定されていた場合、pageとhitsは無効になります。 |
出力パラメーター
楽天トラベル施設検索API(SimpleHotelSearch) 出力パラメーター 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の作り方は2通りあります。入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。
(1) APIの入力パラメーターに「アフィリエイトID」を含める場合:
APIの出力に「アフィリエイトURL」が含まれます。
(2) デベロッパーが自ら、(APIから取得した)「商品URL」と「アフィリエイトID(β版)」から「アフィリエイトURL」を作成する場合:
「アフィリエイトURL」は以下のルールで生成可能です。ただし、「商品URL」の部分はURLエンコードされている必要があります。
http://hb.afl.rakuten.co.jp/hgc/[アフィリエイトID]/?pc=[商品URL(PC)]&m=[商品URL(モバイル)]
Error
Error messages are displayed in the form of HTTP status code and its response body
HTTP Status Code | Description | Response body example (JSON) |
---|---|---|
400 | Parameter error (or required parameters were insufficient) |
If applicationId is not set
If keyword is not valid (only 1 character given, etc.)
|
404 | If data not found. |
|
429 | Too many requests |
This error will be displayed if the number of API requests has been exceeded.
|
500 | Internal error in Rakuten Web Service | An internal system error occured. If you continue seeing this message for a long period, please give your inquiry via this link
|
503 | Unavailable due to maintenance or overloaded |
Maintenance (the API name will be displayed in XXX/XXX)
|
Response body format is display in format.
format | Error output example |
---|---|
json |
|
xml |
|