Início rápido

Obtenha uma chave, copie a linha, execute-a e leia o JSON.

0. Obter uma chave

Crie uma conta gratuita, abra chaves de API e crie uma. Em seguida, mantenha-a em uma variável de ambiente:

export FNA_KEY=fna_live_...

1. Pesquisar

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"
    }
  ]
}

Três campos na resposta merecem atenção imediata. total indica quantos artigos corresponderam à busca, e não quantos foram retornados — o valor é limitado a 10,000 para garantir velocidade, e total_is_lower_bound informa quando você atingiu esse limite. country_source indica como o país foi determinado, o que é relevante porque cerca de um terço dos valores de país em qualquer conjunto de dados de notícias são inferências, não fatos. E crawled_at é o carimbo de data/hora preciso: os editores podem retroceder a data de published_at, mas o horário de rastreamento é atribuído pelo pipeline.

2. Refinar a busca

Os filtros combinam-se com AND entre parâmetros e OR dentro de um mesmo parâmetro. Portanto, country=DE,AT&lang=de lê-se como "artigos em língua alemã da Alemanha ou da Áustria". Esta solicitação pede artigos em ucraniano de hoje, da Ucrânia, ordenados do mais recente para o mais antigo:

curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"

3. Obter o texto completo

Os resultados da pesquisa omitem o corpo do artigo por padrão para manter as respostas leves. Solicite-o explicitamente quando você já tiver selecionado os artigos que realmente deseja:

curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=inflation&full_text=true&size=5"

4. Contar em vez de listar

Muitas vezes, a pergunta útil não é "quais são os artigos", mas "há algo aqui e onde está". Contar respostas custa uma fração do preço — cerca de 200 tokens contra vários milhares para uma página de resultados — o que a torna a primeira chamada ideal para um agente decidir se vale a pena executar uma busca:

curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"

A resposta fornece contagens por país, idioma, zona de domínio, editor e dia, calculadas sobre todo o conjunto correspondente, e não apenas sobre a página atual.

Em 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"])

Em 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));

Próximo