Lodging Listings API

The Lodging Listings API allows travellers on your website to search Expedia lodging inventory by Location Keyword, Region ID, Lat/Long, or Hotel ID(s) and return up to 1,000 offers per response. Travellers will then be able to deeplink from your website to the Expedia website to complete their travel booking.

How to make a Lodging Listings API call

Request Url

curl https://apim.expedia.com/hotels/listings

Required Headers

Accept: application/vnd.exp-hotel.v3+json
Key: Expedia API key
Authorization: More info on Authorization String Creation
Partner-Transaction-Id: Partner TransactionID String

Optional Headers

Accept-Encoding: gzip

Request Parameter

Minimum request parameters

Search Type - You can make a request using one of the following types.
- Search by Hotel ID's
- Search by Latitude & Longitude
- Search by Location Keyword
- Search by Expedia Region ID
checkIn & checkOut

Parameter	Sample	Description
ecomHotelIds	28082,11133	Comma-separated list of Expedia hotel IDs. There can be no spaces between parameters.
geoLocation	40.714269,-74.005973	Use latitude and longitude (separated by a comma) to represent the search center: positive for north latitude and east longitude, negative for south latitude and west longitude.
locationKeyword	seattle	A keyword search for a location. The keyword can be a city, address, airport or a landmark.
regionIds	8816, 1234, 319626202325190073	Comma-separated list of Expedia Region IDs. Search returns set of all hotels in the combined regions.
checkIn	2025-10-01	CheckIn date in YYYY-MM-DD format.
checkOut	2025-10-02	CheckOut date in YYYY-MM-DD format.

Note: If count of adults is not specified, it defaults to 2.

The parameters geoLocation, locationKeyword, regionIds can be used in combination with the radius and unit parameters.

Example Request for Date Search:

Search by Hotel ID's:

curl https://apim.expedia.com/hotels/listings?ecomHotelIds=28082,11133&checkIn=2025-10-01&checkOut=2025-10-02 \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Search by Latitude & Longitude:

curl https://apim.expedia.com/hotels/listings?geoLocation=40.714269,-74.005973&checkIn=2025-10-01&checkOut=2025-10-02 \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Search by city, address, airport or landmark.:

curl https://apim.expedia.com/hotels/listings?locationKeyword=seattle&checkIn=2025-10-01&checkOut=2025-10-02 \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Search by Expedia Region ID:

curl https://apim.expedia.com/hotels/listings?regionId=8816,1234,319626202325190073&checkIn=2025-10-01&checkOut=2025-10-02 \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Example Request for Dateless Search:

If a check-in check-out date is not specified, a dateless search is initiated. The price returned is for comparison only and should NOT be presented as bookable.

curl https://apim.expedia.com/hotels/listings?locationKeyword=seattle \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Example request for a family trip:

curl https://apim.expedia.com/hotels/listings?locationKeyword=seattle&checkIn=2025-10-01&checkOut=2025-10-02&room1.adults=2&room1.childAges=3,6&room2.adults=1 \
-H 'Accept: application/vnd.exp-hotel.v3+json' \
-H 'Partner-Transaction-Id: ••••••' \
-H 'Key: ••••••' \
-H 'Authorization: ••••••'

Note:

Rooms (maximum of 8) can have more than 1 adult or children in them. example room1.adults=2&room1.childAges=3,6 means 2 adults and 2 children (3 years old and 6 years old) in room 1.

Filter Parameters

We recommend using filters to only retrieve the data you need for better latency and smaller payloads

Parameter	Sample	Description
minStarRating	3.0	The minimum star rating for hotels returned in the response.
maxStarRating	5.0	The maximum star rating for hotels returned in the response.
smokingPreference	smoking	Specifies smoking preference. Allowed values are: smoking, nonsmoking, both
freeCancellation	true	Specifies whether to return only free cancelable room rates in the search results.
travelWithPets	true	Indicates if the search should include pet-friendly properties.
links	WD	Comma-separated list to specify the types of deep links. WD (link to Web Details site), WS (link to Web Search Result page), WEB (include all website links)
radius	100	The size of the search radius around a specified point when searching by either geoLocation or by locationKeyword. radius must be less than 200 km or 124 mi.
unit	km	The unit of measure for searches performed via locationKeyword or geoLocation.

Response

A successful response returns the following data:

