조회

조회 API는 700,000개에 달하는 전 세계 숙박 시설의 실시간 요금 및 예약 가능 여부에 대한 액세스를 제공합니다.

개요

조회 API는 지정된 숙박 시설(요청당 최대 250개의 숙박 시설)의 모든 객실 유형에 대한 요금 및 예약 가능 여부를 반환합니다. 응답에는 해당 시장의 가격 표시 요건을 충족할 수 있도록 프로모션, 요금 환불 가능 여부, 취소 위약금과 전체 요금 내역 등의 요금 세부 정보가 포함됩니다.

유형이 같은 여러 객실은 occupancy 매개변수의 여러 인스턴스를 사용하여 요청할 수 있습니다. 같은 요청에서 동일한 투숙 인원이 여러 번 요청되는 경우 응답에 해당 투숙 인원에 적용되는 요금 집합이 하나만 포함됩니다. 한 번에 8개가 넘는 객실을 요청할 수 없습니다. 한 번에 8개 이상의 객실을 예약해야 하는 경우 계정 관리자에게 문의하시기 바랍니다. 저희는 단체 예약을 확대하기 위해 노력하고 있으며, 요구 사항을 공유해 주시면 솔루션 개발에 도움이 될 것입니다.

요금 표시 변경 사항

현지 규정으로 인한 최근 변경 사항을 알려드립니다:

캘리포니아 가격 표시 규정 (캘리포니아 주의회 법안 537), 2024-07-01 부터 적용됨
미네소타 가격 표시 규정 (제111장-H.F. 3438호), 2025-01-01 부터 적용됨

다른 규정이 추가될 것으로 예상되며 각 규정에 대해 이 페이지를 업데이트하지는 않을 것이며, 이는 두 가지 예시일 뿐입니다.

변경된 이유는 무엇인가요?

일부 관할권에서는 여행객에게 요금을 표시하는 방법을 의무화하는 법률을 시행하고 있습니다. 각 법률은 조금씩 다르지만, 변경 사항을 구현한 방식을 통해 개별적인 규정 준수가 가능합니다.

익스피디아 그룹은 API 파트너가 다양한 방식으로 가격을 표시할 수 있도록 API를 변경했습니다. 그러나 궁극적으로 익스피디아 그룹의 API를 사용하는 각 파트너는 익스피디아 여행 정보 및 가격을 표시하는 방식이 법률을 준수하도록 할 책임이 있습니다.

어떤 변화가 있나요?

익스피디아는 전체 숙박에 대한 기본 요금과 익스피디아 및 숙소가 징수한 모든 수수료 및 세금이 포함된 총 요금이 포함된 새로운 필드 property_inclusive를 포함하도록 Rapid API를 개선했습니다. 이 총 가격의 스트라이크 스루 버전도 새로운 필드에서 사용할 수 있습니다property_inclusive_strikethrough. 새로운 속성 포함 표시 필드 외에도 API 응답에서 세금 및 수수료가 구분되는 방식을 재조정했습니다. 익스피디아가 징수하는 모든 수수료는 숙박 및 숙박( property_fee ) 가격 내역 유형에 포함되며, 익스피디아가 징수하는 모든 세금은 숙박 및 숙박( tax_and_service_fee ) 가격 내역 유형에 포함됩니다.

익스피디아 징수 요금의 경우, billable_currency 및 property_inclusive 필드의 property_inclusive_strikethrough 은 익스피디아 그룹과 공급업체의 계약에 명시된 통화(일반적으로 숙박시설의 현지 통화)로 표시됩니다. request_currency 및 property_inclusive 필드에는 현지 통화로 숙박시설에서 징수한 수수료가 포함될 수 있으므로 property_inclusive_strikethrough 와는 무관합니다. 이 동작은 inclusive 및 inclusive_strikethrough 필드와 다르며, Expedia Collect 요금의 경우 billable_currency 은 request_currency 과 동일합니다.

상점 응답에는 속성 수집 금액이 콘텐츠 응답에 표시된 금액과 다르게 그룹화되어 있을 수 있습니다. 합계는 여전히 올바르게 일치해야 합니다.

이는 모든 숙소에 적용되는 글로벌 변경 사항으로, 변경 사항에 대해 궁금한 점이 있으면 계정 관리자에게 문의하시기 바랍니다.

로열티 포인트

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일까지 요청된 숙박의 일부에 대해 사용 가능한 인센티브가 있음을 확인할 수 있습니다. 12월 31일(총 14일 숙박 중 10일에 해당)까지 인센티브가 제공됩니다.

요청 예

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
&currency=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”.

환불 옵션

