뉴스 API은 일반적으로 요청 단위로 판매되며, 키 뒤에 숨겨져 있고 무료 티어에서는 하루 100회 호출로 제한됩니다. Free News API은 이러한 제한이 없습니다: 롤링 90일 기간 내 2,150만 편의 기사, 25,000개 이상 출판사, 키 없음, 회원가입 없음, 쿼터 없음, 상업적 사용 허용. 검색, 통계, 트렌드, 시장, 피드 및 MCP을 포함한 전체 서비스 범위와 데이터가 정확하지 않을 수 있는 부분에 대한 솔직한 설명을 소개합니다.
문제의 구조
AI 에이전트에게 현재 세계가 무엇에 대해 쓰고 있는지 물어보면 세 가지 나쁜 선택지 중 하나를 선택해야 합니다. 출판사에서 직접 스크랩할 수 있는데, 이는 불안정하고 느리며 법적 모호성이 있습니다. 상업용 뉴스 API을 호출할 수 있는데, 이는 계정, 키, 월 요금을 의미하며 — 시장상의 모든 무료 티어에서 — 하루 100회 요청과 24시간 지연된 기사를 의미합니다. 또는 몇 달 전까지만 학습된 훈련 데이터에서 추측할 수 있습니다.
Free News API은 중간 옵션의 가격과 서류 작업을 제거하면서도 그 기능을 유지합니다. 작성 시점에서 21,557,044편의 기사를 포함하고 25,000개 이상의 출판사로부터 수집된 코퍼스를 대상으로 한 GET 요청 하나, 자격 증명 불필요, 롤링 90일 기간 유지, 지속 업데이트 — 인덱스의 최신 기사는 일반적으로 2분 미만의 나이입니다.
4개의 핵심 엔드포인트와 그 외
서비스의 핵심은 네 개의 GET 엔드포인트로, 모두 https://freenewsapi.ai 하위에 위치하며, 모든 응답은 UTF-8 JSON 형식이며 Access-Control-Allow-Origin: * 헤더를 포함하여 브라우저 코드에서 직접 호출할 수 있고, 서버 측 실행 시간은 took_ms로 보고됩니다.
| 엔드포인트 | 질문 내용 |
|---|---|
GET /v1/search | 필터 적용 전역 텍스트 검색. 95%의 경우 사용하게 될 엔드포인트입니다. |
GET /v1/stats | 국가, 언어, TLD, 발행자, 날짜별 등 모든 데이터 슬라이스에 대한 집계 카운트. |
GET /v1/article | 정확한 URL의 기사 하나와 본문 전체. |
GET /health | 현재 문서 수를 포함한 라이브니스. 폴링하기에 충분히 저렴합니다. |
이 핵심을 둘러싸고 네 가지 더 많은 계열이 자리 잡고 있으며, 각 계열은 다른 곳에서는 독립적인 제품이 됩니다: 트렌드(국가별 실시간 스토리 클러스터링), 시장(커버리지 양과 일치하는 가격 시리즈), 암호화폐 심리(7개 엔드포인트 비트코인 블록), 신디케이션(RSS, Atom 또는 JSON 피드로 렌더링된 동일한 검색). 이 모두는 아래에서 다룹니다.
curl "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_is_lower_bound는 일치 건수가 10,000의 상한에 도달하여 카운팅을 중단했을 때 알려줍니다. country_source는 국가가 어떻게 결정되었는지 알려줍니다. 뉴스 데이터셋에서 국가 값의 많은 부분이 사실이라기보다는 추론이기 때문입니다. 그리고 crawled_at은 신뢰할 수 있는 타임스탬프입니다. 발행자는 published_at을 routinely로 역일자를 입력하지만, 크롤링 시간은 파이프라인에 의해 할당되며 항상 앞으로만 진행됩니다.
검색: 중요한 모든 매개변수
모든 매개변수는 선택사항입니다. 기본 호출은 인덱스에서 가장 최신 기사를 반환합니다.
쿼리
- q 제목(가중치 3), 설명(가중치 2) 및 기사 본문과 일치합니다. AND 논리 — 모든 용어가 존재해야 하므로 단어를 추가하면 범위가 넓어지는 것이 아니라 좁아집니다. 최대 500자.
opec production cut은 작동합니다. what did OPEC decide about oil은 아무것도 반환하지 않습니다.필터
필터는 매개변수 간 AND 및 하나의 매개변수 내 OR과 결합합니다. 따라서 country=DE,AT&lang=de는 "독일 또는 오스트리아의 독일어 기사"를 의미합니다. 각 필터는 최대 50개의 값을 받는 쉼표로 구분된 목록을 허용합니다.
| 필터 | 형식 | 참고 사항 |
|---|---|---|
country | ISO 3166-1 alpha-2, 대문자 | 게시자 국가. 의존적 파생, 미표기 — country_source 및 strict_country를 참조하세요. |
lang | ISO 639-1, 소문자 | 문서 자체에서 감지. 99.9%의 커버리지. |
tld | 접두사 없음 | 게시자의 도메인 존. tld=ua는 사실이며, country=UA는 추론입니다. |
host | 정확한 호스트명 | URL에 나타난 대로 — 게시자가 www.을 사용하는 경우 포함. |
date | 오늘 · 어제 · 24시간 · 48시간 · 7일 · 30일 | published_at을 기준으로 평가되는 사전 설정 기간입니다. |
from / to | ISO 날짜 | 사전 설정이 맞지 않는 명시적인 기간. |
strict_country | true/false | 국가 정보가 추정이 아닌 명확한 사실인 기사만 카운트합니다. |
출력 제어
| 매개변수 | 값 | 효과 |
|---|---|---|
sort | date · date_asc · crawled · crawled_asc · relevance | 새로운 기사를 폴링할 때는 crawled 기준으로 정렬 — 발행사는 게시 시간을 과거로 역산하는 경우가 많지만, 크롤링 시간은 항상 앞으로만 진행됩니다. |
size | 1–100 | 페이지당 결과 수. |
offset | 0–9900 | 페이징 오프셋. |
full_text | true/false | 본문 포함. 기본값은 꺼짐. |
highlight | true/false | 일치하는 단편 반환. |
fields | CSV | 실제로 사용하는 필드로 응답을 제한하세요. |
curl "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"curl "https://freenewsapi.ai/v1/search?q=merger&country=DE&date=48h&sort=date&size=20"검색 전 카운팅
서비스에서 가장 활용도가 낮은 엔드포인트는 /v1/stats입니다. 종종 유용한 질문은 "기사 목록이 무엇인가"가 아니라 "여기에 아예 자료가 있는지, 있다면 어디에 있는가"입니다. 카운팅은 결과 페이지를 가져오는 데 수천 토큰이 필요한 반면 비용은 약 200 토큰 정도로 매우 저렴하므로, 검색 실행 여부를 결정하는 에이전트의 첫 번째 호출로 적합합니다.
curl "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"이 엔드포인트는 전체 일치 집합을 기준으로 국가, 언어, TLD, 발행자, 일별 카운트를 반환하며 현재 페이지의 데이터만 기준으로 하지 않습니다. 이를 통해 신뢰하기 전에 커버리지를 측정할 수도 있습니다. 작성 시점의 필터링되지 않은 스냅샷:
주요 국가
| 국가 | 기사 |
|---|---|
| 인도 | 2,286,014 |
| 미국 | 2,180,797 |
| 터키 | 1,499,897 |
| 러시아 | 1,436,556 |
| 이탈리아 | 1,057,479 |
| 아르헨티나 | 826,947 |
| 스페인 | 812,347 |
| 우크라이나 | 662,041 |
| 브라질 | 551,013 |
| 독일 | 543,132 |
| 프랑스 | 502,846 |
| 그리스 | 460,372 |
| 일본 | 437,209 |
| 베트남 | 408,934 |
| 멕시코 | 402,320 |
| 한국 | 362,945 |
| 루마니아 | 354,229 |
| 영국 | 334,379 |
| 이란 | 291,782 |
| 폴란드 | 255,599 |
주요 언어
영어 5,513,650 · 스페인어 2,699,457 · 러시아어 1,785,796 · 터키어 1,501,004 · 이탈리아어 992,200 · 독일어 733,677 · 프랑스어 689,136 · 아랍어 664,016 · 포르투갈어 637,607 · 힌디어 560,840 · 그리스어 466,504 · 일본어 427,085 · 베트남어 385,719 · 루마니아어 358,766 · 중국어 352,720 · 우크라이나어 345,809 · 한국어 335,079 · 페르시아어 268,126 · 폴란드어 238,904 · 불가리아어 183,204.
이 분포는 잠시 주목할 가치가 있습니다. 왜냐하면 이는 대부분의 뉴스 API이 제공하는 내용과 정반대이기 때문입니다. 영어 우선, 미국 중심의 일반적인 데이터셋과는 다릅니다: 인도가 미국보다 상위권을 차지하고, 터키어가 독일어를 앞지르며, 그리스어, 베트남어, 페르시아어, 불가리아어도 6자리 수의 표현을 가지고 있습니다. 만약 질문이 영어권 언론이 아닌 다른 언론에 관한 것이라면, 이는 실질적으로 다른 데이터셋입니다.
볼륨
by_day의 일별 곡선은 전체 90일 기간을 커버합니다. 최근 며칠은 하루에 약 400,000개에서 700,000개의 기사가 있는 범위에 위치합니다. RSS 레이어가 아카이브 ingestion과 함께 추가되기 전의 초기 기간에는 일일 볼륨이 130,000~230,000이었습니다. 두 수치 모두 동일한 응답에서 확인할 수 있으며, 이것이 핵심입니다 — 이 서비스는 마케팅 평균을 인용하는 대신 자체적인 증가세를 보여줍니다.
트렌드: 언론이 지금 실제로 다루고 있는 것
검색은 "X에 대해 무엇을 썼는가"라는 질문에 답합니다. 트렌드는 서로 다르고 종종 더 나은 질문인 "무슨 일이 일어나고 있는가"에 답합니다 — X는 필요 없습니다.
로봇은 기사를 국가별 스토리로 클러스터링하고 최신 상태로 유지합니다. 5분마다 새로운 기사가 식별 단어를 통해 기존 스토리에 연결되며, 모델 호출은 전혀 발생하지 않습니다. 몇 시간마다 한 국가가 전체 통과를 거치며 언어 모델이 헤드라인을 읽고 스토리를 처음부터 명명합니다. 트렌드 레이어는 작성 시점 기준으로 115개국을 커버하며, 각 국가는 최근 몇 분 이내에 다시 계산됩니다.
curl "https://freenewsapi.ai/v1/trends?country=US&window=24h&size=5"{
"window": "24h",
"filters": { "country": ["US"], "min_publishers": 1 },
"trends": [
{
"title": "Hurricane Marie threatens Labor Day weather",
"slug": "hurricane-marie-threatens-labor-day-weather",
"country": "US",
"category": "weather",
"articles": 57,
"publishers": 24,
"first_seen": "2026-09-05T19:24:36Z",
"latest": "2026-09-06T19:00:04Z",
"url": "https://freenewsapi.ai/trends/us/hurricane-marie-…",
"headlines": [ … ]
}
]
}각 스토리에는 두 가지 수치가 함께 제공되며 서로 다른 의미를 가집니다. articles는 시끄러움(주목도)을 나타내고, publishers는 폭(广度)을 나타냅니다. 4개 매체에서 200개의 기사가 있는 스토리는 한 뉴스룸의 집착입니다. 40개 매체에서 60개의 기사가 있는 스토리는 사건입니다. 기본 정렬은 publishers 기준이며, min_publishers / min_articles를 통해 직접 기준을 설정할 수 있습니다.
스토리에는 politics(정치), business(비즈니스), markets(시장), tech(기술), sport(스포츠), health(건강), science(과학), culture(문화), crime(범죄), conflict(분쟁), weather(날씨), society(사회) 등 고정된 카테고리 중 하나가 할당됩니다.
시간 범위는 로봇이 아닌 독자의 선택입니다.
이것은 진정으로 우아한 디자인 결정입니다. 모든 기고는 발행 시간과 함께 저장되며, 해당 스토리와 연결됩니다. 따라서 15분, 1시간, 하루, 특정 날짜 등 어떤 시간 범위든 동일한 저장 데이터에 대한 범위 쿼리로 처리됩니다. 하나의 연산으로 모든 시간 범위를 동시에 처리할 수 있습니다. window=15m, window=1h, window=24h, date=2026-09-01, 또는 명시적인 since/until 쌍 모두 동일한 인덱스에서 재계산 없이 작동합니다.
키워드: 뉴스의 기반이 되는 단어
curl "https://freenewsapi.ai/v1/trends/keywords?country=US&size=8"각 키워드는 해당 키워드를 포함하는 고유 스토리의 수, 해당 스토리들이 포함하는 기사 수, 그리고 가장 흥미로운 지표인 해당 키워드를 사용하는 국가별 언론사의 수와 함께 반환됩니다. 마지막 숫자는 글로벌 이벤트인지 국내 이벤트인지를 구분합니다. 70개국에서 사용되는 단어는 세계적 사건이며, 한 국가의 언론을 지배하는 단어는 그 국가 내에서 얼마나 큰 소리를 지르든 국내 사건입니다.
실시간으로 추적 중인 국가
curl "https://freenewsapi.ai/v1/trends/countries"추적 중인 모든 국가와 해당 국가의 실시간 스토리 수, 그리고 마지막 재계산 후 경과한 분수를 반환합니다. 터키, 러시아, 이란, 그리스, 인도, 이탈리아, 우크라이나, 루마니아, 아르헨티나, 독일, 브라질은 현재 각각 수천 건의 실시간 스토리를 보유하고 있으며, 10분 이내에 재계산되었습니다. 또한 /v1/trends/{cc}/{slug} 엔드포인트를 통해 단일 스토리와 해당 스토리의 전체 기사 목록을 확인할 수 있습니다.
시장 데이터 vs. 보도량: 한 축에는 가격, 다른 축에는 주목도
이것은 서비스에서 가장 특이한 기능이며, 코퍼스(corpus) 구축 비용이 거의 들지 않기 때문에 구현되었습니다. 특정 시간대 동안 그 대상에 대해 세계가 얼마나 많이 보도했는지를 가격 시열과 함께 하나의 타임라인에 나란히 배치합니다.
curl "https://freenewsapi.ai/v1/markets"네 가지 자산 클래스에 걸쳐 14가지 금융 상품이 추적됩니다:
| 자산 클래스 | 추적 대상 | 데이터 간격 | 데이터 소스 |
|---|---|---|---|
| 암호화폐 | 비트코인, 이더리움, 솔라나, XRP, BNB, 도지코인 | 시간 | 바이낸스 |
| 금속 | 금 (USD/oz) | 시간 | 바이낸스 |
| 외환 | EUR/USD, USD/JPY, USD/TRY, USD/INR, USD/BRL, USD/PLN | 일 | 유럽중앙은행(ECB) |
| 에너지 | 독일 전력 가격 (EUR/MWh) | 시간 | Energy-Charts |
curl "https://freenewsapi.ai/v1/markets/usd-try?window=30d"이 단일 호출을 통해 달러 대비 위안화 환율과 동일한 기간 동안 터키 언론의 보도량을 시간별로 정렬하여 확인할 수 있습니다. 터키 언론은 이 코퍼스에서 세 번째로 큰 비중을 차지하므로, 이 조합은 노이즈가 아닌 의미 있는 결과를 만들어냅니다.
그리고 비트코인 감정 분석 블록 전체
비트코인은 자체적인 7개 엔드포인트 패밀리로 제공되는데, 이는 뉴스의 어조와 가격 변동이 끊임없이 논쟁되지만 거의 측정되지 않는 유일한 자산이기 때문입니다:
| 엔드포인트 | 반환값 |
|---|---|
/v1/btc/summary | 최신 가격, 최근 변동, 그리고 오늘의 보도 어조. |
/v1/btc/price | 간격별 BTC/USDT 캔들. |
/v1/btc/sentiment | 기간별 뉴스 어조. |
/v1/btc/series | 가격과 어조를 하나의 타임라인에 정렬. |
/v1/btc/correlation | 시간 차이에 따른 어조와 가격 변동의 상관관계 — 보도가 가격을 선도하는지, 아니면 추종하는지? |
/v1/btc/news | 감성 레이블이 부여된 암호화폐 기사, 레이블, 호스트, 언어, 쿼리로 필터링 가능. |
/v1/btc/sources | 암호화폐 보도를 주도하는 매체는 무엇이며, 각 매체가 어떤 성향을 띠고 있는지 |
감성 라벨은 매 5분마다 새로운 암호화폐 기사를 처리하고 교정된 코인 목록을 기준으로 분석하는 언어 모델에서 생성됩니다. "뉴스가 가격 변동을 유발한다"는 주장을 반복하기보다 검증해 보고 싶다면 /v1/btc/correlation 엔드포인트의 max_shift 파라미터를 사용하세요.
피드로 제공하는 동일한 검색
세 가지 추가 엔드포인트는 동일한 검색 파라미터를 받아 결과를 JSON 대신 Syndication 형식으로 렌더링합니다:
GET /v1/rss— RSS 2.0GET /v1/atom— Atom 1.0GET /v1/feed.json— JSON Feed 1.1
https://freenewsapi.ai/v1/rss?q=semiconductor+export+controls&lang=en&date=7d&sort=date즉, 저장된 검색 쿼리는 코드나 API 키 없이도 리더기, n8n 노드, Slack 통합, Zapier 트리거 또는 정적 사이트 생성기에 붙여넣을 수 있는 피드가 됩니다. 이 작은 기능은 비개발자를 위한 통합 레이어 전체를 조용히 제거합니다.
MCP: 28개 도구, 두 가지 계층
MCP 서버는 단일 URL에서 실행되며 Streamable HTTP(JSON-RPC 2.0 over POST, 프로토콜 버전 2025-06-18)를 지원하고 배치 처리를 허용합니다. 또한 여기서 모든 것과 마찬가지로 인증 단계나 세션 ID가 없습니다.
claude mcp add --transport http freenewsapi https://freenewsapi.ai/mcp두 가지 의도된 계층에 걸쳐 28개의 도구를 노출합니다.
계층 1: 한 번의 호출로 전체 질문에 답변하는 6가지 단축키
| 도구 | 용도 |
|---|---|
search_news | "X에 대해 무엇을 썼는가" — 전체 텍스트 검색, 결과 간소화 |
get_trends | "현재 이슈" — 기사 목록이 아닌 그룹화된 스토리. |
trend_keywords | 현재 뉴스의 기반이 되는 단어들과 스토리 수, 국가별 분포. |
find_publishers | 매체 조회: 이름, 도메인, 국가, 언어, 일일 발행 기사 수. |
list_countries | 어떤 국가에서 실시간 스토리가 제공되는지, 그 수와 최신성. |
market_vs_news | 가격 시계열과 커버리지 볼륨을 함께 표시합니다. 어떤 종목이 존재하는지 확인하려면 인스트루먼트 없이 호출하세요. |
2단계: 서비스 자체에서 생성된 모든 엔드포인트
단축키 아래에는 각 원시 엔드포인트가 별도의 도구로 노출됩니다. API이 허용하는 모든 파라미터를 포함하여 news_get_search, news_get_stats, news_get_article, news_get_trends, news_get_trends_keywords, news_get_markets_slug, 전체 news_get_btc_* 패밀리, 피드 렌더러, 그리고 news_get_health가 있습니다. 이들은 라이브 서비스에서 생성되므로 API이 실제로 허용하는 내용과 어긋날 수 없습니다.
두 개의 메타 도구가 전체 과정을 완성합니다. news_list_endpoints는 존재하는 모든 것의 카탈로그를 반환하며, news_get은 임의의 경로에 대한 원시 GET을 수행합니다. 따라서 도구 목록에 포함되지 않은 엔드포인트를 마주한 에이전트도 여전히 해당 엔드포인트에 접근할 수 있습니다.
curl "https://freenewsapi.ai/mcp?format=json"GET 하나, 핸드셰이크 없이 전체 기계 판독 가능한 카탈로그를 얻습니다: 서버, 트랜스포트, 프로토콜, 도구 수, 설명이 포함된 모든 도구, 그리고 파라미터 목록이 포함된 모든 엔드포인트.
기계 읽기용으로 설계됨
이 문서는 API에 부가적으로 붙여진 것이 아니라 그 자체의 주요 출력물입니다. 사이트는 665개의 정적 페이지를 제공하며, 그중 여러 페이지는 모델이 HTML을 읽지 않아도 되도록 특별히 존재합니다:
- /openapi.json 전체 OpenAPI 스키마.
- /llms.txt 서비스의 개요, 엔드포인트, 효율적인 쿼리 방법, 오류 등을 설명하는 짧은 안내 파일.
- /llms-full.txt 전체 문서를 하나의 일반 텍스트 파일로 제공하며, 크기가 100킬로바이트를 훨씬 초과합니다. 이를 통해 에이전트가 한 번의 요청으로 전체 매뉴얼을 한 번에 로드할 수 있습니다.
- /agents 에이전트 빌더를 위한 39개의 페이지: 미리 준비된 OpenAI 함수 정의, Anthropic 도구 사용 정의, 뉴스 검색용 시스템 프롬프트, RAG 레시피, 토큰 비용 표, 에이전트 레시피 등이 포함되어 있습니다.
- /agents/models 모델 계열별 도구 호출 코드 — Qwen, DeepSeek, MiniMax, Kimi, GLM, Doubao, Hunyuan, ERNIE, Yi, Step, GPT, Claude, Gemini, Grok, Mistral, Llama, Command, Nova, Phi, Jamba, Sonar, OpenRouter, Ollama, vLLM.
- /data 코퍼스 내부 구조, 방법론, 인덱스 스키마, 그리고 데이터셋의 오류를 문서화한 데이터 품질 페이지.
- /sources 국가, 언어, 도메인 존으로 필터링 가능한 11,668개 발행인 목록의 브라우저 가능한 카탈로그.
- /compare NewsAPI.org, GNews.io, NewsData.io, Mediastack, Currents, TheNewsAPI, NewsCatcher, WorldNewsAPI, Perigon, APITube, FreeNewsAPI.io와의 비교 페이지.
168개 국가 페이지, 121개 언어 페이지, 275개 TLD 페이지를 추가로 제공하며, 코퍼스의 각 부분을 위한 하나의 탐색 가능한 인터페이스를 통해 각 항목이 실제로 무엇을 포함하고 있는지 확인할 수 있습니다.
기사의 출처
두 가지 수집 경로가 동일한 색인(index)에 데이터를 공급하며, 이 두 경로 간의 차이가 중요합니다.
아카이브 경로
10분마다 작업이 Common Crawl의 CC-NEWS 아카이브에서 새로운 WARC 파일을 확인하고 이전에 처리하지 않은 파일을 40개의 병렬 워커를 사용하여 처리합니다. 추출기는 필드별로 문서화된 캐스케이드를 사용하여 원시 크롤 데이터에서 각 기사를 추출하며, 이 캐스케이드는 가정하는 것이 아닌 실제 데이터를 기준으로 측정되었습니다:
| 필드 | 캐스케이드 | 커버리지 |
|---|---|---|
| description | JSON-LD → meta → OpenGraph → Twitter 카드 → articleBody → 리드 문단 | 98.1% |
| language | <html lang> → JSON-LD inLanguage → og:locale | 99.9% |
| country | ccTLD → JSON-LD addressCountry → 언어-지역 → og:locale | 79.1% |
| date | JSON-LD datePublished → meta → trafilatura → 크롤 시간 | 100% |
이 국가 데이터는 신뢰할 수 있는 정보입니다. 이것이 바로 모든 기사에 country_source 필드를 노출하는 이유입니다. 전체 레코드의 약 5분의 1은 신뢰할 만한 국가 신호가 전혀 없으며, 존재하는 값의 약 3분의 1은 사실이라기보다 추론에 기반한 것입니다. API은 추론인지 사실인지를 구분하여 알려줍니다. 속임수를 쓰지 않습니다.
실시간 데이터 경로
두 번째 로봇은 5분마다 발행처의 RSS 피드를 폴링합니다. 조건부 요청이 포함된 회전 방식으로 작동하며, 304 Not Modified 응답을 반환하는 피드는 거의 비용이 들지 않습니다. 각 피드의 폴링 간격은 실제 게시 빈도에 맞춰 조정됩니다. 하루에 5편의 기사를 게시하는 매체는 15분마다 과도하게 폴링되지 않습니다.
또한 발행처가 피드에 제공한 정보(제목, 요약, 피드에 포함된 경우 본문)만 가져옵니다. 발행처 웹사이트에 접속하여 추가 정보를 가져오지 않습니다. 이는 의도적인 제한이며, 이 서비스가 발행처 대상 법적 페이지에서 약속하는 내용을 지킬 수 있는 이유입니다.
주변의 작동 구조
두 개의 데이터 수집 경로 주변에는 일곱 가지 이상의 스케줄 기반 로봇들이 배치되어 있습니다. 소스 발견 및 동기화, 도메인별 국가 확인, 트렌드 구축 및 감사, 키워드 백필, 암호화폐 감정 분석, 시장 데이터 추출, 분류학 카탈로그 구축, 유지 관리(90일 윈도우는 인덱스 연령이 아닌 published_at 필드에 대한 일일 쿼리로 강제 적용됨), 일일 검증, 빈 기사 재확인, 그리고 중단된 프로세스를 재시작하는 헬스 가드가 있습니다. 코퍼스는 전용 Elasticsearch 클러스터에 저장됩니다.
이 데이터셋의 한계
이 서비스는 자체 한계를 공개합니다. 이는 해당 데이터셋이 당신의 문제 해결에 적합한지 판단하는 가장 빠른 방법입니다.
- 국가 정보는 추론됨 모든 기사에서
country_source필드를 확인하세요. 국가별 집계 시에는strict_country=true파라미터를 사용하세요. - published_at은 발행처 제공 값임 과거 날짜로 설정되는 경우가 많습니다. 새로운 콘텐츠를 폴링할 때는
crawled필드로 정렬하세요. - total은 10,000으로 제한됨 속도 때문입니다.
total_is_lower_bound필드는 최대 한계에 도달했음을 알려줍니다. - 감정 분석 또는 엔티티 추출 없음 비트코인 블록 외부의 기사에는 감정 점수나 명명된 엔티티(Named Entities)가 없습니다. 이는 이 서비스의 범위에 포함되지 않습니다.
- 90일, 그 이상은 제공하지 않습니다 더 깊은 아카이브가 없습니다. 2019년의 데이터가 필요하다면 이 도구는 적합하지 않습니다.
- SLA 없음 무료입니다. 모니터링과 보호도 이루어지지만, 서면으로 보장되는 내용은 없습니다.
- 텍스트는 발행인의 소유입니다 모든 응답에는 원본 URL이 포함되며, 호출자는 해당 원본으로 링크를 걸어줄 것이 기대됩니다.
잘 사용하는 법: 비용, 페이지네이션 및 오류
토큰 관리
에이전트에게 응답 크기가 실제 비용입니다. 문서화된 응답 형태는 다음과 같습니다:
| 호출 | 대략적인 토큰 비용 | 시점 |
|---|---|---|
/v1/stats | ~200 | 첫째, 검색 실행이 타당한지 여부를 결정하세요. |
/v1/search 메타데이터 전용 | 페이지당 수천 건 | 스캔하고 선택하세요. |
/v1/search?full_text=true | 기사당 약 900개 | 실제로 선택한 소수 기사에만 해당됩니다. |
full_text=true 옵션을 적용한 기사 20편은 약 40,000개의 토큰에 해당합니다. 권장 패턴은 항상 동일합니다. 카운트하고, 스캔한 후, 필요한 소수 기사만 본문을 가져옵니다.
한도 초과 페이지네이션
offset은 9,900에서 멈춥니다. 대규모 데이터셋을 탐색할 때는 한도에 맞서기보다 시간 단위로 데이터를 분할하세요. from/to 파라미터와 sort=date 옵션을 사용해 하루 단위 또는 빈번한 쿼리의 경우 시간 단위씩 루프를 돌리세요. 문서에는 하루 전체를 탐색하는 방법에 대한 전용 페이지가 있습니다.
오류
계약 조건은 명확하고 구현하기 쉽습니다. 4xx는 요청에 오류가 있음을 의미하므로 수정해야 하며 재시도하지 마세요. 5xx는 서비스 장애를 의미하므로 백오프하세요. 429는 속도를 늦추고 재시도하세요. 알 수 없는 쿼리 파라미터는 거부되지 않고 무시되므로, 필드를 추가해도 기존 호출자가 중단될 일이 없습니다.
자신 식별 (선택 사항, 그리고 정말 선택 사항)
키가 없으면 호출자를 식별할 방법이 없습니다. 권장되는 예의는 에이전트 이름, 에이전트가 실행되는 프레임워크, 이를 구동하는 모델을 명시하는 헤더를 사용하는 것입니다:
X-Agent: agent_name=<agent>; software=<langchain|llamaindex|n8n|claude-desktop|cursor|openai-assistants|crewai|custom>; model=<model>; version=<v>; purpose=<rag|monitoring|research|digest>; contact=<url or mailto>
User-Agent: <agent>/<version> (+<contact url>)같은 값은 일반적으로 더 쉬운 plain query 파라미터로도 사용할 수 있습니다:
https://freenewsapi.ai/v1/search?q=climate&agent_name=newsbot&software=langchain&model=gpt-4o알 수 없는 키는 무시되므로 불필요한 키를 보내도 항상 안전합니다. 어떤 값도 검증되지 않으며, 누락했다고 해서 스로틀링되지 않습니다. 단 하나의 확실한 지침은 이 필드에 최종 사용자 개인 데이터를 넣지 마세요입니다.
유료 뉴스 API에 맞서기
사이트의 비교 페이지는 11개 경쟁사를 개별적으로 다룹니다. 모든 경쟁사를 관통하는 구조적 차이점은 다음과 같습니다:
1일 100회 요청, 24시간 지연
무료 뉴스-API 티어의 표준적인 형태: 데모용으로 충분히 작은 토큰 버킷과 유료 고객을 위해 유보된 최신 기사.
- 키 필요
- 일일 한도
- 지연된 기사
- 비상업적 용도만 허용
한도 없음, 지연 없음, 키 없음
IP당 초당 20회 요청이 유일한 제한입니다. 최신 기사는 보통 2분 이내로 업데이트되며 상업적 사용이 허용됩니다.
- 키 없음, 회원가입 불필요
- 일일 또는 월간 한도 없음
- 연속 갱신
- 상업적 사용 허용
영어 우선, 미국 우선
대부분의 코퍼스는 영어권 출판사 목록을 기반으로 구축되고 나머지 지역의 데이터가 추가됩니다.
- 영어 중심
- 비라틴 문자권coverage 부족
인도 > 미국, 터키 > 독일
그리스어, 베트남어, 페르시아어, 우크라이나어, 불가리아어 등 6개 언어에서 6자리 수의 방대한 양을 포함하는 약 100개 언어.
- 100개국
- 약 100개 언어
- 11,668개 등록 소스
유료 서비스는 여전히 무료 서비스에서는 제공되지 않는 다음 기능들을 제공합니다: 감점 점수 및 개체 추출을 표준 필드로 제공, 수년치 아카이브, 그리고 SLA(서비스 수준 계약)가 뒷받침되는 계약. 이러한 기능들은 실제 가치가 있으며, 필요하시다면 구매하셔야 합니다.
레시피
실시간 국가 모니터링
curl "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=crawled&size=50"이 기사가 글로벌 이슈인가, 국내 이슈인가?
curl "https://freenewsapi.ai/v1/trends/keywords?size=30"
# read `countries` on each keyword: 1 country = domestic, 70 = world event오늘의 coverage로 모델을 저렴하게 기반화하기
# 1. count first
curl "https://freenewsapi.ai/v1/stats?q=semiconductor+export+controls&date=7d"
# 2. scan metadata
curl "https://freenewsapi.ai/v1/search?q=semiconductor+export+controls&date=7d&lang=en&size=20&sort=relevance"
# 3. fetch bodies for the three you picked
curl "https://freenewsapi.ai/v1/article?url=<exact-url>&full_text=true"coverage가 가격을 주도하는가?
curl "https://freenewsapi.ai/v1/btc/correlation?interval=hour&max_shift=12"저장된 검색어를 피드로 변환하기
https://freenewsapi.ai/v1/rss?q=central+bank+rate&lang=en&date=24h&sort=date&size=50시장에서 중요한 언론사를 찾아보세요
curl "https://freenewsapi.ai/v1/stats?country=BR&date=30d&top=50"
# the `hosts` block is a ranked publisher list for that slice짧은 버전
Free News API은 100개국, 약 100개 언어의 25,000개 이상 출판사에서 수집한 2,150만 건 이상의 뉴스 기사를 대상으로 한 전체 텍스트 검색 서비스입니다. 90일간의 롤링 윈도우를 기반으로 지속적으로 업데이트되며, API 키나 회원가입 없이 IP 기반 속도 제한만 적용됩니다. 검색 기능 외에도 115개국별 실시간 뉴스 군집화, 세계 사건과 국내 사건을 구분하는 키워드 분석, 커버리지량 대비 14개 시장 지표 시각화, 비트코인 감정 분석용 7개 엔드포인트, RSS/Atom/JSON 형식의 뉴스 배포, 그리고 서비스 자체에서 생성된 28개 도구를 제공하는 MCP 서버가 제공됩니다.
이 서비스는 자체 오류율을 문서화하고, 각 국가별 데이터가 어떻게 도출되었는지 공개하며, 데이터의 오류가 무엇인지에 대한 페이지도 게시합니다. 터키어나 그리스어, 힌디어 등 현재 세계가 무엇을 말하고 있는지 알아야 하는 에이전트라면 이러한 조합은 어떤 가격에도 쉽게 찾기 어렵지만, 이 서비스는 무료입니다.
검색은 모든 검색어에 대해 AND 논리를 사용합니다. 자연어 질문이 아닌 2~5개의 키워드를 사용하세요.
Free News API, 효율적인 쿼리 방법
시작하기: freenewsapi.ai · freenewsapi.ai/mcp에서 MCP · /llms-full.txt에서 전체 매뉴얼 파일 다운로드.