{
    "Count": 10,
    "TotalHotelCount": 1000,
    "TransactionId": "186c782a-16a3-42af-8898-d3a744439554",
    ...
    "Hotels": [
        {
            ...
            "Links": {
                "WebSearchResult": {
                    "Method": "GET",
                    "Href": "https://www.expedia.com/Hotel-Search?mpd=USD&tpid=1&mpe=1744119404&endDate=2025-05-03&adults=2&mpn=113176254&mpm=83&locale=en_US&chid=186c782a-16a3-42af-8898-d3a744439554&eapid=0&currency=USD&rateplanid=00004fa186b21bf34d56a5ce360c3a55a85b&selected=113176254&startDate=2025-05-01&mpb=419.68&mpa=196.00"
                }
            },
            "RoomTypes": [
                {
                    "Price": {
                        ...
                    },
                    "Links": {
                        "WebDetails": {
                            "Method": "GET",
                            "Href": "https://www.expedia.com/Hotel.h113176254.Hotel-Information?mdpcid=US.DIRECT.GENAIPARTNER1&rm1=a2&chid=186c782a-16a3-42af-8898-d3a744439554&tpid=1&eapid=0&currency=USD&langid=1033&rateplanid=00004fa186b21bf34d56a5ce360c3a55a85b&regionId=553248635975749111&chkin=2025-05-01&chkout=2025-05-03&mpa=196.00&mpb=419.68&mpd=USD&mpe=1744119404&mpm=83"
                        }
                    }
                }
            ]
        }
    ]
}

Note:

You can use the link to redirect a traveler to Expedia.

Error Response

{
    "Errors": [
        {
            "Code": "MISSING_CHECKIN_OR_CHECKOUT",
            "Description": "Either checkIn or checkOut is missing. Please specify checkIn and checkOut together."
        }
    ],
    "TransactionId": "7d806ae9-1466-4e4b-9ed8-4102c830db03"
}

Full list of possible error codes and error details:

Common Error Codes

