실시간 검색

재고와 가격을 실시간으로 검색하는 방법을 안내합니다.

실시간 검색#

ONDA 검색 API의 아키텍처와 실시간 재고/가격 조회 전략을 안내합니다.

검색 아키텍처 개요#

ONDA 검색은 2단계 검색 플로우를 사용합니다:

단계	API	목적	응답 속도
1단계	Availability Search	빈방이 있는 숙소 필터링	빠름 (~200ms)
2단계	Rate Search	선택한 숙소의 가격 및 패키지 상세 조회	중간 (~500ms)

왜 2단계 검색인가?#

성능 최적화: 수천 개 숙소의 모든 객실/패키지 가격을 한 번에 조회하면 응답이 느려집니다
사용자 경험: 사용자는 먼저 빈방이 있는 숙소를 빠르게 보고, 관심 있는 숙소만 상세 조회합니다
비용 절감: 불필요한 가격 계산을 최소화합니다

일반적인 검색 플로우#

Availability Search

날짜/인원 조건으로 빈방이 있는 숙소 목록과 최저가를 조회합니다.

사용자 선택

사용자가 관심 있는 숙소를 선택합니다.

Rate Search

선택한 숙소의 모든 객실 타입과 패키지별 가격을 상세 조회합니다.

예약 생성

사용자가 선택한 객실/패키지로 예약을 생성합니다.

실시간 검색의 특징#

왜 실시간 API만 제공하나요?#

재고와 가격은 캐싱이 불가능합니다:

재고 변동: 다른 채널에서 예약이 발생하면 즉시 재고가 감소합니다
동적 가격: 수요/공급에 따라 가격이 실시간으로 변동할 수 있습니다
정합성 보장: 예약 시점의 정확한 재고/가격을 확인해야 더블 부킹을 방지합니다

중요: 검색 결과를 5분 이상 캐싱하지 마세요. 예약 생성 직전에 항상 최신 가격을 재조회해야 합니다.

Availability Search (빈방 검색)#

목적: 빈방이 있는 숙소를 빠르게 필터링하여 목록 표시

주요 기능:

날짜/인원 조건으로 빈방 있는 숙소만 반환
각 숙소의 최저가 제공 (가장 저렴한 객실/패키지 조합)
지역, 가격대, 편의시설 등 필터링 가능
응답 시간: 평균 200ms

활용 사례:

검색 결과 목록 페이지
지도에서 숙소 마커 표시
빠른 가격 비교

간단한 호출 예시#

curl -X GET "https://api.onda.me/v1/search/availability" \
  -H "Authorization: Bearer {access_token}" \
  -d "check_in=2026-03-15" \
  -d "check_out=2026-03-16" \
  -d "adults=2" \
  -d "city=서울"

주요 검색 조건:

필수: 체크인/체크아웃 날짜, 성인 수
선택: 어린이 수, 객실 수, 지역(도시/구), 가격대, 편의시설 등

상세한 파라미터 목록은 API 레퍼런스를 참고하세요.

응답 구조:

빈방이 있는 숙소 목록
각 숙소의 최저가 정보 (객실명, 패키지명 포함)
남은 객실 수량
검색 조건 메타데이터

Rate Search (가격 상세 검색)#

목적: 특정 숙소의 모든 객실 타입과 패키지별 상세 가격 조회

주요 기능:

해당 숙소의 모든 객실 타입 목록
각 객실의 모든 패키지 (조식 포함, 환불 불가 등) 및 가격
일별 가격 상세 (장기 숙박 시 날짜별 차등 가격)
취소 정책, 결제 정책 등 상세 정보
응답 시간: 평균 500ms

활용 사례:

숙소 상세 페이지
객실 타입 비교
패키지별 가격 비교

간단한 호출 예시#

curl -X GET "https://api.onda.me/v1/search/rates" \
  -H "Authorization: Bearer {access_token}" \
  -d "property_id=prop_123456" \
  -d "check_in=2026-03-15" \
  -d "check_out=2026-03-16" \
  -d "adults=2"

응답 구조:

