자동 완성 Rapid용 API

여행자들이 검색할 때 관련 제안을 제공하세요

Typehead(GET /suggestions)는 지리적 지역, 관련 장소 및 이용 가능한 재고를 기반으로 여행객에게 추천 검색 기능을 제공할 수 있게 해주는 새로운 API 엔드포인트입니다. 이 엔드포인트는 부분 검색어와 사용자가 입력한 요청 매개변수를 바탕으로 제안 목록을 반환합니다. 계정에 자동 완성를 추가하시려면 담당 계정 관리자에게 문의해 주시기 바랍니다.

작동 방식

자동 완성 API는 언어 예측 도구로, 때로는 자동 완성 또는 자동 제안이라고도 불립니다. 검색 창에 입력된 부분 정보를 바탕으로 지역, 위치 또는 재고 목록을 반환합니다. 사용자가 검색창에 내용을 입력하면, 자동 완성 API는 도시, 지역, 재고 품목 또는 우편번호 정보를 바탕으로 최대 10개의 검색 결과를 반환하기 시작합니다. 여행자는 이 목록에서 항목을 선택하여 검색을 시작하거나, 계속 입력하여 자동으로 제안된 결과를 더욱 구체화할 수 있습니다.

예를 들어, “Memp”로 시작하는 검색을 하면 미국 테네시주 멤피스와 관련된 동네, 기차역, 공항 등 여러 지리적 옵션이 먼저 표시되고, 그 다음으로 미국 미주리주 멤피스가 나타납니다.

시작 가이드

API에 대해 알아보시려면 담당 계정 관리자나 Partner Connect 담당자에게 문의하셔야 합니다. 해당 측에서 접근 권한 승인을 요청할 것이며, 승인이 이루어지면 자동 완성를 포함하도록 귀하의 계약 내용을 수정할 것입니다. 귀사의 조직에 자동 완성 기능이 활성화되면, Partner Connect 담당자가 필요한 개발 작업을 지원해 드릴 것입니다.

출시 요구 사항:

• 인증 시 불투명 액세스 토큰 절차를 채택하여 사용해야 합니다.

>> 불투명 액세스 토큰에 대해 자세히 알아보기

• 액세스 토큰은 이를 요청한 것과 동일한 서킷 ID 또는 API 키에서만 사용할 수 있습니다.
• 액세스 토큰의 유효 기간은 4시간입니다.
• 새로운 액세스 토큰 요청은 해당 일정에 따라 일관되게 갱신되도록 구성되어야 하며, 너무 빈번하게 업데이트되어서는 안 됩니다.
• 언어와 요청 본문은 필수 매개변수입니다.

>> Rapid에서 지원하는 모든 언어 보기

자동 완성에 대한 Google Places 대체 옵션

자동 완성가 특정 검색 쿼리에 대한 결과를 반환할 수 없는 경우, Google Places로 “대체”하여 결과를 반환합니다. 이 시나리오에서 응답 본문은 다른 자동 완성 응답과 동일하게 보이지만, 결과가 Google을 통해 제공된 경우 다음과 같은 응답 헤더가 반환됩니다:Third-Party-Result-Source: Google. Google 대체 기능은 모든 파트너가 이용할 수 있지만, Switchbox 설정을 통해 Partner Connect에서 해당 기능을 활성화해야 합니다. 모든 파트너는 Google의 지침에 따라 적절한 출처 표기를 표시해야 한다는 것이 운영상의 필수 요건입니다. 저작권 표시 정책.

권한 부여 및 접근

현재 Rapid 버전 3을 사용 중인 파트너사는 API 엔드포인트를 통해 Rapid 자동 완성 API를 요청할 수 있습니다. 승인이 완료되면, 귀하의 기존 프로필에 API를 정상적으로 사용하는 데 필요한 권한이 부여됩니다.

>> OAuth 2.0 인증에 대해 알아보세요 .

제안 요청

Suggestions API를 사용하려면 요청 헤더와 쿼리 매개변수에 특정 정보가 포함되어야 합니다. 응답의 안정성을 높이기 위해 선택적 쿼리 매개변수를 포함할 수도 있습니다.

요청 헤더

필수 항목

• Accept: 클라이언트가 수신하기를 원하는 응답 형식을 지정합니다. 이 값은 .이어야 합니다 application/json.
• Accept-Encoding: 클라이언트가 수신하기를 원하는 응답 인코딩을 지정합니다. 이 값은 gzip``이어야 합니다.
• User-Agent: 통합 기능을 통해 캡처된 고객 요청의 헤더 문자열. 애플리케이션을 구축하는 경우, User-Agent 값은 {app name}/{app version}``이어야 합니다. 예를 들어,TravelNow/3.30.112.

쿼리 매개변수

필수 항목

• language: 응답에 사용될 언어를, 하이픈으로 연결된 ‘ two-digit ’ 언어 코드 및 국가 코드 쌍만을 사용하는 BCP47 형식의 하위 집합으로 지정합니다. w3.org 에 설명된 대로 ISO 639-1 알파 2 언어 코드와 ISO 3166-1 알파 2 국가 코드만 사용하십시오(예: language=en-US).
  >> 지원되는 언어 목록 보기
  >> #로 이동w3.org
