A JSON pull API for partners to pre-download static content, e.g., properties info, room types, images, or facilities.

1 Overview
- 1.1 API endpoints
- 1.2 Sequence diagram
2 Concept
- 2.1 Supported Languages
3 API request settings
- 3.1 API hostname
- 3.2 Authentication
- 3.3 Other HTTP headers
  - 3.3.1 Accept-encoding gzip
- 3.4 Rate limiting
- 3.5 Timeout
4 API Endpoints
- 4.1 GetMyPropertyList
  - 4.1.1 GetMyPropertyListURLSearchParams
  - 4.1.2 GetMyPropertyListResBody
- 4.2 PostProperties
  - 4.2.1 PostPropertiesURLSearchParams
  - 4.2.2 PostPropertiesReqBody
  - 4.2.3 PostPropertiesResBody
- 4.3 GetPropertyFacilities
  - 4.3.1 GetPropertyFacilitiesResBody
- 4.4 GetHotelsChangelog
  - 4.4.1 GetHotelsChangelogURLSearchParams
  - 4.4.2 GetHotelsChangelogResBody
5 API Types and References
- 5.1 Definitions of “req” and “res” columns in API reference table
- 5.2 MyPropertySummary
- 5.3 Pagination
- 5.4 PageItem
- 5.5 PropertyDetails
- 5.6 ImageItem
- 5.7 ImageItemLink
- 5.8 RoomItem
6 Enum Code
- 6.1 CategoryId

Overview

API endpoints

Please find the table below for a summary of endpoints and usage.

Method/Path	Description and characteristics

Method/Path

Description and characteristics

GetMyPropertyList NEW

GET /my-property-list

Paginated API

Retrieves the custom property list that is specifically designed for you.

Returns the property list that RTX made available for you, you should only map the properties returned by this endpoint.

it is highly recommended to update the list weekly
it is a paginated API

PostProperties

POST /properties

Retrieves multiple properties details

Returns property information, e.g., name, room types, images, etc.

supports up to 100 properties on each call
it returns basic information by default, add extends in URL search params to get more details.

Rooms V2

GET /rooms_v2

Retrieves rooms information given a property code

GetPropertyFacilities

GET /property-facilities

Code mapping for facility code

A partner can call this once a week to get the latest facility code, or when the code is missing.

GetChangelog

GET /hotels-changelog

Get the updated property list by a given time frame.

Partner is advised to re-download the property data by using PostProperties

GetRoomsChangelog

GET /rooms-changelog

Get the updated room list by a given time frame.

Partner is advised to re-download the room data by using Room V2

Sequence diagram

The diagram below describes how the endpoints work together

Concept

Supported Languages

E.g: en_US, ar_SA, cs_CZ, da_DK, de_DE, el_GR, es_ES, es_MX, fi_FI, fr_FR, fr_CA, in_ID, it_IT, ja_JP, ko_KR, ms_MY, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN, zh_TW

It will default to en_US in the absence of localized content.

API request settings

API hostname

https://content.rakutentravelxchange.com

*Do take note that we only have single hostname regardless of system environment

Authentication

To access the API users are required to attach given API key into X-Api-Key HTTP header.

Other HTTP headers

Accept-encoding gzip

It is highly recommended to attach accept-encoding: gzip to be able to receive a compressed response which will preserve bandwidth and provide faster retrieval of response.

Rate limiting

This setting varies by client, contact your account manager to know your current limit. 429 Too many requests will be returned as a response if you are over the limit.

Timeout

Typical 60s timeout apply

API Endpoints

GetMyPropertyList

Use this endpoint to get the list of the latest available properties for you.

Path	/my-property-list
Method	GET
URLSearchParams	GetMyPropertyListURLSearchParams
Response body	GetMyPropertyListResBody

GetMyPropertyListURLSearchParams

Field Name	Type	Description

Field Name

Type

Description

since

String

RFC 3339

Request the changes since the specified date and time

e.g: 2020-05-16T03:11:00Z

Default The first record we found

page

int

Page number

e.g: 1 or 3

Default 1

size

int

The number of records to return. Maximum 1000.

e.g: 100 or 333

Default 500

GetMyPropertyList request example