객실 타입별로 그룹화된 패키지 목록
각 패키지의 총 금액, 일별 금액, 세금 포함 여부
취소 정책 (무료 취소 기한, 위약금 비율)
결제 정책 (선결제/현장 결제)
조식 포함 여부 및 인원수

검색 필터링 전략#

지원하는 필터 유형#

필터 유형	예시	활용 사례
지역	도시, 구/군	"서울 강남구 호텔"
숙소 타입	호텔, 리조트, 펜션	"리조트만 보기"
성급	4성급 이상	"고급 호텔만"
가격대	10만원~20만원	"예산 범위 내"
편의시설	Wi-Fi, 주차장, 수영장	"수영장 있는 호텔"
위치	위도/경도 + 반경	"강남역 2km 이내"

필터 조합 전략#

효율적인 검색을 위해 필터를 적절히 조합하세요:

1차 필터 (넓게): 지역 + 날짜 → 후보 숙소 확보
2차 필터 (좁게): 가격대 + 편의시설 → 사용자 요구 충족
정렬: 가격순, 거리순, 평점순 → 최적 결과 우선 표시

캐싱 전략#

캐시 가능 여부#

데이터 유형	캐싱 가능	권장 TTL	이유
콘텐츠 (숙소/객실 정보)	✅ 가능	24시간	변경 빈도 낮음
Availability (빈방 여부)	⚠️ 짧게만	5-10분	재고 변동 빈번
Rates (가격)	❌ 불가	-	예약 직전 재조회 필수

중요: 예약 생성 직전에는 항상 최신 가격을 재조회하세요. 캐시된 가격으로 예약하면 가격 불일치 에러가 발생할 수 있습니다.

캐싱 아키텍처 예시#

웹훅 기반 캐시 무효화#

특정 숙소의 재고가 변경되면 웹훅 이벤트(inventory.updated)를 받아 관련 캐시를 삭제하세요. 이렇게 하면 항상 최신 재고를 보여줄 수 있습니다.

성능 최적화 전략#

1. 병렬 검색#

여러 숙소의 Rate를 동시에 조회할 때는 병렬 요청을 사용하세요. 순차 호출 대비 3-5배 빠릅니다.

권장: 비동기 HTTP 클라이언트 (Python: aiohttp, Node.js: Promise.all)

2. 페이지네이션#

검색 결과가 많을 경우 한 번에 모두 로드하지 말고 페이지네이션을 활용하세요.

권장: 페이지당 20-50개, 무한 스크롤 또는 페이지 번호 제공

3. 필드 선택#

불필요한 데이터를 받지 않도록 필요한 필드만 요청하세요. 응답 크기를 30-50% 줄일 수 있습니다.

예시: 목록 페이지에서는 상세 정책 정보를 제외하고 ID, 이름, 가격만 요청

4. Gzip 압축#

Accept-Encoding: gzip 헤더를 추가하면 응답 크기가 70-80% 감소합니다.

성능 목표#

API	목표 응답 시간	평균 응답 시간
Availability Search	< 300ms	~200ms
Rate Search	< 700ms	~500ms

응답 시간이 목표를 초과하면 병렬 처리, 필드 선택, Gzip 압축을 순서대로 적용해보세요.

일반적인 에러 시나리오#

파라미터 검증 에러#

원인: 체크인 날짜가 과거, 체크아웃이 체크인보다 이전 등

해결: 클라이언트에서 날짜 유효성 검증 후 API 호출

재고 없음#

상황: 빈방이 없으면 빈 배열([]) 반환 (에러 아님)

처리: "검색 결과가 없습니다" 메시지 표시, 다른 날짜 제안

가격 변동#

상황: 검색 후 시간이 지나 예약 시 가격이 변경됨

해결: 예약 생성 직전 Rate Search로 최신 가격 재확인

자세한 에러 코드는 에러 처리 가이드를 참고하세요.

다음 단계#

예약 관리 - 검색 결과로 예약 생성하기
웹훅 - 재고 변경 알림 받기
에러 처리 - 에러 코드 및 처리 방법
API 레퍼런스 - 전체 API 명세