조회
조회 API는 700,000개에 달하는 전 세계 숙박 시설의 실시간 요금 및 예약 가능 여부에 대한 액세스를 제공합니다.
개요
조회 API는 지정된 숙박 시설(요청당 최대 250개의 숙박 시설)의 모든 객실 유형에 대한 요금 및 예약 가능 여부를 반환합니다. 응답에는 해당 시장의 가격 표시 요건을 충족할 수 있도록 프로모션, 요금 환불 가능 여부, 취소 위약금과 전체 요금 내역 등의 요금 세부 정보가 포함됩니다.
유형이 같은 여러 객실은 occupancy 매개변수의 여러 인스턴스를 사용하여 요청할 수 있습니다. 같은 요청에서 동일한 투숙 인원이 여러 번 요청되는 경우 응답에 해당 투숙 인원에 적용되는 요금 집합이 하나만 포함됩니다. 한 번에 8개가 넘는 객실을 요청할 수 없습니다. 8개가 넘는 객실을 한 번에 예약하려면 해당 영업 담당자에게 단체 예약 파트너십에 대해 문의해 주세요.
요금 표시 변경 사항
2024년 7월 1일부터 시행되는 캘리포니아 가격 표시 규정(버먼법)에 따라 변경되는 사항에 대해 알려드립니다.
버먼법이란?
이 법은 단기 숙박 시설에서 숙박 시 부과되는 모든 수수료나 요금이 미포함된 객실 요금을 광고, 표시 또는 제공하는 것을 금지하고 있습니다(정부에서 숙박에 대해 부과하는 세금 및 수수료 제외). 또한 이 법에 따르면 단기 숙박 시설은 소비자가 숙박을 예약하기 전에 표시되는 총 결제 요금에 정부에서 숙박에 대해 부과하는 모든 세금 및 수수료도 포함해야 합니다. "단기 숙박 시설"이란 호텔, 모텔, B&B, 여관 또는 기타 단기 숙박 시설을 의미하며, 단기 임대 숙박 시설 또는 방문객에게 30일 이하로 연속 임대하는 주거용 숙박 시설을 포함합니다. 자세한 내용은 캘리포니아 주의회 법안 537을 참조해 주세요.
Expedia Group은 API 파트너가 다양한 방식으로 요금을 표시할 수 있도록 API를 변경하고 있습니다. 그렇지만 궁극적으로 Expedia Group API를 사용하는 개별 파트너는 Expedia 여행 정보 및 요금 표시 방식이 법률을 준수하도록 해야 할 책임이 있습니다.
예정된 변경 사항에는 어떤 것이 있나요?
Expedia는 새로운 필드(property_inclusive)를 포함하도록 Rapid API를 개선하고 있으며, 이 필드에는 기본 요금과 전체 숙박 기간에 대해 Expedia 및 숙박 시설에서 청구하는 수수료 및 세금을 포함하는 총 요금이 표시됩니다. 이 총 요금의 할인 전 요금도 새로운 필드(property_inclusive_strikethrough)에서 확인 가능합니다. 새로운 숙박 시설 포함 표시 필드 외에도 API 응답에서 세금과 수수료가 구분되는 방식으로 재조정하고 있습니다. Expedia에서 청구하는 모든 수수료는 nightly 및 stay property_fee 요금 내역 유형에 포함됩니다. Expedia에서 청구하는 모든 세금은 nightly 및 stay tax_and_service_fee 요금 내역 유형에 포함됩니다.
모든 숙박 시설에 적용되는 글로벌 변경 사항인 만큼, 변경 사항을 원활하게 적용하고 이해할 수 있도록 릴리스 날짜가 2024년 5월 29일로 변경되었습니다. 변경 사항에 대한 궁금한 점이 있으시면 영업 관리자에게 문의해 주세요.
로열티 포인트
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월 숙박에 대해 더 높은 마진을 제공합니다. 12월 22일부터 1월 5일까지 숙박에 대한 숙박 시설 19248의 조회 API 요청을 만듭니다. 조회 API 응답의 marketing_fee_incentives 개체에서 요청한 숙박 기간의 일부인 12월 22일부터 12월 31일(총 14박 중 10박에 해당)에 사용 가능한 인센티브가 있음을 확인할 수 있습니다.
요청 예
curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-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": "2023-12-22",
"end": "2023-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 매개변수를 사용해 여행 목적을 출장 또는 휴가로 지정할 수 있습니다. 2024년 4월 1일부터 비즈니스 요금으로 조회할 수 있는 파트너는 조회 요청 시 travel_purpose=business를 사용해야 조회 응답에 비즈니스 요금을 받을 수 있습니다. 요청에 travel_purpose 매개변수가 제공되지 않으면 휴가로 간주되고 비즈니스 요금이 반환되지 않습니다.
예시
예약 가능 여부 API 요청에 24자를 추가해 쉽고 간편하게 여행 목적을 출장으로 지정할 수 있습니다.
&travel_purpose=business할인 전 가격 표시
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”.
이용 불가 이유
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를 사용하여 이전에 선택한 요금이 아직 유효한지 확인합니다. 요금이 일치하면 응답은 예약을 요청하는 링크를 반환합니다. 요금이 변경된 경우 응답은 새로운 요금 세부 정보와 새 요금에 대한 예약 링크를 반환합니다. 해당 요금을 더 이상 이용할 수 없으면 응답에 다른 요금을 다시 검색할 수 있는 새로운 조회 요청 링크가 반환됩니다.
totals.property_fees 및 fees에 대해 PriceCheck에 표시되는 청구 가능 금액은 이전 조회 응답과 비교하여 약 0.1%(객실당 × 1인 × 1박) 정도의 차이가 있을 수 있습니다. 이러한 숙박 시설 요금의 불일치는 Expedia Collect 요금의 request_currency와 billable_currency가 다른 경우에만 발생할 수 있습니다. API는 이 상황에서도 오류 없이 작동합니다.
결제 옵션
수락된 결제 옵션을 반환합니다. 이 API에서는 결제 페이지를 제공하고 유효한 결제 수단을 표시하여 원활한 예약을 돕습니다. Property Collect로 제공된 요금은 숙박 시설에서 승인하는 카드 유형을 반환합니다. 다른 모든 요금 유형은 Expedia에서 허용하는 결제 옵션을 반환합니다.
중요 참고 사항
language는 하이픈으로 연결된 2자리 언어 및 국가 코드 쌍만 사용합니다. 코드를 통합하기 전에 지원되는 언어를 검토해 주세요.- 2자리
country코드는 여행객의 POS를 설정하며 현지화된 콘텐츠에는 영향을 미치지 않습니다. - 정적 데이터(이름, 등급, 지리적 정보 등)는 반환되지 않습니다. 예약 가능 여부 및 요금 관련 데이터만 제공됩니다.
- 토큰화된 요청 링크는 곧 만료됩니다. 토큰 링크가 HTTP 503 오류를 반환하면 링크가 만료된 것일 수 있습니다. 새 조회 응답에서 최신 요금 확인 또는 보증금 링크를 가져온 후 다시 시도해 주세요. 링크 값을 오래 재사용하려고 저장해 두면 안 됩니다.
- 숙박 시설은 Rapid API에서 언제든지 콘텐츠를 업데이트할 수 있습니다. 고객에게 최신 정보를 제공하기 위해 여러분의 노력이 필요합니다. 조회 API는 이용 가능한 객실 및 요금의 최신 정보를 제공합니다. 이 응답에 반환되지 않는 추가적인 숙박 시설 수준, 객실 수준 및 요금 수준 정보를 확인하려면 숙박 시설 콘텐츠 API를 사용해 주세요.
- API에서는 객실 하나당 요금만 제공하므로 여러 객실을 예약하려면 직접 추가로 계산해야 합니다. 출시 요구 사항의 일부로 통합 시 예약 과정의 특정 단계에서 최종 사용자에게 상세한 요금 내역을 표시해야 합니다. 이 상세 내역은 이 보안 설명서 링크에서 확인할 수 있습니다.
이 서비스에 대해 테스트 요청을 수행하려면 테스트 요청 설명서를 참조해 주세요.
API 세부 정보
이 페이지에서 조회 관련 엔드포인트 정의를 살펴본 후 API Explorer 또는 다른 테스트 소프트웨어를 사용하여 예시 및 스키마 정의가 실제 출력과 어떤 차이가 있는지 확인해 보세요.
추가 리소스
모든 Rapid API 엔드포인트를 사용해 보거나 OpenAPI 사양 또는 Postman 컬렉션을 다운로드하려는 경우 다음 사항을 참조해 주세요.