curl --request GET \
  --url 'https://content.rakutentravelxchange.com/my-property-list' \
  --header 'content-type: application/json' \
  --header 'user-agent: <your company name> \
  --header 'x-api-key: <your api key>' 
}'

GetMyPropertyListResBody

Field Name	Type	Description

Field Name

Type

Description

meta

Object

Metadata description about the request, it contains the request GetMyPropertyListURLSearchParams in Object format.

example:

{
  "query": {
    "since": "2020-05-16T03:11:00Z",
    "page": 1,
    "size": 200
  }
}

my_property_list

[<MyPropertySummary>]

Array of <MyPropertySummary> Object. You will have to include the returned property_code into the request body of PostProperties to retrieve the property details.

pagination

Pagination Object

GetMyPropertyList response example

{
  "meta": {
    "query": {
      "since": "2020-05-16T03:11:00Z",
      "page": 1,
      "size": 200
    }
  },
  "my_property_list": [
    {
      "property_code": "wijn",
      "activated_at": "2020-05-16T03:11:00Z",
      "deactivated_at": "2020-05-16T03:11:00Z",
      "is_active": true,
      "last_seen_at": "2020-05-16T03:11:00Z"
    },
    {
      "property_code": "WiJn",
      "activated_at": "2020-05-16T03:11:00Z",
      "deactivated_at": "2020-05-16T03:11:00Z",
      "is_active": true,
      "last_seen_at": "2020-05-16T03:11:00Z"
    }
  ],
  "pagination": {
    "current: {
      "page": 1,
      "size": 200
    },
    // nullable
    "next": {
      "page": 2,
      "size": 200
    }
  }
}

PostProperties

This API helps you download and cache static content.

Path	/properties
Method	POST
URLSearchParams	PostPropertiesURLSearchParams
Request body	PostPropertiesReqBody
Response body	PostPropertiesResBody

PostPropertiesURLSearchParams

Field Name	Type	Description

Field Name

Type

Description

extends

String

A comma-separated value containing additional information to return.

Possible values are:

long – Includes more details are visible, e.g., policy, description, etc.
rooms – Includes property room types. deprecated Please use Rooms V2
facilities – Includes property facilities.
images – Includes all property’s images.

e.g: “long,rooms” “long,images”

Typically you will like to use long,facilities,images to get the complete details.

lang

String

[a-z]{2}-[A-Z]{2}

The language to use for returning the response (if available).

e.g: en-US, ja-JP, zh-CN, …

Default en-US

Translations provided for supported languages are provided on an as-is basis, with no guarantee as to complete accuracy. When there is a discrepancy between the English and translated text for fields such as Hotel Name, Description, etc., the English is to be considered canonical.

PostPropertiesReqBody

Field Name	Type	Description

Field Name

Type

Description

property_codes

[String]

\w{4}

Hotel IDs to be searched for with the other given parameters. Only 100 hotel IDs may be sent in any given request.

e.g: [ “09uu”, “PLPo” ]

PostProperites request example

curl --request POST \
  --url 'https://content.rakutentravelxchange.com/properties?extends=long%2Cimages%2Crooms%2Cfacilities' \
  --header 'content-type: application/json' \
  --header 'user-agent: <your company name> \
  --header 'x-api-key: <your api key>' \
  --data '{
	"property_codes": [
"GiT5", "WijN", "wijn"
	]
}'

PostPropertiesResBody

A JSON object response with a nested key-value pair object, where hotel ID is the key, and the hotel info is the value.

Only valid and available properties are returned.

Field Name	Type	Description

Field Name

Type

Description

<hotel_id>

\w{4}

Hotel IDs to be searched for with the other given parameters. Only 100 hotel IDs may be sent in a given request.

e.g: 09uu

PostProperties response example

