빠른 시작
키를 받고, 해당 줄을 복사한 후 실행하면 JSON 데이터를 확인할 수 있습니다.
0. 키 발급받기
무료 계정 만들기, API 키로 이동하여 키를 생성하세요. 그런 다음 이 키를 환경 변수에 저장하세요:
export FNA_KEY=fna_live_...1. 검색하기
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=climate+summit&size=2"{
"took_ms": 41,
"total": 1284,
"total_is_lower_bound": false,
"size": 2,
"offset": 0,
"results": [
{
"id": "9c1f8a4b2d3e5f6071829304a5b6c7d8",
"url": "https://example-news.com/world/climate-summit-opens",
"title": "Climate summit opens with a call for binding targets",
"description": "Delegates from 190 countries gathered on Monday ...",
"published_at": "2026-08-17T09:12:00Z",
"crawled_at": "2026-08-17T10:48:31Z",
"host": "example-news.com",
"sitename": "Example News",
"country": "GB",
"country_source": "cctld",
"lang": "en",
"tld": "com"
}
]
}해당 응답에서 주목해야 할 세 가지 필드가 있습니다. total은 반환된 기사 수가 아닌, 일치한 기사 수를 의미합니다. 속도를 위해 10,000로 제한되며, total_is_lower_bound는 해당 제한에 도달했음을 알려줍니다. country_source은 국가가 어떻게 결정되었는지를 나타내며, 이는 뉴스 데이터셋의 약 3분의 1의 국가 값이 사실보다는 추론에 기반하기 때문에 중요합니다. crawled_at는 정직한 타임스탬프로, 발행사는 published_at를 과거 날짜로 설정할 수 있지만 크롤링 시간은 파이프라인에 의해 할당됩니다.
2. 검색 범위 좁히기
필터는 파라미터 간에는 AND로, 단일 파라미터 내에서는 OR로 결합됩니다. 따라서 country=DE,AT&lang=de은 "독일어 기사 중 독일 또는 오스트리아에서 발행된 기사"를 의미합니다. 이는 우크라이나에서 발행된 오늘의 우크라이나어 기사를 최신순으로 요청하는 것입니다:
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"3. 본문 전체 가져오기
검색 결과에는 기본적으로 본문이 생략되어 응답 크기가 작아집니다. 실제로 원하는 기사를 선택한 후에 명시적으로 요청하세요:
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=inflation&full_text=true&size=5"전체 글자는 기사당 약 2,000–4,000자입니다. full_text=true가 포함된 기사 20개는 언어 모델 기준 약 40,000 토큰에 해당합니다. 먼저 검색 결과를 선택한 후 본문 데이터를 가져오세요. 토큰 비용을 참조하세요.
4. 나열하지 말고 개수 확인
종종 유용한 질문은 "기사 목록이 무엇인가"가 아니라 "여기에 자료가 있는지, 그리고 어디에 있는가"입니다. 이 확인은 페이지 결과 전체를 가져오는 데 수천 개의 토큰이 필요한 반면 약 200개의 토큰으로 비용의 일부분으로 처리할 수 있으므로, 검색 실행 여부를 결정하는 에이전트의 첫 번째 호출에 적합합니다.
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"응답은 일치하는 전체 데이터 집합에 대해 계산된 국가, 언어, 도메인 접미사, 발행 기관 및 일별 건수를 제공합니다.
Python에서
import os, requests
HEADERS = {"Authorization": "Bearer " + os.environ["FNA_KEY"]}
r = requests.get("https://freenewsapi.ai/v1/search", headers=HEADERS, params={
"q": "semiconductor export controls",
"date": "7d",
"lang": "en",
"size": 20,
"sort": "relevance",
})
for a in r.json()["results"]:
print(a["published_at"], a["host"], a["title"])JavaScript에서
const url = new URL("https://freenewsapi.ai/v1/search");
url.search = new URLSearchParams({ q: "central bank", date: "24h", size: "20" });
const { results } = await (await fetch(url, { headers: { Authorization: `Bearer ${FNA_KEY}` } })).json();
results.forEach(a => console.log(a.published_at, a.host, a.title));