Hướng dẫn nhanh

Lấy khóa, sao chép dòng lệnh, chạy nó, đọc kết quả JSON.

0. Lấy khóa

Tạo tài khoản miễn phí, mở khóa API và tạo một khóa. Sau đó, lưu khóa này trong biến môi trường:

export FNA_KEY=fna_live_...

1. Tìm kiếm

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

Ba trường trong phản hồi này đáng chú ý ngay lập tức. total là số bài viết khớp, không phải số bài viết được trả về — con số này được giới hạn ở 10,000 để đảm bảo tốc độ, và total_is_lower_bound cho bạn biết khi nào bạn chạm ngưỡng giới hạn đó. country_source cho biết cách xác định quốc gia, điều này quan trọng vì khoảng một phần ba giá trị quốc gia trong bất kỳ bộ dữ liệu tin tức nào đều là suy luận chứ không phải sự thật. Và crawled_at là dấu thời gian trung thực: nhà xuất bản có thể đặt lại ngày đăng published_at, nhưng thời gian thu thập được hệ thống tự động gán.

2. Thu hẹp phạm vi tìm kiếm

Các bộ lọc kết hợp với nhau bằng AND giữa các tham số và OR trong cùng một tham số. Vì vậy country=DE,AT&lang=de được hiểu là "các bài viết bằng tiếng Đức từ Đức hoặc Áo". Điều này yêu cầu các bài viết bằng tiếng Ukraina từ Ukraina hôm nay, sắp xếp theo thứ tự mới nhất trước:

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

3. Lấy toàn bộ nội dung

Kết quả tìm kiếm mặc định không bao gồm nội dung bài viết để giữ kích thước phản hồi nhỏ. Hãy yêu cầu rõ ràng khi bạn đã chọn được các bài báo thực sự muốn:

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

4. Đếm thay vì liệt kê

Thường thì câu hỏi hữu ích không phải là "các bài viết là gì" mà là "có dữ liệu gì ở đây không, và nó nằm ở đâu". Việc đếm kết quả giúp tiết kiệm chi phí đáng kể — chỉ tốn khoảng 200 token so với vài nghìn token cho một trang kết quả — khiến đây là bước gọi đầu tiên phù hợp nhất cho một tác nhân AI quyết định xem việc tìm kiếm có đáng để thực hiện hay không:

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

Phản hồi cung cấp số lượng theo quốc gia, ngôn ngữ, tên miền, nhà xuất bản và ngày, được tính trên toàn bộ tập hợp phù hợp thay vì chỉ trang hiện tại.

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

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

Tiếp theo