Google Hotels
구글 호텔 검색 결과 한 건에는 호텔 이름, 성급, 지도 위치와 함께 투숙객 평점, 리뷰 수, 사진, 그리고 선택한 일정과 통화 기준의 최저 1박 요금이 담겨 있습니다. 이 값들을 나란히 놓으면 목적지별 호텔 공급을 비교하고, 요금과 평점의 균형을 살피고, 개별 호텔을 자세히 보기 전에 후보를 좁힐 수 있습니다.
Google Hotels API 주요 기능
- 여행자가 쓰는 말 그대로 검색query에 hotels in new york 같은 목적지나 호텔 이름을 넣으면 구글 호텔에 표시되는 순서대로 호텔이 반환되고, rank에 각 호텔의 순위가 담깁니다.
- 실제 숙박 일정 기준의 요금check_in, check_out, currency로 원하는 숙박 조건을 지정하면 각 행에 해당 일정과 price.amount, price.currency, 형식이 적용된 요금이 들어갑니다.
- 정렬과 1박 요금 범위sort_by로 relevance, lowest_price, highest_rating, most_reviewed를 고르고, min_price와 max_price로 예산 안의 호텔만 남길 수 있습니다.
- 모든 호텔에 평가 지표stars는 호텔 등급, rating은 1~5점 투숙객 평균 평점, reviews_count는 그 평점의 근거가 된 리뷰 수입니다.
- 좌표와 사진location에 위도와 경도가, images에 구글이 보여 주는 호텔 사진 URL이 들어 있습니다.
- 후속 조회용 호텔 ID각 행의 id는 Google Hotel Details API와 Hotel Price Tracker API에 그대로 넘길 수 있고, url은 구글 호텔의 해당 페이지를 가리킵니다.
- 한 번에 최대 140개 호텔results_limit은 1~140으로 지정할 수 있으며, is_sponsored로 광고 호텔을 일반 노출과 구분해 다룰 수 있습니다.
Google Hotels API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 목적지 또는 호텔 검색어. 예: hotels in new york, 호텔 이름. |
check_in | 선택 | 체크인 날짜(YYYY-MM-DD, 오늘 이후). check_out과 함께 지정합니다. 둘 다 생략하면 내일부터 1박 요금이 반환됩니다. |
check_out | 선택 | 체크아웃 날짜(YYYY-MM-DD). check_in보다 늦어야 하며 최대 30박까지입니다. |
currency | 선택 | 요금과 요금 범위에 쓰는 3자리 통화 코드(USD, EUR 등). |
sort_by | 선택 | 정렬 기준: relevance, lowest_price, highest_rating, most_reviewed 중 하나. |
min_price | 선택 | 1박 요금 하한(currency 기준 통화). |
max_price | 선택 | 1박 요금 상한(currency 기준 통화). min_price보다 작을 수 없습니다. |
location_code | 선택 | 검색 시장의 위치 코드. 기본값은 2840(미국)입니다. |
language_code | 선택 | 결과 언어 코드. 기본값은 en입니다. |
results_limit | 선택 | 반환할 호텔 수(1~140). 기본값은 18입니다. |
Google Hotels API 사용 방법
목적지로 검색하고 호텔을 한 행씩 읽습니다.
- {"query": "hotels in new york", "currency": "USD", "results_limit": 18}을 /v1/google-hotels/search에 POST합니다.
- GET /v1/tasks/{task_id}를 폴링해 status 값이 succeeded가 될 때까지 기다립니다.
- results.items에서 호텔을 읽고, has_more가 true이면 results.next_cursor로 다음 페이지를 가져옵니다.
curl -X POST "https://api.socq.ai/v1/google-hotels/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"hotels in new york","currency":"USD","results_limit":18}'Google Hotels API 추천 활용 사례
- 목적지 요금 수준 파악: 같은 일정에서 price.amount를 stars, rating과 함께 놓고 도시별·등급별 호텔 요금 수준을 파악합니다.
- 후보 호텔 선별: 요금 범위 안에서 rating과 reviews_count가 기준을 넘는 호텔을 남기고, 그 id를 상세 조회와 가격 조회로 넘깁니다.
- 여행 일정 비교: 같은 query를 check_in과 check_out만 바꿔 실행한 뒤 id로 묶어 일정별 요금 변화를 비교합니다.
- 호텔 분포 지도: location의 위도·경도에 stars와 요금을 겹쳐 지역 안에서 합리적인 호텔과 고급 호텔이 어디에 모여 있는지 확인합니다.
Google Hotels API 활용 팁
- 비교용 검색에는 매번 currency를 명시해 price.amount의 단위를 맞추세요.
- check_in과 check_out은 항상 함께 지정하세요. 30박을 넘거나 체크아웃이 체크인보다 이른 일정은 작업이 생성되기 전에 거부됩니다.
- 후속 조회는 호텔 이름이 아니라 id로 연결하세요. 같은 도시의 체인 호텔은 이름이 비슷한 경우가 많습니다.
- 반환된 호텔 1개당 0.15크레딧이 차감되므로 results_limit은 실제로 검토할 수만큼 설정하세요.
관련 API
Google Hotels API 외에 Google Hotels의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Google Hotel Details API — 호텔 ID로 구글 호텔의 프로필을 가져와 연락처, 편의시설, 주변 지역 점수, 평점 분포, 리뷰 주제, 예약 사이트별 요금을 반환합니다.
- Hotel Price Tracker API — 호텔 ID로 구글 호텔의 요금 캘린더를 가져와 앞으로 약 6~8주 동안 체크인 날짜별 최저 1박 요금을 반환합니다.