• text: 쿼리할 입력 문자열로, 최대 150자까지 입력할 수 있습니다(예: text=Springfie).

Optional

• type: 사용자가 찾고 있는 장소를 설명합니다. 이 매개변수는 서로 다른 값을 지정하여 여러 번 전달할 수 있습니다(예: type=AIRPORT&type=CITY). 지정되지 않은 경우, 기본값으로 모든 유형이 포함됩니다. 사용 가능한 옵션은 아래의 ‘허용되는 값’ 표를 참조하십시오.
• line_of_business: 이 매개변수는 검색 휴리스틱을 제공하며, 유효한 값을 지정하면 응답의 관련성이 더욱 높아집니다. 이 매개변수는 선택 사항이지만, 생략할 경우 검색 결과에 영향을 미칠 수 있으므로 각 Rapid API에 대해 기본값을 설정해 두었습니다. 사용 가능한 옵션은 아래의 ‘허용되는 값’ 표를 참조하십시오.
• package_type: 사용자가 지정한 패키지 유형별로 필터링합니다. 사용 가능한 옵션은 아래의 ‘허용되는 값’ 표를 참조하십시오.
• feature: 추천 결과의 계산 방식을 변경합니다. 값으로는 hierarchy, nearby_airport, postal_code 등이 있습니다.
• region_id: 결과를 지정된 지역으로 필터링합니다.
• origin: 쿼리 텍스트가 목적지가 아닌 출발지인지 여부를 지정합니다. 기본 검색 설정에서는 목적지만 검색됩니다.
• limit: 응답에서 반환되는 제안의 최대 개수를 지정합니다. 이 값은 1에서 10 사이여야 합니다(예: limit=5). 이 매개변수가 지정되지 않은 경우, 기본값은 10입니다.

허용되는 값

참고: 위 표에 포함되지 않은 값을 입력하면 오류가 발생합니다.

데이터 요청

access_token를 확보한 후에는 GET 요청을 설정하게 됩니다.

샘플 요청 - 숙박 API

GET - https://api.ean.com/v3/suggestions?language=en-US&line_of_business=properties&limit=3&text=chicago&type=city&type=neighborhood 

Header : 
Authorization: Bearer {{access_token}}

답변 예시 - 숙박 API

[
  {
    "related_id": "4477519",
    "type": "airport",
    "name": "Chicago, IL (ORD-O'Hare Intl.)",
    "name_full": "Chicago, IL, United States of America (ORD-O'Hare Intl.)",
    "name_display": "<B>Chicago</B>, IL, United States of America (ORD-O'Hare Intl.)",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "ORD",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.976977,
      "longitude": -87.90481
    }
  },
  {
    "related_id": "829",
    "type": "city",
    "name": "Chicago",
    "name_full": "Chicago, Illinois, United States of America",
    "name_display": "<B>Chicago</B>, Illinois, United States of America",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "CHI",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.878113,
      "longitude": -87.629799
    }
  },
  {
    "related_id": "6350699",
    "type": "neighborhood",
    "name": "Downtown Chicago",
    "name_full": "Downtown Chicago, Chicago, Illinois, United States of America",
    "name_display": "Downtown <B>Chicago</B>, <B>Chicago</B>, Illinois, United States of America",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "CHI",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.885969845574834,
      "longitude": -87.62933540465228
    }
  }
]

오류 코드

자동 완성 API는 다른 Rapid API들과 공통된 오류 코드를 사용합니다.

>> 일반적인 오류 응답에 대해 자세히 알아보기

다른 Rapid API와의 연동

최종 사용자가 검색창에 텍스트를 입력하면, 자동 완성 API는 검색에 지정된 type 에 따라 지역(지역 ID, 이름, 좌표 등) 또는 항목 정보를 불러옵니다. 그런 다음 API는 해당 정보를 자동 완성 목록의 결과로 표시합니다.

사용자가 자동 완성 목록에서 지역을 선택하면, 해당 지역 주변의 재고 목록을 가져오기 위해 Region API가 호출됩니다. 해당 검색 결과에서 반환된 ID를 사용하여 조회 API를 호출하고, 이용 가능 여부를 확인한 뒤 목록을 표시하세요.

사용자가 자동 완성 목록에서 항목을 선택하면, 조회 API가 재고 현황 및 세부 정보가 포함된 상세 페이지를 생성합니다.

API 세부 정보

이 페이지에서 관련 엔드포인트 정의를 살펴본 후 API Explorer 또는 다른 테스트 소프트웨어를 사용하여 예시 및 스키마 정의가 실제 출력과 어떤 차이가 있는지 확인해 보세요.

추가 리소스

Rapid API 의 모든 엔드포인트를 직접 사용해 보시든, OpenAPI 사양이나 당사의 Postman 컬렉션을 다운로드하시든, 여러분이 필요로 하는 모든 것을 준비해 두었습니다.

API Explorer로 이동