{
  "GiT5": {
    "id": "GiT5",
    "name": "Harmonie Embrassee Osaka",
    "address": "7-20, Chayamachi, Kita-Ku, Osaka-Shi, Osaka-Fu, 530-0013",
    "category_id": 1,
    "city": "Osaka",
    "country_code": "JP",
    "country": "",
    "latitude": 34.7074203,
    "longitude": 135.5001367,
    "original_name": "Harmonie Embrassee Osaka",
    "rating": 5,
    "trustyou_review_count": 947,
    "trustyou_rating": 89,
    "trip_advisor_review_count": 0,
    "trip_advisor_rating": 0,
    "approximate_cost": 0,
    "destination_ids": [],
    "region_ids": [],
    "hero_images": [
      {
        "caption": "",
        "hero_image": true,
        "links": {
          "m": {
            "href": "6zDXbKD4.jpg",
            "method": "GET"
          }
        }
      }
    ],
    "is_property_opened": true,
    "images": [
      {
        "caption": "",
        "hero_image": true,
        "links": {
          "m": {
            "href": "6zDXbKD4.jpg",
            "method": "GET"
          }
        }
      },
      {
        "caption": "",
        "hero_image": false,
        "links": {
          "m": {
            "href": "Q9MW3E5Q.jpg",
            "method": "GET"
          }
        }
      },
      ...
    ],
    "description": "<p><b>Property Description</b> <br /> <span>Harmonie Embrassee Osaka is located in Osaka and takes about 3 minute walk from Umeda (Hankyu) Station, near Dotonbori and Universal Studios Japan. It takes about 30 minutes to Osaka International Airport by train. Free WiFi is available in the guest rooms. The hotel also has a home delivery service counter.Guests may borrow hair dryers and kettles at no additional charge (please inquire at the front desk for details). A restaurant offering French cuisine is available for guests. The hotel possesses 40 rooms.</span></p><p><b>Property Access</b> <br /> <span>3-minute walk from Hankyu Umeda Station. 10-minute walk from JR Osaka Station. 7-minute walk from Umeda Station on Subway Midosuji Line.</span> </p>",
    "website": "http://www.h-embrassee.jp/",
    "check_in_time": "15:00:00",
    "check_out_time": "12:00:00",
    "check_in_time_to": "19:00:00",
    "check_out_time_to": null,
    "airport_code": "",
    "chain_code": 0,
    "state_province": null,
    "postal_code": "530-0013",
    "email": "",
    "highest_daily_rate": 0,
    "lowest_daily_rate": 0,
    "payments": [],
    "phone": "06-6376-2255",
    "fax": "",
    "policy": "<p><b>Check In/Check Out Policy</b> <br /> <ul> <li> Check In: 15:00</li><li> Check Out: 12:00</li><li> Last Check In: 24:00</li></ul> </p>",
    "rooms": [
      {
        "beds": {
          "Twin": 1
        },
        "code": "219470",
        "descriptions": "Standard Twin Room with Bathroom and Toilet/Non-Smoking",
        "images": [],
        "size": null
      },
      {
        "beds": {
          "Twin": 1
        },
        "code": "220421",
        "descriptions": "Standard Twin Room with Bathroom and Toilet/Non-Smoking",
        "images": [],
        "size": null
      },
      ...
    ],
    "facilities": [2,3,4]
  },
  "wijn": {
    ...
  }
}

GetPropertyFacilities

Use this endpoint to get the list of facility details corresponding the facility code.

Path	/property-facilities
Method	GET
Response body	GetPropertyFacilitiesResBody

GetPropertyFacilities request example

curl --request GET \
  --url https://content.rakutentravelxchange.com/property-facilities \
  --header 'accept-encoding: gzip' \
  --header 'user-agent: <your identity, e.g., company name>' \
  --header 'x-api-key: <your api key>'

GetPropertyFacilitiesResBody

Responses in a JSON array with nested facility object describe below.

Field Name	Type	Description

Field Name

Type

Description

code

Integer

The facility code that partner retrieved it from PostProperties endpoint

e.g.: 3026

description

String

The label of the facility

e.g.: Outdoor swimming pool

is_for_room

Boolean

Indicated the same facility can use as a room facility.

Work-in-progress; do not use this.

GetPropertyFacilities response example

[
  {
    "code": 1,
    "description": "Chinese restaurant",
    "is_for_room": false
  },
  {
    "code": 2,
    "description": "Western restaurant",
    "is_for_room": false
  },
  {
    "code": 3,
    "description": "Café",
    "is_for_room": false
  },
  {
    "code": 5,
    "description": "Bar",
    "is_for_room": false
  },
  ....
]

GetHotelsChangelog

Use this endpoint to check the property’s details updates

Path	/hotels-changelog
Method	GET
URLSearchParams	GetHotelsChangelogURLSearchParams
Response body	GetHotelsChangelogResBody

