Skip to main content

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:

  1. Criteria
  2. Token
  3. 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:

  1. Add the token object to the fields and variables.

  2. 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.

  3. 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

note

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

hotelCodes  *  (String)
Search by hotel codes. These hotel codes are used to perform search.

supplierHotelCodes  *  (String)
Search by hotel codes in supplier s context.

hotelName (String)
Search by hotel name

destinationCodes  *  (String)
Search by destination codes, only search by minimal destinations

countries  *  (Country)
Filter by country

ranks  *  (Int)
Filter by supplier rank

maxSize (Int)
Maxium number of items per page

group (ID)
The supplier s group. Only available if all permissions allowed

supplierCode (ID)
The supplier s unique code

HotelXHotelFilterInput (INPUT_OBJECT)
By default: Logical AND on all given filters. Hotels data are returned only if match condition

AND  *  (undefined)
Logical AND on all given filters.

OR  *  (undefined)
Logical OR on all given filters.

createdAt_in  *  (DateTime)
Return hotels with creation time in given list.

createdAt_not_in  *  (DateTime)
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.

createdAt_lte (DateTime)
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.

createdAt_gte (DateTime)
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.

updatedAt_not_in  *  (DateTime)
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.

updatedAt_lte (DateTime)
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.

updatedAt_gte (DateTime)
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.

deletedAt_not_in  *  (DateTime)
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.

deletedAt_lte (DateTime)
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.

deletedAt_gte (DateTime)
Return hotels with delete time greater than or equal the given value.

country_in (Boolean)
Hotel Country required for all Hotels

category_in (Boolean)
Hotel Category code required for all Hotels

destination_in (Boolean)
Hotel destination required for all Hotels

name_in (Boolean)
Hotel Name required for all Hotels

coordinates_in (Boolean)
Hotel Coordinates required for all Hotels

token (String)
A unique authentication token required for API requests.

Returned Fields

HotelConnection (OBJECT)
HotelList definition

edges (HotelEdge)

node (Hotel)

code  *  (ID)
Hotel ID

hotelData (HotelData)
Hotel data

code  *  (ID)
Internal code.

hotelCode  *  (String)
Code to perform availability.

hotelCodeSupplier (String)
Native supplier hotel code.

giataData (GiataData)
Giata data stored in giata.

id  *  (ID)
Giata System ID.

source  *  (URI)
Giata URL for the hotels of the supplier.

href  *  (URI)
Giata url for the hotel info.

updatedAt  *  (DateTime)
Date of last Giata update for this code.

hotelName (String)
Name of the hotel in the Supplier selected.

categoryCode (String)
Hotel category (for example number of stars).

chainCode (String)
Hotel chain code

exclusiveDeal  *  (Boolean)
Indicates that the Hotel has an Exclusive Deal.

location  *  (Location)
Indicates the location of the hotel

address (String)
Contains Hotel Address

city (String)
Contains the city

zipCode (String)
Contains the zipCode.

country (Country)
Country where is the Hotel.

coordinates (Coordinates)
Geographical coordinates corresponding to a location.

latitude  *  (Float)
Latitude

longitude  *  (Float)
Longitude

closestDestination (DestinationData)
Closest destination

code  *  (ID)
Destination Code

available  *  (Boolean)
Indicates if you can search by destination

destinationLeaf  *  (String)
Returns destination leafs of the destination.

texts  *  (Text)
Contains the destination name

text  *  (String)

language  *  (Language)

closestDestinations  *  (String)
Closest destinations, indicates destinations in proximity

parent (String)
Parent destination code

type (Enum of DestinationType)
Indicates destination type, zone or city
Possible values:
ZONE
CITY
COUNTRY

airports  *  (Airport)
Airports

code  *  (ID)
Airport ID

airportData (AirportData)
Airport data

code  *  (ID)
Airport Code (IATA)

name (String)
The airport s name

adviseMessage  *  (AdviseMessage)
List of messages

code  *  (ID)
AM code: The following codes can be returned:

description  *  (String)
Error description

level  *  (Enum of AdviseMessageLevel)
Indicates the level of importance of the message. Possible values: ERROR, WARN, INFO.
Possible values:
WARN
ERROR
INFO

external (ExternalMessage)
Specify the external message.

code (String)
External code.

message  *  (String)
External message.

correlationID  *  (ID)
Identifier to investigate the cause of the error.

createdAt  *  (DateTime)
Date created

updatedAt  *  (DateTime)
Date updated

state (State)
the state/province of the property

contact (Contact)
Contact contains information about hotel contact.

email (String)
Email

telephone (String)
Telephone

fax (String)
Fax

web (URI)
Web

rank  *  (Int)
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

medias  *  (Media)
Medias

code (String)
Code.

order (String)
Indicates the order priority.

type  *  (Enum of ApplicationAreaType)
Indicates the type of the media.
Possible values:
HOTEL
ROOM
SERVICE
GENERAL

updatedAt  *  (DateTime)
Date updated.

url  *  (URI)
Url.

texts  *  (undefined)
Contains the descriptive.

descriptions  *  (Description)
Descriptions

type  *  (Enum of DescriptionType)
Indicates type of description
Possible values:
ADDITIONAL
AMENITY
ACTIVITY
RESTAURANT
ROOM
GENERAL
POOL
LOCATION
HOW_TO_GET

texts  *  (undefined)
Label

rooms (RoomConnection)
Rooms

edges (RoomEdge)

node (RoomStatic)

code  *  (ID)
Room ID

roomData (RoomData)
Room data

code  *  (ID)
Internal code for checking availability

roomCode  *  (String)
Code of the hotel in the Supplier selected

texts  *  (undefined)
Label

source (String)
Room source

occupancies (OccupancyStatic)
Room occupancies

total (OccupancyRange)
Occupancy Total Pax Range

min (Int)

max (Int)

views  *  (View)
Room views

texts  *  (undefined)
Contains the descriptive of view.

viewCode  *  (String)
Containg the view code

medias  *  (undefined)
Room medias

beds  *  (BedStatic)
Room beds

type (String)
Specifies the bed type

count (Int)
Indicates number of beds in a room

shared (Boolean)
Specifies if the bed is shared or not

area (Area)
Room area in square meters.

allAmenities (HotelXAmenityConnection)
Amenities with mapping

edges  *  (HotelXAmenityEdge)
Amenity edges of amenity connection

node  *  (HotelXAmenity)
Amenity node

code  *  (ID)
Node Id

amenityData (HotelXAmenityData)
Indicates data values of amenity

code  *  (ID)
Amenity code

amenityCode  *  (String)
External amenity code

type  *  (undefined)
Indicates the type of Amenity.

texts  *  (undefined)
Contains the descriptive

value  *  (undefined)
Indicates the amenity s value in different languages

mappings  *  (HotelXMappedCode)
Mappings of amenity codes in different contexts

context  *  (String)
Context of the mapped code

code  *  (String)
Code in context

adviseMessage  *  (undefined)
List of messages

createdAt  *  (DateTime)
Indicates the creation date of the node

updatedAt  *  (DateTime)
Indicates the date of last update of the node

cursor  *  (String)
Edge s cursor

adviseMessage  *  (undefined)
List of messages

createdAt  *  (DateTime)
Date created

updatedAt  *  (DateTime)
Date updated

cursor  *  (String)

token (String)

propertyType (PropertyType)
Indicates property type.

propertyCode (String)
Native supplier property code.

name (String)
PropertyType name

mandatoryFees  *  (MandatoryFee)
Mandatory fees of property

duration (String)
Fee duration

mandatoryFeeCode  *  (String)
Native supplier Mandatry Fee

price  *  (PriceStatic)
Fee price

amount  *  (Float)
Net amount

currency  *  (Currency)
Price curency

scope (String)
The scope of the fee

name (String)
the name of the fee

text (String)
Fee description

included  *  (Boolean)
Indicates if the fee is included in the price

checkIn (CheckInformation)
CheckIn information

instructions  *  (undefined)
CheckIn instructions

specialInstructions  *  (undefined)
CheckIn special instructions

minAge (Int)
Minimal age allowed for doing the checkin

schedule (TimeRange)
The schedule of checkIn

startTime (Time)
the start time of range

endTime (Time)
the end time of range

accesses  *  (String)
Accesses that has this hotel

mappings  *  (undefined)
Mapping codes for this property in various contexts, e.g.: TGX, GIATA,...

adviseMessage  *  (undefined)
List of messages

createdAt  *  (DateTime)
Date created

updatedAt  *  (DateTime)
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:

Search for a specific creation date from a supplier