HTTP Status Code	Error Code	Error Response	Cause
500	APPLICATION_ERROR	Application error.	Application error.
400	MULTIPLE_AMBIGUOUS_LOCATION	More than one location found.	More than one winners found for locationKeyword search.
200	NO_RESULTS_FOUND	Sorry, your query completed successfully, but did not return any inventory. Please adjust your search parameters and try again.	No hotel found.
400	INVALID_LOCATION_KEYWORD	The locationKeyword is missing.	The locationKeyword should not be empty for a locationKeyword search.
400	COMBINED_HOTEL_SELECT_CRITERIA	Combined hotel search is not supported. Please specify either one of the following search criteria:[geoLocation, regionIds, ecomHotelIds, hcomHotelIds, locationKeyword, hnk, offerId].	Combined search is not supported.
400	NO_HOTEL_SELECT_CRITERIA	No hotel search criteria specified. Available options are:[geoLocation, regionIds, ecomHotelIds, hcomHotelIds, locationKeyword, hnk, offerId].	No hotel search criteria is specified.
400	INVALID_ECOMHOTELIDS	The ecomHotelIds is invalid. Which should be comma separated list of Expedia hotel IDs.	Please specify correct Expedia hotel IDs. Available Expedia hotel ID list could be found in Related Links section below.
400	TOO_MANY_HOTEL_IDS	Too many hotel IDs. Please specify up to 1000 hotel IDs in ecomHotelIds or hcomHotelIds.	Requested too many hotels.
400	INVALID_GEOLOCATION	The format of geoLocation is invalid. Please specify latitude and longitude separated by comma.	The format of geoLocation should be like 40.764458,-73.968852.
400	LONGITUDE_OUT_OF_RANGE	The longitude is out of range. Please specify longitude between -180.000000 and 180.000000.	The longitude is out of range.
400	LATITUDE_OUT_OF_RANGE	The latitude is out of range. Please specify latitude between -90.000000 and 90.000000.	The latitude is out of range.
400	INVALID_RADIUS	The radius is invalid. Allowed value is a number.	The radius should be like 2.34.
400	RADIUS_OUT_OF_RANGE	The radius is out of range. Allowed range is from 0 to 200km / 124mi.	The radius is out of range.
400	INVALID_UNIT	The unit is invalid. Allowed options are mi and km.	The unit is invalid. Allowed options are mi and km.
400	INVALID_REGION_ID	The regionIds is invalid. Please specify comma separated list of Expedia region IDs.	Please specify comma separated list of Expedia region IDs. You can find a link to the complete list of Expedia Region IDs in the Related Links section at the bottom of the page.
400	UNSUPPORTED_REGION_ID	RegionIds:[%s] are not supported.	Please check the regionid whether in supported region ids list. Download lists of supported Expedia Region IDs.
400	TOO_MANY_REGION_IDS	Too many regionIds. Please specify up to 10 region IDs.	Request too many regions.
400	MISSING_CHECKIN_OR_CHECKOUT	Either checkIn or checkOut is missing. Please specify checkIn and checkOut together.	Please specify both checkIn and checkOut together.
400	INVALID_CHECKIN	The checkIn is in invalid. The format should be 'YYYY-MM-DD'.	The format of checkIn is invalid.
400	INVALID_CHECKOUT	The checkOut is invalid. The format should be 'YYYY-MM-DD'.	The format of checkOut is invalid.
400	CHECKOUT_EARLIER_THAN_CHECKIN	The checkout date must occur after checkin date.	The checkout date must occur after checkin date.
400	CHECKIN_IN_THE_PAST	The checkIn should not be in the past.	The checkIn should not be in the past.
400	SEARCH_WINDOW_OUT_OF_RANGE	Search window is too large. Maximum length of stay is 28 days.	Search window is too large.
400	CHECKOUT_OUT_OF_RANGE	The checkOut is out of range. Checkout date can only occur up to 500 days in the future.	The checkOut is out of range.
400	INVALID_ALL_ROOM_TYPES	The allRoomTypes is invalid. Allowed options are true and false.	The allRoomTypes is invalid.
400	INVALID_LOCALE	The locale is invalid. The locale should be two-letter language code and two-letter region code connected with '_'.	The format of Locale should be like en_US.
400	UNSUPPORTED_LOCALE	The requested locale is not supported.	The given locale is not supported. You can find a link to the complete list of Supported Locales in the Related Links section at the bottom of the page.
400	INVALID_CURRENCY	The currency is invalid. The currency should be a standard ISO 3 letter currency code	The format of currency is not correct.
400	UNSUPPORTED_CURRENCY	The currency is invalid. The requested currency is not supported.	The given currency is not supported.
400	TOO_MANY_ROOMS	Requested too many rooms. Please search up to 8 rooms.	Requested too many rooms.
400	INVALID_ADULTS	Invalid adult number detected. Allowed value is a number.	Please specify correct adult number.
400	ADULTS_OUT_OF_RANGE	Too many adults. The number of adults should not be greater than 14.	Requested too many adults.
400	ROOM_NUMBER_NOT_IN_SEQUENTIAL	Room numbers of adults invalid. Room numbers should be in numeric sequential and start from 1.	Please specify adult number for each desired room. For example, do not specify room1.adults=2&room3.adults=3 only without specifying room2.adults.
400	INVALID_ROOM_OCCUPANTS	Only childAges specified. Adults info is mandatory for each room.	Children should be accompanied by adults for each room.
400	INVALID_CHILDAGES	Invalid child occupants detected. Each child age should be a number of less than 17 and child count of any room should be less than 6.	Child age is not a number, or child age is out of range, or children number exceeded the maximum allowed number.
400	INVALID_LINKS	The links is invalid. The links could be any set of WD, WS, AD, WEB, API separated by comma.	Please specify correct links.
400	INVALID_SOURCE	The source is invalid. Allowed options are [browser, mobileapp].	The source is invalid.
400	INVALID_LIMIT	The limit is invalid. Please specify an integer grater than 0.	The limit is invalid.
400	INVALID_IMAGE_SIZES	Invalid imageSizes. Allowed values are t,s,b,y,z.	The imageSizes is invalid.
400	INVALID_CLIENT_KEY	Invalid client key: %s.	Key in request header is invalid or too many Keys in header.
400	INVALID_ACCEPT	Please provide a valid Accept header.	Accept in request header is invalid or too many Accepts in header.
400	INVALID_PARTNER_TRANSACTION_ID	Partner-Transaction-Id is missing.	Partner-Transaction-Id in request header is empty.
400	INVALID_RATE_PLAN_TYPE	The ratePlanType is invalid. Allowed options are 'package', 'standalone'	The ratePlanType is invalid.
400	INVALID_PROPERTY_TYPE_IDS	The includedPropertyTpyeIds/excludedPropertyTypeIds is invalid. Which should be comma separated list of integer numbers.	includedPropertyTpyeIds/excludedPropertyTypeIds in request are contains not integer character or integers are not separated by comma.
400	SORT_TYPE_INVALID	SortType is either missing or is in an invalid format. SortType must be one of the following: price, avgrate, starrating, guestrating, deals, hotelname, distance, totalpricewithfees.	The sortType is invalid.
400	SORT_ORDER_INVALID	SortOrder is either missing or is in an invalid format. SortOrder must be one of the following: 'asc', 'desc'.	The sortOrder is invalid.
400	INVALID_CONTENT_DETAILS	Invalid contentDetails. Allowed values are high,medium,lowest,low.	The contentDetails is invalid.
400	INVALID_GROUPED_AMENITIES	The groupedAmenities is invalid. Allowed values are true and false.	The groupedAmenities is invalid.
400	INVALID_AVAIL_ONLY	The availonly is either missing or is in an invalid format. Allowed values are true and false.	The availOnly is invalid.
400	INVALID_RATE_TYPE	The ratetype in request is invalid. Allowed options are 'payonline', 'payhotel', 'all'.	The ratetype is invalid.
400	INVALID_QUERY_TEXT	The queryText in request is empty.	The queryText in request is empty.
400	INVALID_SMOKING_PREFERENCE	The smokingPreference in request is invalid. Allowed options are 'smoking', 'nonsmoking', 'both'.	The smokingPreference is invalid.
400	MIN_STAR_RATING_GREATER_THAN_MAX_STAR_RATING	The maxStarRating can not be less than minStartRating.	The maxStarRating can not be less than minStartRating.
400	INVALID_MAX_STAR_RATING	The maxStarRating in request is either missing or is in an invalid format. Allowed values are: 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0 .	The maxStarRating is invalid.
400	INVALID_MIN_STAR_RATING	The minStarRating in request is either missing or is in an invalid format. Allowed values are: 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0	The minStarRating is invalid.
400	INVALID_PROPERTYPE_TYPE_FILTER	The propertyType filter is invalid. includedPropertyTypeIds and excludedPropertyTypeIds cannot both be specified.	The request parameter contains both of includedPropertyTypeIds and excludedPropertyTypeIds.
400	INVALID_BLOCK_FULL_DEPOSIT_RATEPLANS	The blockFullDepositRateplans is either missing or is in an invalid format. Allowed values are true and false.	The blockFullDepositRateplans is invalid.