GetHotelsChangelogURLSearchParams

Field Name	Type	Description

Field Name

Type

Description

updated_at
required

String

RFC 3339

Request the changes since. Only valid for the last 30days.

e.g: 2020-05-16T03:11:00Z

GetHotelsChangelog request example

curl --request GET \
  --url 'https://content.rakutentravelxchange.com/hotels-changelog?updated_at=2020-05-27T23%3A59%3A59%2B08%3A00' \
  --header 'accept-encoding: gzip' \
  --header 'content-type: application/json' \
  --header 'user-agent: <your company name>' \
  --header 'x-api-key: <your api key>'

GetHotelsChangelogResBody

Field Name	Type	Description

Field Name	Type	Description
data.items	[<int>] \| nullable	Collection of a list of property codes that use conjunctions with PostProperties endpoint to get the latest property details.

GetHotelsChangelog response example

{
  "data": {
    "items": [
      "9CPH",
      "rts1",
      "pbcs",
      "bk60",
      "aRuS"
    ]
  }
}

API Types and References

Definitions of “req” and “res” columns in API reference table

Req (request), represents the user is using the JSON property in the HTTP request body.

Res (response), represents the user is handling the JSON property in the HTTP response body.

Value	Req	Res

Value	Req	Res
R	Required The JSON property is required in the request.	Always visible The JSON property is always visible in the response.
C	Conditional Required The JSON property is conditionally required in the request. Check the JSON property for the condition.	n.a
O	Optional It’s optional in the request, in most cases the default value will be used.	Omit empty The JSON property will not be responded if it has an empty value.
	n.a	n.a

MyPropertySummary

Field Name	req	res	Type	Description

Field Name	req	res	Type	Description
property_code	-	R	String	Property codes. (This is the same as Hotel ID in another document, we only single Hotel ID, case sensitive hotel ID) e.g: 09uu
is_active		R	Boolean	If the property is active for you `true` – active and available for you `false` – inactive and no longer available for you, usually this happens to property that previously available. Note: Property has `is_active` = `false` might revert to `true` in your next GetMyPropertyList request.
activated_at	-	R	String RFC 3339	When the property available for you. e.g: 2020-05-16T03:11:00Z Default `The first available date`
deactivated_at	-	R	String \| Null RFC 3339 Nullable	When the property stop available for you. e.g: 2020-05-16T03:11:00Z Default `null`
last_seen_at		R	String \| Null RFC 3339 Nullable	Work-in-progress; do not use this. When was the last time the property was included in a search request. The data is not realtime and potential delay up to a day. `null` – We never found the property in the search, partner should check if the property has been mapped. e.g: 2020-05-16T03:11:00Z Default `null`

Pagination

Field Name	req	res	Type	Description

Field Name

req

res

Type

Description

current

-

R

Page Object of the current page.

example:

{
  "page": 1,
  "size": 200
}

next

-

R

<PageItem> | Null

Nullable

Page Object of the next page. If this is not null please continue to request with page and size.

example:

{
  "page": 33,
  "size": 200
}

PageItem

Field Name	req	res	Type	Description

Field Name

req

res

Type

Description

page

-

R

int

Page number

e.g: 1 or 33

size

-

R

int

The number of records intended to return. Maximum 1000.

e.g: 100 or 333

Default 500

PropertyDetails

Field Name	req	res	Type	Description

