웹 검색 API — 앱에 웹 검색 기능을 추가하세요 문서

1. 인증

api-key 및 Content-Type: application/json 헤더를 사용하여 서버에서 호출하세요. 키를 비공개로 유지하세요.

2. 요청 매개변수

요청은 쿼리, 개수 및 search_lang만 지원합니다. 쿼리는 자연어 질문이나 키워드를 허용합니다.

필드	유형	필수	설명
query	string	예	검색 질문 또는 키워드. 비워둘 수 없습니다.
count	integer	아니요	원하는 결과 수. 서비스 기본값을 사용하려면 0를 생략하거나 전달하세요.
search_lang	string	아니요	검색 언어(예: zh-hans). 이 서비스는 zh를 zh-hans로 정규화합니다. 지원되는 목록을 보려면 이 행을 클릭하세요.

3. 검색어 API에 전화하세요

POSThttps://api.starsg.ai/api/product/websearch/search

YOUR_API_KEY를 바꾸고 검색어를 검색 텍스트로 설정하세요. 개수 및 search_lang는 선택 사항입니다.

bash

curl -X POST 'https://api.starsg.ai/api/product/websearch/search' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "北京今天的天气",
  "count": 5,
  "search_lang": "zh-hans"
}'

본문 래퍼나 추가 /v1 없이 JSON 개체를 직접 보냅니다.

4. 결과 읽기

먼저 성공 여부를 확인하세요. 성공하면 data.references 및 data.data를 읽습니다. 실패 시 errorCode 및 errorMsg를 검사합니다. 아래 웹 콘텐츠는 예시입니다.

성공응답

json

{
  "success": true,
  "data": {
    "references": [
      {
        "website": "example.com",
        "logo": "https://example.com/favicon.ico",
        "title": "스마트 홈 뉴스 예시",
        "url": "https://example.com/article",
        "summary": "검색 결과 요약이 여기에 표시됩니다.",
        "published": "",
        "extra": {}
      }
    ],
    "data": [
      "검색 결과 요약이 여기에 표시됩니다."
    ]
  },
  "errorCode": null,
  "errorMsg": null
}

`data.references`	제목, 링크, 요약이 포함된 웹 참고 자료입니다.
`data.data`	외부 데이터 개체 내에 중첩된 결과 텍스트 목록입니다.
`references[].website / logo`	웹사이트 이름 또는 도메인 및 로고 URL.
`references[].title / url / summary`	결과 제목, 원본 페이지 URL 및 요약.
`references[].published / extra`	출판 날짜 및 추가 정보. 비어 있을 수 있습니다.

success=true인데 references와 data 배열이 비어 있으면 유효한 결과가 없다는 뜻입니다. 다른 키워드나 검색 언어를 사용해 보세요. API 오류로 처리하지 마세요.

오류 응답

json

{
  "success": false,
  "data": null,
  "errorCode": "PARAM_INVALID",
  "errorMsg": "query is required"
}

일반적인 오류 및 다음 단계

`PARAM_INVALID`	JSON를 확인하고 쿼리하세요. 재시도하기 전에 매개변수를 수정하세요.
`SEARCH_FAILED`	검색에 실패했습니다. 시도 횟수를 제한하여 나중에 다시 시도하세요. 지속적인 오류가 발생하는 경우 지원을 위해 호출 시간과 요청 식별자를 저장하세요.