Search API

This method searches the hotel and room inventory available through MescoGo for the requested dates and occupancy.

📍 Endpoint

POST {BaseURL}/api/price/mg-hotel-prices

Property	Value
URI	{BaseURL}/api/price/mg-hotel-prices
Method	POST
Content-Type	application/json

Authorization

Send the Basic Auth header described in Authentication.

📋 Request Parameters

Parameter	Type	Description
CheckIn	String	Accommodation check-in date. Format: YYYY-MM-DD
CheckOut	String	Accommodation check-out date. Format: YYYY-MM-DD
HotelCodes	String	Comma-separated MescoGo hotel codes. Maximum 50 codes per request.
GuestNationality	String	Guest nationality as a two-letter ISO 3166-1 alpha-2 country code. RU is valid; send the guest's actual nationality. Availability, price, and cancellation conditions may vary by nationality.
PaxRooms	Object List	Required room occupancy list. Must contain at least one room. Each item contains Adults, Children, and ChildrenAges.
PaxRooms[].Adults	Integer	Required. Supported range: 1-10 adults per room.
PaxRooms[].Children	Integer	Must match ChildrenAges.length. If there are no children, send Children: 0 and ChildrenAges: [].
PaxRooms[].ChildrenAges	Integer Array	Child ages for the room. Send an empty array when Children is 0.
ResponseTime	Decimal	Required maximum response time requested for the search, in seconds. Must be greater than 0.
IsDetailedResponse	Boolean	To get additional details such as day breakdown and detailed cancellation policies in search response. Default: false
Filters	Object	Filters to narrow down the search response. Send this object even when no filter is needed.
Filters.Refundable	Boolean	Only refundable room requirement. Default: false
Filters.NoOfRooms	Integer	Maximum number of rooms to return per hotel. 0 returns all matching rooms.
Filters.MealType	String	Meal filter. Send All for no meal filter, or one or more meal codes separated by commas. See Board Types.
BookingCode	GUID	Price check is done with the booking code returned as a result of a previously sent price search query

BookingCode Notes

• If BookingCode is empty, the request starts a new search.
• If BookingCode contains a code returned by a previous search for the same API account, the current price and availability are checked for that room.
• A returned room code is valid only until its ValidityDate. Start a new search after it expires.

📤 Example Request (Single Room)

{
  "CheckIn": "2026-12-29",
  "CheckOut": "2026-12-31",
  "HotelCodes": "26090",
  "GuestNationality": "RU",
  "PaxRooms": [
    {
      "Adults": 2,
      "Children": 1,
      "ChildrenAges": [4]
    }
  ],
  "ResponseTime": 1,
  "IsDetailedResponse": true,
  "Filters": {
    "Refundable": false,
    "NoOfRooms": 0,
    "MealType": "All"
  },
  "BookingCode": ""
}

📥 Response Parameters

Parameter	Type	Description
Status	Object	Response status
Status.Code	Integer	API code indicating response status
Status.Description	String	Descriptive message
HotelResult	Array	Information about hotels
HotelResult[].HotelCode	Integer	MescoGo hotel code
HotelResult[].Currency	String	Currency of the returned prices. Prices are returned in USD.
HotelResult[].Rooms	Array	List of bookable rooms

Rooms Structure

Parameter	Type	Description
Name	Array of String	List of room names
RoomId	Integer	Room ID
BookingCode	GUID	Booking code
Inclusion	String	Inclusions
DayRates	Array	Price breakdown for each day of stay at the hotel
BasePrice	Decimal	Room base price
TotalFare	Decimal	Total price of bookable unit
TotalTax	Decimal	Total tax of bookable unit
RoomPromotion	Array	List of promotions on rate
CancelPolicies	Array or null	Detailed cancellation policies. Returned when IsDetailedResponse is true; otherwise this field may be null.
MealType	String	Meal type
IsRefundable	Boolean	Is refundable
WithTransfers	Boolean	Transfer included
Supplements	Array	Section where additional taxes are listed
CustomRow	Decimal	Informational commercial adjustment related to the room rate. It is already included in TotalFare; do not add it again.
ValidityDate	DateTime	Booking code validity date

CancelPolicies Structure

Parameter	Type	Description
FromDate	String	Date and time from which the cancellation penalty applies, based on the hotel's local time. The value is not converted to UTC or the customer's local timezone; use it exactly as returned.
ChargeType	String	Cancellation charge type. Returned values can be percent, amount, nights, or unknown.
CancellationCharge	Decimal	Charge value. Interpret it according to ChargeType; when the type is unknown, do not infer a unit.

Supplements Structure

Parameter	Type	Description
Index	Integer	Indicates rate index
Type	String	Supplement type
Description	String	Supplement details
Price	Decimal	Supplement charges
Currency	String	Currency of supplement charges. Supplement prices are returned in USD.

📥 Example Response

{
  "Status": {
    "Code": 200,
    "Description": "Successful"
  },
  "HotelResult": [
    {
      "HotelCode": 26090,
      "Currency": "USD",
      "Rooms": [
        {
          "Name": ["Triple Room"],
          "RoomId": 0,
          "BookingCode": "00000000-0000-4000-8000-000000000003",
          "Inclusion": "",
          "DayRates": [
            [
              { "BasePrice": 102.1440 },
              { "BasePrice": 102.1440 }
            ]
          ],
          "BasePrice": 102.144,
          "TotalFare": 218.11,
          "TotalTax": 13.82,
          "RoomPromotion": [],
          "CancelPolicies": [
            {
              "FromDate": "2026-12-29T00:00:00",
              "ChargeType": "percent",
              "CancellationCharge": 100
            },
            {
              "FromDate": "2026-12-27T00:00:00",
              "ChargeType": "percent",
              "CancellationCharge": 90
            },
            {
              "FromDate": "2026-12-22T00:00:00",
              "ChargeType": "percent",
              "CancellationCharge": 50
            },
            {
              "FromDate": "2026-12-15T00:00:00",
              "ChargeType": "percent",
              "CancellationCharge": 20
            }
          ],
          "MealType": "FB",
          "IsRefundable": false,
          "Supplements": [
            {
              "Index": 1,
              "Type": "",
              "Description": "City tax of 10% per night (Not included in price)",
              "Price": 13.82,
              "Currency": "USD"
            },
            {
              "Index": 2,
              "Type": "",
              "Description": "Service tax of 8% per night (Included in price)",
              "Price": 11.26,
              "Currency": "USD"
            },
            {
              "Index": 3,
              "Type": "",
              "Description": "Added taxes of 15% per room per night (Included in price)",
              "Price": 22.8,
              "Currency": "USD"
            }
          ],
          "WithTransfers": false,
          "CustomRow": 14.29,
          "ValidityDate": "2026-12-22T09:53:05.3847699+00:00"
        }
      ]
    }
  ]
}

Example data note: The booking code and dates in this example are synthetic and illustrative. Do not copy them as live availability data.

When no matching rooms are available, the response uses the same Status / HotelResult shape with Status.Code 201 and an empty HotelResult array. Validation and processing errors may use a Status object with a body code such as 400, 404, or 500; handle the HTTP status separately from the body status.