Understanding how handle errors: Error Handling.

You will get an ambiguous error response when multiple locations match a locationKeyword search.

When you search for a locationKeyword that refers to one or more global locations, the API will ask you to clarify which location you'd like to search, then you can choose the right one and call Lodging Listings API again.

{
      "Errors": [
          {
              "Code": "AMBIGUOUS_LOCATION",
              "DetailCode": "MULTIPLE_AMBIGUOUS_LOCATION",
              "Description": "More than one location found",
              "LocationKeyword": "dublin",
              "LocationOptions": [
                  {
                      "Type": "MULTICITY",
                      "RegionId": "178256",
                      "ShortName": "Dublin (and vicinity)",
                      "AirportCode": "DUB",
                      "Address": "Dublin (and vicinity), Ireland",
                      "Country": {
                          "Name": "Ireland",
                          "IsoCode2": "IE",
                          "IsoCode3": "IRL"
                      },
                      "GeoLocation": {
                          "Latitude": "53.34402",
                          "Longitude": "-6.26146"
                      }
                  },
  
      ...
                  {
                      "Type": "POI",
                      "RegionId": "553248621563220238",
                      "ShortName": "Market On Madison",
                      "AirportCode": "MCN",
                      "Address": "Market On Madison, Dublin, Georgia, United States of America",
                      "Country": {
                          "Name": "United States of America",
                          "IsoCode2": "US",
                          "IsoCode3": "USA"
                      },
                      "GeoLocation": {
                          "Latitude": "32.539313",
                          "Longitude": "-82.902537"
                      }
                  }
              ]
          }
      ],
      "TransactionId": "cc026998-5e61-4613-a086-7c725def7eea"
  }

Next Steps

Here, you can explore the endpoint definitions for this API, then go to the API Explorer to try out all the XAP endpoints, download OpenAPI specs, or download Postman collections. Testing with one or all of these options will give you an understanding of how the examples and schema definitions compare to the actual output. Go to the API Explorer to find out more.
Deeplink customers to the Expedia website where they can book selected hotel. You will also be able to earn commission on any bookings that your customers make using our XAP API solution.