Hotels
The Hotels Query returns a comprehensive hotel list from a supplier's access, granting you access to all the properties configured by the Seller for a given set of credentials. The returned fields include:
hotelCode
hotelName
giataData
location
allAmenities
medias
descriptions
Query Overview
When creating your hotels query, you have three different inputs to fill based on your specific needs:
- Criteria
- Token
- Filter
1. Criteria
This query offers versatility, with certain fields marked as mandatory (access
) and others as optional (hotelCodes
, countries
, destinationCodes
, etc.). This flexibility empowers you to create a personalized Hotels Query, tailoring the requested fields to your specific needs. Consequently, the response will only include information that is highly relevant to you, streamlining the retrieval process and ensuring the data you receive meets your exact requirements.
{
"criteriaHotels": {
"access": "2",
"hotelCodes": [
"91415"
],
"maxSize": 5
}
}
Mandatory criteria
access
Optional criteria
hotelCodes
(Search by hotel)countries
(Search by country)destinationCodes
(Search by destination)ranks
maxSize
(Paginate response)language
(It requests the language in format "ISO 639-1 lowercase", in case of having information stored in that language, it will return the answer in the requested language.)
2. Token
The Hotel-X API provides paginated responses to handle cases where the number of hotels from the selected supplier exceeds 10000. The default response page contains a maximum of 500 hotels, but you can specify the number of objects returned per page using the maxSize
field in the criteria variable explained before to retrieve between 1 and 10000 hotels.
To include the token in your request, all you need to do is:
-
Add the
token
object to the fields and variables. -
After receiving a response, you will only receive a portion of the full list. To access the next page, simply copy the
token
tag from the response and include it in your next request. This will allow you to obtain a new set of objects in the following response. -
Repeat these steps until the
token
is no longer included in the response, the query will return “Hotels not found”.
Query variables
First, in your hotels query you won't indicate any token
input:
{
"criteriaHotels" : {
"access" : "2",
"maxSize" : 5
},
"token" : ""
}
You will obtain a response with 5 hotels per page:
Response
{
"data": {
"hotelX": {
"hotels": {
"token": "FGluY2x1ZGVfY29udGV4dF91dWlkDnF1ZXJ5VGhlbkZldGNoAhZMN2w2SlZYaVNaaXhYeXQwdm1GWjlBAAAAAAV14HUWeXZ3cU02MkpSbTY3WkF6QzJraWJWZxY2NDJ0Uk1EUFFkZXZZTS1ENDVTd2tBAAAAAAZuWSgWdFZSMzRYUVBUWC1nZ1ltWVRCTjVMZw==",
"edges": [
{
"..."
}
]
}
}
}
}
This token should be used as input in your next hotels query, inside the token
input:
{
"criteriaHotels" : {
"access" : "2",
"maxSize" : 5
},
"token" : "FGluY2x1ZGVfY29udGV4dF91dWlkDnF1ZXJ5VGhlbkZldGNoAhZMN2w2SlZYaVNaaXhYeXQwdm1GWjlBAAAAAAV14HUWeXZ3cU02MkpSbTY3WkF6QzJraWJWZxY2NDJ0Uk1EUFFkZXZZTS1ENDVTd2tBAAAAAAZuWSgWdFZSMzRYUVBUWC1nZ1ltWVRCTjVMZw=="
}
3. Filter
Filter
feature allows for more precise queries. It consists of two types of filters:
-
Date filters: These filters allow searching by dates in which the hotels have been created (
createdAt_in
,createdAt_It
,createdAt_gt
etc.), updated (updatedAt_in
,updatedAt_It
,updatedAt_gt
etc.), or deleted (deletedAt_in
,deletedAt_It
,deletAt_gt
etc.). -
Field filters (boolean: true or false): These filters allow searching hotels that have information in indicated fields, such as country (
country_in
), category (category_in
), destination (destination_in
), name (name_in
), and coordinates (coordinates_in
).
{
"criteriaHotels": {
"access": "2"
},
"token": "",
"filterHotel": {
"createdAt_gt": "2023-01-01T08:58:18.0117911Z"
}
}
Response Considerations
The amount of information and content returned might vary between Sellers.
Hotel-X supports all languages, but receiving hotel descriptions in one or another depends entirely on the languages supported by the Seller.
Know the Total Amount of Properties
To obtain the total number of properties in the list, you can easily add the count
field to your Hotels Query.
Request
query {
hotelX {
hotels(criteria: {access: "2"}) {
count
edges {
Response
{
"data": {
"hotelX": {
"hotels": {
"count": 16,
"edges": [
Receive GIATA Codes
Hotel-X API fully supports GIATA codes in Hotel-X Hotels Query response. Note that GIATA codes are only available at a hotel level.
GIATA information is retrieved in the node giataData
. This information is not returned by default, to activate this feature, open a ticket to our Customer Care team with your GIATA credentials and specified Sellers for activation. Once GIATA is implemented for your account, add giataData
node to your Hotels Query to receive GIATA details in the response.
Request
query {
hotelX {
hotels(criteria: {access: "2"}) {
edges {
cursor
node {
code
hotelData {
hotelCode
hotelName
giataData {
updatedAt
source
href
}
Response
{
"data": {
"hotelX": {
"hotels": {
"edges": [
{
"cursor": "",
"node": {
"code": "",
"hotelData": {
"hotelCode": "66337",
"hotelName": "Hotel Test",
"giataData": "11267",
Mapping
When utilizing the Hotel List Query, you will receive the Seller's native hotel codes. Connecting with a new Seller doesn't always mean that you are interested in the whole hotels portfolio, maybe you are just interested in some specific hotels. Since mapping depends entirely on your side, you can map only those hotels you are interested in.
Additionally, you can upload your own mapping files to our FTP (credentials should be provided by our Customer Care team), and we will use your own hotel codes in the booking flow.
You can find all the necessary information in the mapping section.
Query Inputs
HotelXHotelListInput (INPUT_OBJECT)
access (ID)
Indicates the access
Indicates the access
hotelCodes * (String)
Search by hotel codes. These hotel codes are used to perform search.
Search by hotel codes. These hotel codes are used to perform search.
supplierHotelCodes * (String)
Search by hotel codes in supplier s context.
Search by hotel codes in supplier s context.
hotelName (String)
Search by hotel name
Search by hotel name
destinationCodes * (String)
Search by destination codes, only search by minimal destinations
Search by destination codes, only search by minimal destinations
countries * (Country)
Filter by country
Filter by country
ranks * (Int)
Filter by supplier rank
Filter by supplier rank
maxSize (Int)
Maxium number of items per page
Maxium number of items per page
group (ID)
The supplier s group. Only available if all permissions allowed
The supplier s group. Only available if all permissions allowed
supplierCode (ID)
The supplier s unique code
The supplier s unique code
HotelXHotelFilterInput (INPUT_OBJECT)
By default: Logical AND on all given filters. Hotels data are returned
only if match condition
By default: Logical AND on all given filters. Hotels data are returned only if match condition
AND * (undefined)
Logical AND on all given filters.
Logical AND on all given filters.
OR * (undefined)
Logical OR on all given filters.
Logical OR on all given filters.
createdAt_in * (DateTime)
Return hotels with creation time in given list.
Return hotels with creation time in given list.
createdAt_not_in * (DateTime)
Return hotels with creation time that are not contained in given list.
Return hotels with creation time that are not contained in given list.
createdAt_lt (DateTime)
Return hotels with creation time less than the given value.
Return hotels with creation time less than the given value.
createdAt_lte (DateTime)
Return hotels with creation time less than or equal the given value.
Return hotels with creation time less than or equal the given value.
createdAt_gt (DateTime)
Return hotels with creation time greater than the given value.
Return hotels with creation time greater than the given value.
createdAt_gte (DateTime)
Return hotels with creation time greater than or equal the given value.
Return hotels with creation time greater than or equal the given value.
updatedAt_in * (DateTime)
Return hotels with update time that are contained in given list.
Return hotels with update time that are contained in given list.
updatedAt_not_in * (DateTime)
Return hotels with update time that are not contained in given list.
Return hotels with update time that are not contained in given list.
updatedAt_lt (DateTime)
Return hotels with update time less than the given value.
Return hotels with update time less than the given value.
updatedAt_lte (DateTime)
Return hotels with update time less than or equal the given value.
Return hotels with update time less than or equal the given value.
updatedAt_gt (DateTime)
Return hotels with update time greater than the given value.
Return hotels with update time greater than the given value.
updatedAt_gte (DateTime)
Return hotels with update time greater than or equal the given value.
Return hotels with update time greater than or equal the given value.
deletedAt_in * (DateTime)
Return hotels with delete time that are contained in given list.
Return hotels with delete time that are contained in given list.
deletedAt_not_in * (DateTime)
Return hotels with delete time that are not contained in given list.
Return hotels with delete time that are not contained in given list.
deletedAt_lt (DateTime)
Return hotels with delete time less than the given value.
Return hotels with delete time less than the given value.
deletedAt_lte (DateTime)
Return hotels with delete time less than or equal the given value.
Return hotels with delete time less than or equal the given value.
deletedAt_gt (DateTime)
Return hotels with delete time greater than the given value.
Return hotels with delete time greater than the given value.
deletedAt_gte (DateTime)
Return hotels with delete time greater than or equal the given value.
Return hotels with delete time greater than or equal the given value.
country_in (Boolean)
Hotel Country required for all Hotels
Hotel Country required for all Hotels
category_in (Boolean)
Hotel Category code required for all Hotels
Hotel Category code required for all Hotels
destination_in (Boolean)
Hotel destination required for all Hotels
Hotel destination required for all Hotels
name_in (Boolean)
Hotel Name required for all Hotels
Hotel Name required for all Hotels
coordinates_in (Boolean)
Hotel Coordinates required for all Hotels
Hotel Coordinates required for all Hotels
token (String)
A unique authentication token required for API requests.
A unique authentication token required for API requests.
Returned Fields
HotelConnection (OBJECT)
HotelList definition
HotelList definition
edges (HotelEdge)
node (Hotel)
code * (ID)
Hotel ID
Hotel ID
hotelData (HotelData)
Hotel data
Hotel data
code * (ID)
Internal code.
Internal code.
hotelCode * (String)
Code to perform availability.
Code to perform availability.
hotelCodeSupplier (String)
Native supplier hotel code.
Native supplier hotel code.
giataData (GiataData)
Giata data stored in giata.
Giata data stored in giata.
id * (ID)
Giata System ID.
Giata System ID.
source * (URI)
Giata URL for the hotels of the supplier.
Giata URL for the hotels of the supplier.
href * (URI)
Giata url for the hotel info.
Giata url for the hotel info.
updatedAt * (DateTime)
Date of last Giata update for this code.
Date of last Giata update for this code.
hotelName (String)
Name of the hotel in the Supplier selected.
Name of the hotel in the Supplier selected.
categoryCode (String)
Hotel category (for example number of stars).
Hotel category (for example number of stars).
chainCode (String)
Hotel chain code
Hotel chain code
exclusiveDeal * (Boolean)
Indicates that the Hotel has an Exclusive Deal.
Indicates that the Hotel has an Exclusive Deal.
location * (Location)
Indicates the location of the hotel
Indicates the location of the hotel
address (String)
Contains Hotel Address
Contains Hotel Address
city (String)
Contains the city
Contains the city
zipCode (String)
Contains the zipCode.
Contains the zipCode.
country (Country)
Country where is the Hotel.
Country where is the Hotel.
coordinates (Coordinates)
Geographical coordinates corresponding to a location.
Geographical coordinates corresponding to a location.
latitude * (Float)
Latitude
Latitude
longitude * (Float)
Longitude
Longitude
closestDestination (DestinationData)
Closest destination
Closest destination
code * (ID)
Destination Code
Destination Code
available * (Boolean)
Indicates if you can search by destination
Indicates if you can search by destination
destinationLeaf * (String)
Returns destination leafs of the destination.
Returns destination leafs of the destination.
texts * (Text)
Contains the destination name
Contains the destination name
text * (String)
language * (Language)
closestDestinations * (String)
Closest destinations, indicates destinations in proximity
Closest destinations, indicates destinations in proximity
parent (String)
Parent destination code
Parent destination code
type (Enum of DestinationType)
Indicates destination type, zone or city
Possible values:
ZONE
CITY
COUNTRY
Indicates destination type, zone or city
Possible values:
ZONE
CITY
COUNTRY
airports * (Airport)
Airports
Airports
code * (ID)
Airport ID
Airport ID
airportData (AirportData)
Airport data
Airport data
code * (ID)
Airport Code (IATA)
Airport Code (IATA)
name (String)
The airport s name
The airport s name
adviseMessage * (AdviseMessage)
List of messages
List of messages
code * (ID)
AM code: The following codes can be returned:
AM code: The following codes can be returned:
description * (String)
Error description
Error description
level * (Enum of AdviseMessageLevel)
Indicates the level of importance of the message.
Possible values: ERROR, WARN, INFO.
Possible values:
WARN
ERROR
INFO
Indicates the level of importance of the message. Possible values: ERROR, WARN, INFO.
Possible values:
WARN
ERROR
INFO
external (ExternalMessage)
Specify the external message.
Specify the external message.
code (String)
External code.
External code.
message * (String)
External message.
External message.
correlationID * (ID)
Identifier to investigate the cause of the error.
Identifier to investigate the cause of the error.
createdAt * (DateTime)
Date created
Date created
updatedAt * (DateTime)
Date updated
Date updated
state (State)
the state/province of the property
the state/province of the property
contact (Contact)
Contact contains information about hotel contact.
Contact contains information about hotel contact.
email (String)
Email
telephone (String)
Telephone
Telephone
fax (String)
Fax
Fax
web (URI)
Web
Web
rank * (Int)
Rank indicates the supplier categorization.
Rank indicates the supplier categorization.
cardTypes * (Enum of PaymentCardType)
List of credit cards
Possible values:
VI
AX
BC
CA
CB
CU
DS
DC
T
R
N
L
E
JC
TO
S
EC
EU
TP
OP
ER
XS
O
List of credit cards
Possible values:
VI
AX
BC
CA
CB
CU
DS
DC
T
R
N
L
E
JC
TO
S
EC
EU
TP
OP
ER
XS
O
medias * (Media)
Medias
Medias
code (String)
Code.
Code.
order (String)
Indicates the order priority.
Indicates the order priority.
type * (Enum of ApplicationAreaType)
Indicates the type of the media.
Possible values:
HOTEL
ROOM
SERVICE
GENERAL
Indicates the type of the media.
Possible values:
HOTEL
ROOM
SERVICE
GENERAL
updatedAt * (DateTime)
Date updated.
Date updated.
url * (URI)
Url.
Url.
texts * (undefined)
Contains the descriptive.
Contains the descriptive.
descriptions * (Description)
Descriptions
Descriptions
type * (Enum of DescriptionType)
Indicates type of description
Possible values:
ADDITIONAL
AMENITY
ACTIVITY
RESTAURANT
ROOM
GENERAL
POOL
LOCATION
HOW_TO_GET
Indicates type of description
Possible values:
ADDITIONAL
AMENITY
ACTIVITY
RESTAURANT
ROOM
GENERAL
POOL
LOCATION
HOW_TO_GET
texts * (undefined)
Label
Label
rooms (RoomConnection)
Rooms
Rooms
edges (RoomEdge)
node (RoomStatic)
code * (ID)
Room ID
Room ID
roomData (RoomData)
Room data
Room data
code * (ID)
Internal code for checking availability
Internal code for checking availability
roomCode * (String)
Code of the hotel in the Supplier selected
Code of the hotel in the Supplier selected
texts * (undefined)
Label
Label
source (String)
Room source
Room source
occupancies (OccupancyStatic)
Room occupancies
Room occupancies
total (OccupancyRange)
Occupancy Total Pax Range
Occupancy Total Pax Range
min (Int)
max (Int)
views * (View)
Room views
Room views
texts * (undefined)
Contains the descriptive of view.
Contains the descriptive of view.
viewCode * (String)
Containg the view code
Containg the view code
medias * (undefined)
Room medias
Room medias
beds * (BedStatic)
Room beds
Room beds
type (String)
Specifies the bed type
Specifies the bed type
count (Int)
Indicates number of beds in a room
Indicates number of beds in a room
shared (Boolean)
Specifies if the bed is shared or not
Specifies if the bed is shared or not
area (Area)
Room area in square meters.
Room area in square meters.
allAmenities (HotelXAmenityConnection)
Amenities with mapping
Amenities with mapping
edges * (HotelXAmenityEdge)
Amenity edges of amenity connection
Amenity edges of amenity connection
node * (HotelXAmenity)
Amenity node
Amenity node
code * (ID)
Node Id
Node Id
amenityData (HotelXAmenityData)
Indicates data values of amenity
Indicates data values of amenity
code * (ID)
Amenity code
Amenity code
amenityCode * (String)
External amenity code
External amenity code
type * (undefined)
Indicates the type of Amenity.
Indicates the type of Amenity.
texts * (undefined)
Contains the descriptive
Contains the descriptive
value * (undefined)
Indicates the amenity s value in different languages
Indicates the amenity s value in different languages
mappings * (HotelXMappedCode)
Mappings of amenity codes in different contexts
Mappings of amenity codes in different contexts
context * (String)
Context of the mapped code
Context of the mapped code
code * (String)
Code in context
Code in context
adviseMessage * (undefined)
List of messages
List of messages
createdAt * (DateTime)
Indicates the creation date of the node
Indicates the creation date of the node
updatedAt * (DateTime)
Indicates the date of last update of the node
Indicates the date of last update of the node
cursor * (String)
Edge s cursor
Edge s cursor
adviseMessage * (undefined)
List of messages
List of messages
createdAt * (DateTime)
Date created
Date created
updatedAt * (DateTime)
Date updated
Date updated
cursor * (String)
token (String)
propertyType (PropertyType)
Indicates property type.
Indicates property type.
propertyCode (String)
Native supplier property code.
Native supplier property code.
name (String)
PropertyType name
PropertyType name
mandatoryFees * (MandatoryFee)
Mandatory fees of property
Mandatory fees of property
duration (String)
Fee duration
Fee duration
mandatoryFeeCode * (String)
Native supplier Mandatry Fee
Native supplier Mandatry Fee
price * (PriceStatic)
Fee price
Fee price
amount * (Float)
Net amount
Net amount
currency * (Currency)
Price curency
Price curency
scope (String)
The scope of the fee
The scope of the fee
name (String)
the name of the fee
the name of the fee
text (String)
Fee description
Fee description
included * (Boolean)
Indicates if the fee is included in the price
Indicates if the fee is included in the price
checkIn (CheckInformation)
CheckIn information
CheckIn information
instructions * (undefined)
CheckIn instructions
CheckIn instructions
specialInstructions * (undefined)
CheckIn special instructions
CheckIn special instructions
minAge (Int)
Minimal age allowed for doing the checkin
Minimal age allowed for doing the checkin
schedule (TimeRange)
The schedule of checkIn
The schedule of checkIn
startTime (Time)
the start time of range
the start time of range
endTime (Time)
the end time of range
the end time of range
accesses * (String)
Accesses that has this hotel
Accesses that has this hotel
mappings * (undefined)
Mapping codes for this property in various contexts, e.g.: TGX, GIATA,...
Mapping codes for this property in various contexts, e.g.: TGX, GIATA,...
adviseMessage * (undefined)
List of messages
List of messages
createdAt * (DateTime)
Date created
Date created
updatedAt * (DateTime)
Date updated
Date updated
cursor * (String)
count * (Int)
token (String)
Examples
Search for the complete hotel list from a supplier
Search for a specific country from a supplier
When utilizing the Hotels List Query, for more personalized results, filter specific hotels, countries or destinations based on your interests. For example, to focus solely on the inventory of a Seller in Greece, add the countries
field with "GR" in your criteria. This will ensure you receive hotels directly related to that country, providing you with highly targeted and relevant information.
You would need to apply the same approach for search for specific hotels (hotelCodes
) and destinations (destinationCodes
).
Search for a specific destination from a supplier
For example, if you want to obtain only hotels from "Santorini", you can use the destination code for that zone. In the bellow case, test supplier have determined code "101402" as Santorini, so you need to specify this code in the destinationCodes
field:
Search for a specific hotel code from a supplier
If you want to retrieve the information of specific hotel codes from a supplier, you will need to specify the codes in the hotelCodes
field: