Best practices: Booking queries by searchType

How to improve your queries by search type using metadata's information

When you want to retrieve bookings, you send a query "booking" to our system. There are two search types that determine how we search the supplier's system. The type of search is chosen by the input typeSearch: BookingCriteriaType.

 

References

If you choose REFERENCES, you have to fill some of references node elements or indicate a bookingID.

Using BookingID

If you want to retrieve a single booking that you got the bookingID from the previous Book operation from this field of response:

That node allows you to indicate only this field in HotelCriteriaBookingInput (and REFERENCES in typeSearch).

 

Example

Get BookingID from Book response

{
  "data": {
    "hotelX": {
      "book": {
        "booking": {
          "reference": {
          "client": "clientReferenceTest",
          "supplier": "supplierReferenceTest",
            "bookingID": "bookindIDTest"
          },
          "price": {
            "currency": "EUR",
            "net": 800,
            "gross": 800,
          "binding": false
        },
        "status": "OK",
        },
        "errors": null,
        "warnings": null
      }
    }
  }
}

Insert it into bookingID in HotelCriteriaBookingInput and add the client (if the access is test access, you have to indicate testMode: true)

{
    "criteriaBooking": {
      "bookingID": "bookindIDTest",
        "typeSearch": "REFERENCES"
  },
"settings": {
"client": "myclient"
}
}

 

And that's all 😀

Without using BookingID

If you want to retrieve various bookings that you have their references, you have to fill the node references: CriteriaBookingReferencesInput

 

How you can see, that three fields are mandatory ('!'). The hotelCode and the currency must be filled with the hotelCode in supplier context and the currency in standard ISO 4217 codes. References element is mandatory too, and can have more than one BookReferenceInput.

These three fields from BookingReferenceInput are optional, but depending on the supplier, it can be mandatory or optional.

 

How can you know which input/s you have to fill depending on supplier? Using metadata query with the supplierCode.

Query

{
  hotelX {
    metadata(criteria: {supplierCodes: ["supplierCode"]}, relay: {}) {
      adviseMessage {
        code
        level
        description
      }
      edges {
      node {
          metadataData {
            supplierCode
            booking {
              queryableBySupplierReference {
                reviewDate
                value
              }
              queryableByClientReference {
                reviewDate
                value
              }
              requiresCheckInDateInReferencesSearchType {
                reviewDate
                value
              }
              requiresCheckOutDateInReferencesSearchType {
                reviewDate
                value
              }
              requiresCheckInDateInReferencesSearchType {
                reviewDate
                value
              }
            }
          }
        }
      }
    }
  }
}

Please, note that in this example, we are using inline variables. You can (as the booking examples) declare variables like "criteriaBooking" and send it via parameter to query. GraphQL variables.

Response

{
  "data": {
    "hotelX": {
      "metadata": {
        "adviseMessage": null,
        "edges": [
          {
          "node": {
              "metadataData": {
              "supplierCode": "supplierCode",
                "booking": {
                  "queryableBySupplierReference": {
                    "reviewDate": "2018-12-27",
                    "value": true
                  },
                  "queryableByClientReference": {
                    "reviewDate": "2018-12-27",
                    "value": true
                  },
                  "requiresCheckInDateInReferences": {
                    "reviewDate": "2021-10-11",
                    "value": false
                  },
                  "requiresCheckOutDateInReferences": {
                    "reviewDate": "2021-10-11",
                    "value": false
                  },
                  "requiresReservationDateInReferences": {
                    "reviewDate": "2021-10-11",
                    "value": false
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

 

"queryableBy*" fields indicate that the supplier allows search by this fields.

"requires*" fields indicate that is mandatory for the supplier's API, receive this information in the query.

"value" indicates if that supplier requires or allows the indicated field.

"reviewDate" indicates last time this value has been checked their correctness against supplier.

 

Note: if you are not using bookingID input, you have to indicate the accessCode in the HotelCriteriaBookingInput. Language is optional, but, for best results, please indicate it.

Dates 

If you want to retrieve all the bookings between a date range, you have to use this query.

Let's see the query fields that you have to fill.

 

Start and End date fields indicate a date range and are mandatory. Example: 2022-01-13 to 2022-10-01 as always, complying ISO 8601 (yyyy-MM-dd). DateType field indicates if the dates  are referring to check-in date or booking date. 

 

Example

{
  "criteriaBooking": {
  "accessCode": "0",
    "language": "en",
    "typeSearch": "DATES",
    "dates": {
      "dateType": "ARRIVAL",
    "start": "2022-01-13",
    "end": "2022-10-01"
    }
  }
}

 

Please note that this is only criteria variable, you have to include settings in your request too.

 

How to know if a supplier allows search by check-in and/or booking date?

By using metadata query with supplierCode.

Query

{
  hotelX {
    metadata(criteria: {supplierCodes: ["supplierCode"]}, relay: {}) {
      adviseMessage {
        code
        level
        description
      }
      edges {
      node {
          metadataData {
            supplierCode
            booking {
              queryableByCreationDate {
                reviewDate
                value
              }
              queryableByCheckinDate {
                reviewDate
                value
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "hotelX": {
      "metadata": {
        "adviseMessage": null,
        "edges": [
          {
          "node": {
              "metadataData": {
              "supplierCode": "supplierCode",
                "booking": {
                  "queryableByCreationDate": {
                  "reviewDate": "2022-01-13",
                  "value": true
                  },
                  "queryableByCheckinDate": {
                  "reviewDate": "2022-10-01",
                    "value": false
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

In that example, metadata inform us that this supplier only allows search by booking creation date (booking date), so we have to select dateType: BOOKING

{
  "criteriaBooking": {
    "accessCode": "0",
    "language": "en",
    "typeSearch": "DATES",
    "dates": {
    "dateType": "BOOKING",
      "start": "2022-01-13",
      "end": "2022-10-01"
    }
  }
}

Note: if you are not using bookingID input, you have to indicate the accessCode in the HotelCriteriaBookingInput. Language is optional, but, for best results, please indicate it.