찾을 네이버 뉴스 검색어를 알려주세요. 예: "삼성전자 실적", "인공지능 규제", "금리 인상"
단어 2글자 미만이면 의미가 불분명하므로 되묻는다.
Proxy endpoint
기본값은 public/read-only/no-auth 프록시다. 사용자는
네이버 개발자 센터 Client ID/Secret 을 발급받지 않아도 된다
. upstream key(
NAVER_SEARCH_CLIENT_ID
/
NAVER_SEARCH_CLIENT_SECRET
)는 프록시 서버에서만 주입한다.
curl
-fsS
--get
"
${KSKILL_PROXY_BASE_URL
:-
https
:
/
/
k-skill-proxy.nomadamas.org}
/v1/naver-news/search"
\
--data-urlencode
'q=삼성전자 실적'
\
--data-urlencode
'display=10'
\
--data-urlencode
'sort=date'
쿼리 파라미터:
q
또는
query
— 검색어. 2글자 이상.
display
— 반환 건수. 기본 10, 범위 1~100.
start
— 검색 시작 위치(1-indexed). 기본 1, 최대 1000.
start + display - 1
은 1000 을 넘을 수 없다
예를 들어
start=1000 & display=100
은
1099
번째 아이템을 요구하므로 proxy가 업스트림 호출 전에
400 bad_request
("start + display exceeds Naver's 1000-item search window")로 거절한다. 아주 오래된 기사를 찾으려면 검색어를 좁히는 것이 낫다.
sort
—
sim
(유사도 순, 기본값) 또는
date
(최신순). 그 외 값은
sim
으로 fallback.
응답 주요 필드:
items[].title
—
태그·HTML entity 가 제거된 기사 제목
items[].description
—
태그·HTML entity 가 제거된 기사 요약
items[].link
— 네이버 뉴스 redirect 링크
items[].original_link
— 원문 뉴스 링크(빈 문자열이면
null
)
items[].pub_date
— 원본 RFC822 형식 발행 시각
items[].pub_date_iso
— 파싱된 ISO-8601(UTC) 발행 시각. 파싱 실패시
null
meta.extraction
— 항상
naver-openapi
meta.total
,
meta.start
,
meta.display
,
meta.last_build_date
,
meta.sort
Workflow
검색어를 확인한다. (없거나 2글자 미만이면 먼저 물어본다)
사용자가 "최신순"을 원하면
sort=date
, 그 외에는
sort=sim
으로 호출한다.
GET /v1/naver-news/search
를 호출한다.
items
가 있으면 상위 3~5건을 제목, 발행 시각(KST 기준으로 재포맷해도 좋다), 요약, 링크로 짧게 정리한다.
발행 시각은
pub_date_iso
기준으로 오늘/어제 표기를 붙여도 된다. (KST = UTC+9)
items
가 비었거나
upstream_error
가 나면 재시도하지 말고 검색어를 좁혀 다시 물어본다.
Response style
기사 제목/요약은 API 가 돌려준 원문만 인용한다. 원문에 없는 해설은 덧붙이지 않는다.
기사 발행 시각은 "KST 기준 {YYYY-MM-DD HH:mm}" 또는 "{n}시간 전" 정도로 짧게 표시한다.
원문 링크(
original_link
)가 있으면 우선 노출하고, 없으면
link
(네이버 뉴스 redirect)를 안내한다.
서로 다른 언론사가 같은 사건을 다루면 링크 2~3개를 병렬로 제시해 사용자가 비교할 수 있게 한다.
description
은 요약이므로, 팩트로 단정하지 말고 "기사 요약에 따르면"이라고 전한다.
Failure modes
400 bad_request
— 검색어 누락, 2글자 미만, 허용되지 않는 파라미터, 혹은
start + display - 1 > 1000
조합(네이버 1000-item search window 초과). 에러 메시지를 그대로 사용자에게 노출한다.
503 upstream_not_configured
— 프록시 서버에
NAVER_SEARCH_CLIENT_ID
/
NAVER_SEARCH_CLIENT_SECRET
가 없는 경우. 운영자가 키를 등록해야 한다. 사용자에게는 "잠시 후 다시 시도해 주세요" 정도로 안내한다.
401 upstream_error
— 프록시 서버의 Client ID/Secret 이 잘못된 경우(
errorCode: 024
). 운영자가 재발급해야 한다.
429 upstream_error
— 네이버 검색 API 일일 쿼터(25,000 호출/일) 초과(
errorCode: 010
). 재시도 루프는 금지. 잠시 후 다시 시도하도록 안내한다.
502 upstream_error
— 네이버 API 5xx 또는 응답 JSON 파싱 실패.
upstream 차단이나 장애 발생 시 재시도하지 않는다. cache + rate limit 만으로 대응하고, 사용자에게는 현재 조회 불가능함을 분명히 말한다.
Privacy
검색어/결과를 영구 저장하지 않는다.
기사 본문은 요청하지 않는다. description(API 가 주는 요약)만 사용한다.
특정 인물·사건을 비방·추측하는 서술은 하지 않는다. 기사 원문만 전달한다.
Done when
검색어를 확인했다.
최소 1건 이상의 기사를 제목·요약·발행 시각·링크로 정리해서 돌려주거나, 왜 결과가 없는지 설명했다.
발행 시각은 KST 기준으로 표시했다.
네이버 API 쿼터 상태·차단 발생 여부·재시도 금지 원칙을 지켰다.
로그인/개인화/차단 우회 범위를 벗어나지 않았다.