Field Name	res	Type	Description
id	R	String [a-zA-Z0-9]{4}	Case sensitive hotel IDs. Use it together with shopping API to get hotel availability. e.g: WijN
name	R	String	Name of the property/hotel. e.g: My Harmony Embrassee Osaka
address	R	String	Property’s address
category_id	R	<CategoryId>	Property category. e.g: 1
city	R	String	Property’s city e.g: Osaka
country_code	R	String ISO-3166 alpha 2	Property’s country code in ISO-3166 alpha 2 e.g: SG, JP https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes
country	R	String	Property’s country name Deprecated; do not use this. Instead, retrieve the name by using country_code above.
latitude	R	Float	Property’s latitude e.g: 34.7074203
longitude	R	Float	Property’s longitude e.g: 135.5001367
rating	R	Float	Property’s star rating e.g: 3.5
original_name	R	String	Deprecated; do not use this.
trustyou_review_count	R	Integer	Property’s TrustYou review count.
trustyou_rating	R	Integer	Property’s TrustYou Rating
trip_advisor_review_count	R	Integer	Deprecated; do not use this.
trip_advisor_rating	R	Integer	Deprecated; do not use this.
approximate_cost	R	Float	Deprecated; do not use this.
destination_ids	R	[<int>]	Deprecated; do not use this.
region_ids	R	[<int>]	Property’s regions id. Note: Might response empty array `[]`
hero_images	R	[<ImageItem>]	List of property primary images e.g.: `[ { "caption": "", "hero_image": true, "links": { "m": { "href": "6zDXbKD4.jpg", "method": "GET" } } } ]` Note: it might be an empty array, i.e: `[]` if the property has no primary images.
images	R	[<ImageItem>]	List of property images. (Hero images will be excluded) e.g.: `[ { "caption": "", "hero_image": false, "links": { "m": { "href": "7Ybk0rp4.jpg", "method": "GET" } } }, ... ]` Note: Available by includes `images` or `long` in `extends`, refer to PostPropertiesURLSearchParams for more info. Note: it might be an empty array, i.e: `[]` if the property has no images.
description	R	Text	Property’s description. e.g.: “<p><b>Property Description</b> <br /> <span>Harmonie Embrassee Osaka is located in Osaka and takes about 3 minute walk from Umeda (Hankyu) Station, near Dotonbori and Universal Studios Japan. It takes about 30 minutes to Osaka International Airport by train. Free WiFi is available in the guest rooms. The hotel also has a home delivery service counter.Guests may borrow hair dryers and kettles at no additional charge (please inquire at the front desk for details). A restaurant offering French cuisine is available for guests. The hotel possesses 40 rooms.</span></p><p><b>Property Access</b> <br /> <span>3-minute walk from Hankyu Umeda Station. 10-minute walk from JR Osaka Station. 7-minute walk from Umeda Station on Subway Midosuji Line.</span> </p>” Note: it might contain basic HTML tag for style purpose, i.e., `<b>`, `<span>`, `<p>`, `<br />` Note: Available by includes `long` in `extends`, refer to PostPropertiesURLSearchParams for more info.
website	R	String	Property’s website Note: Available by includes `long` in `extends`, refer to PostPropertiesURLSearchParams for more info.
check_in_time	R	String	Property’s check-in time start e.g: 15:11:00 Note: Available by includes `long` in `extends`, refer to PostPropertiesURLSearchParams for more info.
check_in_time_to	R	String	Property’s check-in time end e.g: 19:11:00 Note: Available by includes `long` in `extends`, refer to PostPropertiesURLSearchParams for more info.
check_out_time	R	String	Property’s check-out time start e.g: 11:11:00 Note: Available by includes `long` in `extends`, refer to PostPropertiesURLSearchParams for more info.
check_out_time_to	R	String

Content API

Overview

API endpoints

Paginated API

Returns the property list that RTX made available for you, you should only map the properties returned by this endpoint.

Returns property information, e.g., name, room types, images, etc.

A partner can call this once a week to get the latest facility code, or when the code is missing.

Partner is advised to re-download the property data by using PostProperties

Partner is advised to re-download the room data by using Room V2

Sequence diagram

The diagram below describes how the endpoints work together

Concept

Supported Languages

API request settings

API hostname

*Do take note that we only have single hostname regardless of system environment

Authentication

Other HTTP headers

Accept-encoding gzip

Rate limiting

Timeout

API Endpoints

GetMyPropertyList

GetMyPropertyListURLSearchParams

GetMyPropertyList request example

GetMyPropertyListResBody

GetMyPropertyList response example

PostProperties

PostPropertiesURLSearchParams

PostPropertiesReqBody

PostProperites request example

PostPropertiesResBody

PostProperties response example

GetPropertyFacilities

GetPropertyFacilities request example

GetPropertyFacilitiesResBody

GetPropertyFacilities response example

GetHotelsChangelog

GetHotelsChangelogURLSearchParams

GetHotelsChangelog request example

GetHotelsChangelogResBody

GetHotelsChangelog response example

API Types and References

Definitions of “req” and “res” columns in API reference table

MyPropertySummary

Pagination

PageItem

PropertyDetails