조회
조회 API는 700,000개가 넘는 전 세계 숙박 시설의 실시간 요금 및 예약 가능 여부에 대한 액세스를 제공합니다.
개요
조회 API는 지정된 숙박 시설(요청당 최대 250개의 숙박 시설)의 모든 객실 유형에 대한 요금 및 예약 가능 여부를 반환합니다. 응답에는 해당 시장의 가격 표시 요건을 충족할 수 있도록 프로모션, 요금 환불 가능 여부, 취소 위약금과 전체 요금 내역 등의 요금 세부 정보가 포함됩니다.
유형이 같은 여러 객실은 occupancy 매개변수의 여러 인스턴스를 사용하여 요청할 수 있습니다. 같은 요청에서 동일한 투숙 인원이 여러 번 요청되는 경우 응답에 해당 투숙 인원에 적용되는 요금 집합이 하나만 포함됩니다. 한 번에 8개가 넘는 객실을 요청할 수 없습니다. 한 번에 8개 이상의 객실을 예약해야 하는 경우, 담당 계정 관리자에게 문의해 주시기 바랍니다. 현재 단체 예약 서비스를 확대하기 위해 노력 중이며, 귀하의 요구 사항을 알려주시면 이를 바탕으로 해결 방안을 마련하는 데 큰 도움이 될 것입니다.
요금 표시 변경 사항
일부 관할 구역에서는 여행객에게 요금을 어떻게 표시해야 하는지를 규정하는 법률을 시행하고 있습니다. 각 법률마다 약간의 차이가 있지만, 당사가 변경 사항을 적용한 방식 덕분에 개별 상황에 맞춘 규정 준수가 가능해질 것입니다.
가격 표시 규정 사례로는 다음이 포함되나, 이에 국한되지는 않습니다:
왜 변경되었나요?
Expedia Group API 파트너들이 다양한 방식으로 가격을 표시할 수 있도록 API를 개선했습니다. 그러나 궁극적으로, ‘ Expedia Group's ’ API를 사용하는 각 파트너는 익스피디아의 여행 정보 및 요금을 표시하는 방식이 관련 법규를 준수하도록 할 책임이 있습니다.
어떤 변경 사항이 있나요?
익스피디아는 ‘ Rapid API ’를 개선하여, 기본 요금과 전체 숙박 기간 동안 발생하는 모든 익스피디아 및 숙박 시설 수수 료와 세금을 포함한 총액을 나타내는 새로운 필드 ‘ property_inclusive ’를 추가했습니다. 이 총액에 대한 취소선 처리된 버전도 새로운 필드에서 확인할 수 있습니다 property_inclusive_strikethrough. 새로운 숙박 시설 포괄적 표시 필드 외에도, API 응답에서 세금 및 수수료가 분류되는 방식을 재조정했습니다. 익스피디아가 징수한 모든 수수료는 ‘1박 및 숙박( property_fee)’ 가격 내역 유형에 포함되며, 익스피디아가 징수한 모든 세금은 ‘1박 및 숙박( tax_and_service_fee)’ 가격 내역 유형에 포함됩니다.
Expedia Collect 요금의 경우, billable_currency및 property_inclusive필드의 property_inclusive_strikethrough값은 Expedia Group's 공급업체와의 계약에 명시된 통화로 표시되며, 이는 대개 숙박 시설의 현지 통화입니다. 이는 request_currency와는 별개입니다. property_inclusive및 property_inclusive_strikethrough필드에는 숙박 시설에서 현지 통화로 징수된 수수료가 포함될 수 있기 때문입니다. 이러한 동작은 ‘ inclusive ’ 및 ‘ inclusive_strikethrough ’ 필드와는 다르며, 이 필드들의 경우 Expedia Collect 요율에 대한 ‘ billable_currency ’은 ‘ request_currency ’과 동일합니다.
Shop 응답에 포함된 숙박 시설 수집 금액은 Content 응답에 표시된 금액과 다른 방식으로 그룹화되어 있을 수 있습니다. 합계는 여전히 정확히 일치해야 합니다.
이번 조치는 모든 숙박 시설에 적용된 전사적 변경 사항입니다. 변경 사항에 대해 추가 문의 사항이 있으시면 담당 계정 관리자에게 문의해 주시기 바랍니다.
로열티 포인트
Expedia의 비즈니스 요금 프로그램에 참여하는 회원혜택 프로그램을 운영 중인 숙박 시설에서는 출장 여행객에게 숙박에 대해 호텔 로열티 포인트를 적립할 수 있는 기회를 제공합니다. 파트너는 조회 응답의 amenities 노드를 사용하여 여행객으로부터 멤버십 세부 정보를 가져오기 전에 로열티 자격을 식별하고 보여줄 수 있습니다.
파트너는 또한 조회 API 요청에서 loyalty 값 필터를 사용하여 로열티 포인트 적립이 가능한 비즈니스 요금을 구체적으로 검색할 수 있습니다.
참고: 로열티 포인트 적립은 호텔의 기존 로열티 프로그램애 있는 비즈니스 요금에 대해서만 가능합니다.
예시:
로열티 포인트를 적립할 수 있는 호텔 비 즈니스 요금에는 검색 응답의 amenities 노드 아래에 다음 매개변수가 있습니다.
{
"id": "2096",
"name": "Eligible for hotel loyalty points"
}커미션 인센티브
Rapid API 파트너는 지정된 예약 및 숙박 기간 동안 숙박 시설에 대해 더 높은 마진을 제공하는 추가 커미션 인센티브를 이용할 수 있습니다. 활성 상태의 커미션 인센티브가 있는 숙박 시설을 식별하려면 Rapid 조회 API 요청에서 include 매개변수에 rooms.rates.marketing_fee_incentives 값을 사용하면 됩니다. 요청한 숙박 기간 전체 또는 일부에 대해 커 미션 인센티브가 적용된 요금에는 조회 API 응답의 marketing_fee_incentives 개체에 인센티브 출처와 영향을 받는 숙박 기간 일부가 포함된 추가 세부 정보가 있습니다. 따라서 재고 정렬 및 선택 프로세스에서 이 필드와, 사용 가능한 모든 인센티브를 포함하는 마케팅 수수료의 예상치를 나타내는 기존 marketing_fee 필드를 고려할 수 있습니다.
예시
숙박 시설 19248은 12월 숙박에 대해 더 높은 마진을 제공합니다. 조회 API에 대해 다음과 같이 요청해 주세요. 숙박 시설 19248, 12월 22일부터 1월 5일까지의 숙박 예약입니다. 조회 API 응답의 marketing_fee_incentives객체에서, 12월 22일부터 12월 31일까지 요청된 숙박 기간 중 일부에 대해 인센티브가 제공되는 것을 확인할 수 있습니다. 이는 총 14박 중 10박에 해당합니다.
요청 예
curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2026-12-22\
&checkout=2027-01-05\
¤cy=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
-H "accept: application/json, application/json"\
-H "accept-encoding: gzip"\
-H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
-H "user-agent: TravelNow/3.30.112"응답 예
[
{
"property_id": "19248",
"rooms": [
{
"id": "123abc",
"room_name": "Fancy Queen Room",
"rates": [
{
"id": "333abc",
...
"marketing_fee_incentives": [
{
"source": "property",
"start": "2026-12-22",
"end": "2027-12-31"
}
],
"occupancy_pricing": {
"2": {
"nightly": [ ... ],
"stay": [ ... ],
"totals": {
"inclusive": { ... },
"exclusive": { ... },
"inclusive_strikethrough": { ... },
"strikethrough": { ... },
"marketing_fee": {
"billable_currency": {
"value": "276.36",
"currency": "USD"
},
"request_currency": {
"value": "276.36",
"currency": "USD"
}
},
"gross_profit": { ... },
"minimum_selling_price": { ... },
"property_fees": { ... }
},
"fees": { ... }
}
}
}
]
}
]
}
]여행 목적
travel_purpose매개변수를 사용하면 여행객을 출장 목적 또는 여가 목적으로 지정할 수 있습니다. 모든 Rapid 파트너사는 ‘ travel_purpose ’ 매개변수를 활용하여 숙박 시설가 기업 출장객을 더 잘 식별하고 서비스를 제공할 수 있도록 도울 수 있습니다.
사업용 세율을 조회할 자격이 있는 파트너의 경우, ‘Shop’ 요청 시 travel_purpose=business을 사용해야만 ‘Shop’ 응답에서 사업용 세율을 수신할 수 있습니다. 요청에 travel_purpose 매개변수가 제공되지 않으면 휴가로 간주되고 비즈니스 요금이 반환되지 않습니다.
예시
예약 가능 여부 API 요청에 24자를 추가해 쉽고 간편하게 여행 목적을 출장으로 지정할 수 있습니다.
&travel_purpose=business머천다이징
머천다이징 워크플로를 지원하고 머천다이징 API 연동을 원활하게 진행할 수 있도록 조회 API에 변경 사항을 적용했습니다. 파트너사는 Rapid Shopping Availability 엔드포인트에서 제공되는 새로운 ‘ deal ’ 필터를 사용하여, 현재 진행 중인 프로모션이 적용된 요금만 수신할 수 있습니다. 이 를 통해 파트너사는 상품 진열에만 초점을 맞춘 쇼핑 요청을 유연하게 생성할 수 있으며, 반환되는 모든 요율에 ‘ deal ’ 속성이 포함되도록 보장할 수 있습니다.
할인 전 가격 표시
strikethrough 필드는 호텔에서 지원하는 할인이 적용되기 전 세금을 제외한 총 가격을 나타냅니다. 이 필드는 일반적으로 검색 결과에 세금 및 수수료 없이 기본 가격을 표시하는 미국과 같은 지역에서 사용해야 합니다.
inclusive_strikethrough 필드는 세금 및 수수료가 포함된 할인 전 총 가격을 나타냅니다. 이 필드를 통해 모두 포함된 가격, 즉 기본 가격, 세금 및 수수료를 표시하는 지역에 적용되는 할인을 보다 명확하게 표시할 수 있습니다. 이 필드는 청구 가능한 통화와 요청된 통화 모두로 값을 반환합니다.
예시
[
{
"property_id": "19248",
"rooms": [
{
"id": "123abc",
"room_name": "Fancy Queen Room",
"rates": [
{
"id": "333abc",
...
"occupancy_pricing": {
"2": {
"nightly": [ ... ],
"stay": [ ... ],
"totals": {
"inclusive": { ... },
"exclusive": { ... },
"inclusive_strikethrough": {
"billable_currency": {
"value": "726.63",
"currency": "CAD"
},
"request_currency": {
"value": "549.60",
"currency": "USD"
}
},
"strikethrough": {
"billable_currency": {
"value": "650.00",
"currency": "CAD"
},
"request_currency": {
"value": "491.64",
"currency": "USD"
}
},
"marketing_fee": { ... },
"gross_profit": { ... },
"minimum_selling_price": { ... },
"property_fees": { ... }
},
"fees": { ... }
}
}
}
]
}
]
}
]프로모션 및 할인 가격 표시
예약 가능 여부 및 가격 확인 API에서 제공되는 프로모션 또는 할인 전 가격을 기반으로 할인 금액을 표시하는 경우 특정 POS(Point of Sale)에서는 표준 요금(할인을 계산하는 데 사용되는 요금)에 대한 세부 정보를 제공하도록 요구합니다. 아래에서 사용할 용어에 대한 설명을 참조하세요.
EU: 명확한 표준 요금 가격 세부 정보를 제공합니다(예: "이 가격은 검색 내용을 기반으로 숙박 시설에서 제공한 표준 요금입니다.").
이탈리아: 다음 문구를 사용해 주세요: “Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date”.
환불 가능 옵션
‘ current_refundability ’ 필드를 통해 파트너사는 모든 환불 옵션을 표시할 수 있으며, 이를 통해 여행객에게 요금 투명성을 제공하고 유연성을 높여줍니다.
3가지 옵션은 다음과 같습니다:
refundablenon_refundablepartially_refundable
‘부분 환불 가능’이란 무슨 뜻인가요?
‘부분 환불 가능’이란 취소 위약금이 0보다 크지만 예약 총액보다 작은 요금제를 의미하며, 및/또는 에서 확인 가능한 바와 같이, 숙박 기간 내에 non-refundable 에 명시된 일정 범위가 있는 경우를 말합니다.
current_refundability필드를 활용하는 것이 환불 가능 여부를 나타내는 부울 플래그만 사용하는 것보다 어떤 점이 더 나은가요?
refundable부울 플래그는 요금이 전액 환불 가능한 지 여부를 나타내지만, 부분 환불 가능한 요금의 경우 ‘ false ’ 결과를 반환하므로 여행객에게 오해를 줄 수 있습니다. ‘ current_refundability ’ 필드는 요금 환불 가능 여부에 대한 보다 정확한 정보를 제공하는, 더 세분화된 옵션을 제공합니다.
파트너는 Shop 응답에서 ‘ current_refundability ’ 필드를 어떻게 확인할 수 있나요?
파트너는 Shop 요청에서 ‘ current_refundability ’ 매개변수 아래에 있는 ‘ include ’ 필드를 요청해야 합니다.
예시
"property_id": "23060",
"status": "available".
"rates": [
{
"id": "201392692",
"status": "available",
...
...
...
...
"current_refundability": partially_refundable,
"cancel_penalties":[
{
"start": "2027-10-08T23:59:00.000+02:00",
"end": "2027-10-09T23:59:00.000+02:00",
"nights":"1",
"currency": "EUR"
}
]
}
]이용 불가 이유
unavailable_reason 기능을 사용하면 설정된 숙박(숙박 날짜 및 투숙 인원) 조건으로 숙박 시설을 이용할 수 없는 이유에 대한 구체적인 정보를 요청할 수 있습니다. 응답에 이 정보를 받으려면 조회 시 선택적 요청 매개변수 include=unavailable_reason을 포함해야 합니다. 그러나 사용할 수 없는 모든 숙박 시설에서 예약 불가에 대한 구체적인 이유를 제공하는 것은 아닙니다. 이러한 숙박 시설은 응답에 반환되지 않습니다.
조회 응답에는 이용 가능한 숙박 시설과 그렇지 않은 숙박 시설이 섞여 있을 수 있습니다. 이용할 수 없는 숙박 시설에는 property_id, score 및 이용 불가 숙박 시설에 대한 간단한 설명(영어로 제공됨) code가 포함된 unavailable_reason 섹션과 숙박 시설/객실/요금제를 예약할 수 있도록 요청에서 조정할 수 있는 추가 정보에 대한 data 섹션이 포함됩니다. 예를 들어, unavailable_reason code가 adults_exceed_threshold인 경우 data의 2는 성인 2명이 해당 객실/요금에 허용되는 최대 인원이며 2인을 초과하는 경우 오류를 반환함을 의미합니다.
참고: 숙박 시설에 여러 제한 사항을 적용할 수 있지만 하나의 unavailable_reason만 반환됩니다.
예시
[
{
"property_id": "824739",
"score": 12345,
"unavailable_reason": {
"code": "adults_exceed_threshold",
"data": "2"
}
}
]편의 시설 필터
선택적으로 하나 이상의 특정 편의 시설과 함께 amenity_category 요청 매개변수를 사용하여 Rapid 조회 응답에 반환된 숙박 시설을 필터링할 수 있습니다. 응답을 필터링하는 데 사용할 수 있는 편의 시설 목록은 콘텐츠 참조 목록의 편의 시설 카테고리 섹션을 참조하십시오.
예시
단일 편의 시설 필터:
&amenity_category=free_breakfast여러 편의 시설 필터:
&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino속도 제한
파트너에게 속도 제한을 적용하여 트래픽을 최적화합니다. 이러한 속도 제한은 파트너에게 안정적이고 유지 가능한 서비스를 지속적으로 제공하는 동시에 Expedia Group 시스템의 효율적인 사용을 보장합니다. 조회 트래픽의 경우 부하를 결정하는 중요한 요소는 각 요청에서 검색되는 숙박 시설 수, 객실 수 및 숙박 기간입니다.
요금 확인
조회 응답에서 반환한 요금을 확인합니다. 예약 전에 이 API를 사용하여 이전에 선택한 요금이 아직 유효한지 확인합니다. 요금이 일치하면 응답은 예약을 요청하는 링크를 반환합니다. 요금이 변경된 경우 응답은 새로운 요금 세부 정보와 새 요금에 대한 예약 링크를 반환합니다. 해당 요금을 더 이상 이용할 수 없으면 응답에 다른 요금을 다시 검색할 수 있는 새로운 조회 요청 링크가 반환됩니다.
PriceCheck에 표시된 totals.property_fees및 fees의 청구 금액은 이전 Shop 응답과 비교하여 약 0.1%(객실당 × 인원당 × 숙박일수) 정도의 미세한 차이가 있을 수 있으며, 이 차이는 금액이 0으로 조정된 경우를 포함할 수 있습니다. 숙박 시설에서 납부해야 할 수수료의 차이는 Expedia Collect 요율에 대해 request_currency와 billable_currency의 내용이 서로 다를 때 발생합니다. 이 불일치로 인해 API 기능에는 아무런 영향이 없습니다.
보류 및 다시 시작 기능
일부 재고는 ‘보류 및 재개’ 기능을 이용할 수 없습니다. ‘보류 및 재개’ 기능을 사용하는 파트너는 ‘ non-holdable ’ 요금의 쇼핑 지표를 적용함으로써 이러한 단계별 요금을 이용할 수 있습니다.
결제 옵션
익스피디아가 최종 여행객으로부터 직접 결제를 받는 경우(EPS MOR)에 허용되는 결제 수단을 반환합니다. 이 API에서는 결제 페이지를 제공하고 유효한 결제 수단을 표시하여 원활한 예약을 돕습니다.
중요 참고 사항
language2자리 언어 코드 및 국가 코드를 하이픈으로 연결한 쌍만 사용합니다.
- 2자리 국가 코드(
country)는 여행자의 판매 지점을 지정하는 용도로 사용되며, 현지화된 콘텐츠에는 영향을 미치지 않습니다. - 정적 데이터(이름, 등급, 지리적 정보 등)는 반환되지 않습니다. 예약 가능 여부 및 요금 관련 데이터만 제공됩니다.
- 토큰화된 요청 링크는 곧 만료됩니다. 토큰 링크가 HTTP 503 오류를 반환하면 링크가 만료된 것일 수 있습니다. 새 조회 응답에서 최신 요금 확인 또는 보증금 링크를 가져온 후 다시 시도해 주세요. 링크 값을 오래 재사용하려고 저장해 두면 안 됩니다.
- 숙박 시설은 Rapid API를 통해 언제든지 콘텐츠를 업데이트할 수 있습니다. 고객에게 최신 정보를 제공하기 위해 여러분의 노력이 필요합니다. 조회 API는 예약 가능한 객실 및 요금에 대한 최신 정보를 제공합니다. 이 응답에 포함되지 않은 property-level, room-level, 및 rate-level 에 대 한 추가 정보를 얻으려면 당사의 숙박 시설 콘텐츠 API를 이용하십시오.
- API에서는 객실 하나당 요금만 제공하므로 여러 객실을 예약하려면 직접 추가로 계산해야 합니다. 출시 요건의 일환으로, 귀사의 통합 시스템은 예약 과정의 특정 단계에서 최종 사용자에게 상세한 가격 내역을 표시해야 합니다.
>> 당사의 보안이 철저한 제휴 사이트에서 상세 내역을 확인하세요
변동 세금 및 수수료
예약 시점에 산정할 수 없어 총액에 포함되지 않은 필수 세금 및 수수료가 있을 수 있습니다. 예를 들어, ‘ in-stay ’ 활동에 따라 달라지는 요금이나 일본 및 콜롬비아와 같은 일부 시장에서 부과되는 변동성 있는 숙박세 등이 이에 해당합니다. 이러한 가변 세금 및 수수료의 산정 방식에 대한 정보는 콘텐츠 API에서 확인할 수 있습니다. 이 정보는 여행객들이 잘 볼 수 있는 곳에 눈에 띄게 게시되어야 합니다.
API 세부 정보
이 페이지에서 조회 관련 엔드포인트 정의를 살펴본 후 API Explorer 또는 다른 테스트 소프트웨어를 사용하여 예시 및 스키마 정의가 실제 출력과 어떤 차이가 있는지 확인해 보세요.
추가 리소스
모든 Rapid API 엔드포인트를 사용해 보거나 OpenAPI 사양 또는 Postman 컬렉션을 다운로드하려는 경우 다음 사항을 참조해 주세요.