current_refundability 필드를 통해 파트너는 모든 환불 가능 옵션을 표시하여 여행자에게 요금 투명성과 향상된 유연성을 제공할 수 있습니다.

세 가지 옵션이 있습니다:

refundable
non_refundable
partially_refundable

부분 환불이 가능하다는 것은 무엇을 의미하나요?

부분 환불 가능은 다음과 같은 요금을 말합니다:

취소 위약금 이 0보다 크지만 총 예약 금액보다 작습니다.

및/또는

숙박 기간 내에는 환불이 불가능한 날짜 범위가 있습니다.

**** current_refundability 필드를 활용하는 것이 환불 가능한 부울 플래그만 사용하는 것보다 어떻게 더 나은가요?

refundable 부울 플래그는 요금이 전액 환불 가능한지 여부를 나타내지만, 부분 환불 가능한 요금의 경우 false 결과를 반환하므로 여행자에게 오해의 소지가 있습니다. current_refundability 필드는 요금의 환불 가능성에 대한 보다 정확한 정보를 제공하는 미묘한 옵션을 제공합니다.

파트너는 Shop 응답 내에서 current_refundability 필드를 어떻게 받을 수 있나요?

파트너는 상점 요청의 current_refundability 매개변수 아래에 include 필드를 요청해야 합니다.

예시

"property_id": "23060",
  "status": "available".
  "rates": [
    {
      "id": "201392692",
      "status": "available",
      ...
      ...
      ...
      ...
      "current_refundability": partially_refundable,
      "cancel_penalties":[
        {
          "start": "2024-10-08T23:59:00.000+02:00",
          "end": "2024-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 에 대한 이전 상점 응답과 비교하여 약 0.1%(객실당 × 1인 × 1박)의 약간의 차이가 있을 수 있으며, 여기에는 0으로 조정되는 금액이 포함될 수 있습니다. 숙박 시설에서 지불해야 하는 수수료의 차이는 request_currency 와 billable_currency 의 익스피디아 콜렉트 요금이 다를 때 발생합니다. API 기능은 이 불일치로 인해 영향을 받지 않습니다.

보류 및 다시 시작 기능

일부 인벤토리는 보류 및 재개할 수 없습니다. 보류 및 재개를 사용하는 파트너는 보류 불가 요금의 쇼핑 지표를 채택하여 이러한 증분 요금에 액세스할 수 있습니다. 자세한 내용은 에서 확인할 수 있습니다.

결제 옵션

익스피디아가 최종 여행자로부터 결제를 받는 경우 허용되는 결제 옵션(EPS MOR)을 반환합니다. 이 API에서는 결제 페이지를 제공하고 유효한 결제 수단을 표시하여 원활한 예약을 돕습니다.

중요 참고 사항

language는 하이픈으로 연결된 2자리 언어 및 국가 코드 쌍만 사용합니다. 코드를 통합하기 전에 지원되는 언어를 검토해 주세요.
2자리 country 코드는 여행객의 POS를 설정하며 현지화된 콘텐츠에는 영향을 미치지 않습니다.
정적 데이터(이름, 등급, 지리적 정보 등)는 반환되지 않습니다. 예약 가능 여부 및 요금 관련 데이터만 제공됩니다.
토큰화된 요청 링크는 곧 만료됩니다. 토큰 링크가 HTTP 503 오류를 반환하면 링크가 만료된 것일 수 있습니다. 새 조회 응답에서 최신 요금 확인 또는 보증금 링크를 가져온 후 다시 시도해 주세요. 링크 값을 오래 재사용하려고 저장해 두면 안 됩니다.
숙박 시설은 Rapid API를 통해 언제든지 콘텐츠를 업데이트할 수 있습니다. 고객에게 최신 정보를 제공하기 위해 여러분의 노력이 필요합니다. 조회 API는 예약 가능한 객실 및 요금에 대한 최신 정보를 제공합니다. 이 응답에 반환되지 않는 추가적인 숙박 시설 수준, 객실 수준 및 요금 수준 정보를 확인하려면 숙박 시설 콘텐츠 API를 사용해 주세요.
API에서는 객실 하나당 요금만 제공하므로 여러 객실을 예약하려면 직접 추가로 계산해야 합니다. 출시 요구 사항의 일부로 통합 시 예약 과정의 특정 단계에서 최종 사용자에게 상세한 요금 내역을 표시해야 합니다. 이 상세 내역은 이 보안 설명서 링크에서 확인할 수 있습니다.

이 서비스에 대해 테스트 요청을 수행하려면 테스트 요청 설명서를 참조해 주세요.

조회