依國家與分類取得新聞標題的 API 使用方法

Neper 依國家和新聞分類整理新聞，也提供 Neper News API，讓應用程式直接取得新聞標題、文章連結、圖片和摘要，不必自行逐一擷取新聞來源。

API 只有一個端點：/queryNews。可透過以下任一 API 市集呼叫。請求格式相同，只有主機網址和驗證標頭不同。

• RapidAPI
• JoJ API

Neper 使用指南會集中整理目前的 API 說明及日後新增的 Neper 文件。

在慣用的 API 市集訂閱後，使用該市集提供的金鑰呼叫 /queryNews。

1. 請求：國家與分類

GET 和 POST 都可以使用。

• country（必填）：en、ko、au、nz、it、ja、gb、fr、de 或 in
• section（選填）：省略時會取得該國家的所有分類

常用分類值包括：top、BUSINESS、ENTERTAINMENT、SPORTS、WORLD、HEALTH。

科技與科學分類依國家使用不同代碼：

• it、ko、ja、fr、de → SCITECH
• en、au、nz、gb、in → SCIENCE 或 TECHNOLOGY

TOP 會視為 top。GET 請求中的多個分類可寫成 BUSINESS,SPORTS。POST 則可傳送單一字串、逗號分隔字串或 JSON 陣列。

範例：

GET /queryNews?country=en
GET /queryNews?country=ko&section=top
GET /queryNews?country=ko&section=SCITECH

{ "country": "gb", "section": ["SPORTS", "BUSINESS"] }

新聞資料約每五分鐘更新一次。updatedAt 是以毫秒為單位的 Unix 時間戳記。

2. 回應格式

成功回應範例如下：

{
  "status": "success",
  "message": "Request successful",
  "data": {
    "country": "ko",
    "sections": ["top"],
    "count": 1,
    "items": [
      {
        "docId": "kotop",
        "code": "ko",
        "id": "top",
        "updatedAt": 1757116800000,
        "news": [
          {
            "title": { "_text": "Headline" },
            "link": { "_text": "https://news.google.com/rss" },
            "url": "https://example.com/article",
            "img": "https://example.com/image.jpg",
            "content": "Article body",
            "summary": "One-sentence summary",
            "section": "top"
          }
        ]
      }
    ]
  }
}

幾個容易忽略的細節：

• 省略 section 時，data.sections 會是空陣列，並回傳該國家的所有分類。
• title 和 link 可能是含有 _text 欄位的物件。顯示前請先讀取 _text。
• 文章也可能包含 description、faviconUrl 等欄位。
• AI summary 目前適用於 de、en、ko。其他國家會回傳空字串；即使是支援的國家，來源文章沒有可用內文時也可能沒有摘要。

3. RapidAPI

1. 前往 RapidAPI 頁面並訂閱方案。
2. 從控制台複製 RapidAPI 金鑰。
3. 呼叫 RapidAPI 主機。請只將金鑰放在標頭中，不要放進網址或 JSON 主體。

https://neper-news-api.p.rapidapi.com

X-RapidAPI-Key: <YOUR_KEY>
X-RapidAPI-Host: neper-news-api.p.rapidapi.com

curl -G 'https://neper-news-api.p.rapidapi.com/queryNews' \
  --data-urlencode 'country=ko' \
  --data-urlencode 'section=top' \
  -H 'X-RapidAPI-Key: <YOUR_KEY>' \
  -H 'X-RapidAPI-Host: neper-news-api.p.rapidapi.com'

import axios from 'axios'

const res = await axios.get('https://neper-news-api.p.rapidapi.com/queryNews', {
  params: { country: 'ko', section: 'top' },
  headers: {
    'X-RapidAPI-Key': '<YOUR_KEY>',
    'X-RapidAPI-Host': 'neper-news-api.p.rapidapi.com'
  }
})

console.log(res.data)

const res = await axios.post(
  'https://neper-news-api.p.rapidapi.com/queryNews',
  { country: 'en', section: ['top', 'BUSINESS'] },
  {
    headers: {
      'X-RapidAPI-Key': '<YOUR_KEY>',
      'X-RapidAPI-Host': 'neper-news-api.p.rapidapi.com'
    }
  }
)

4. JoJ API

1. 前往 JoJ API 頁面並訂閱方案。
2. 建立或複製 JoJ API 金鑰。
3. 呼叫此 API 的 JoJ 主機。閘道會驗證金鑰，並在轉送請求前移除金鑰。

https://neper-news-api.jojapi.net

建議使用的標頭：

X-JoJAPI-Key: <YOUR_KEY>

以下格式也可使用：

Authorization: Bearer <YOUR_KEY>
Authorization: <YOUR_KEY>

curl -G 'https://neper-news-api.jojapi.net/queryNews' \
  --data-urlencode 'country=ko' \
  --data-urlencode 'section=top' \
  -H 'X-JoJAPI-Key: <YOUR_KEY>'

import axios from 'axios'

const res = await axios.get('https://neper-news-api.jojapi.net/queryNews', {
  params: { country: 'ko', section: 'top' },
  headers: {
    'X-JoJAPI-Key': '<YOUR_KEY>'
  }
})

console.log(res.data)

const res = await axios.post(
  'https://neper-news-api.jojapi.net/queryNews',
  { country: 'en', section: ['top', 'BUSINESS'] },
  {
    headers: {
      'X-JoJAPI-Key': '<YOUR_KEY>'
    }
  }
)

JoJ API 的計費單位是 Request API 物件。每次成功呼叫計為一個單位；即使省略 section 並取得所有分類，也只計一次。每月精確額度和速率限制請查看 API 頁面的價格說明。HTTP 5xx 回應和閘道產生的錯誤不會扣除額度。

5. 錯誤代碼

狀態碼	常見原因
400	country 或 section 遺漏或無效。errorCode 為 INVALID_REQUEST，允許值會列在 message 中。
401	金鑰遺漏或無效，或訂閱尚未生效
402	JoJ API 計費問題：額度用完、方案不包含此物件，或錢包餘額不足
429	超過速率限制或使用額度
5xx	暫時性伺服器問題

由 JoJ API 閘道產生的回應會包含 X-Jojapi-Gateway-Response: true。

常見的 400 原因是混用科技分類代碼：ko 請用 SCITECH，不要用 SCIENCE；en 請用 SCIENCE 或 TECHNOLOGY，不要用 SCITECH。

6. 選擇 API 市集

/queryNews 在兩個市集上的行為相同。如果金鑰和付款已經在 RapidAPI，繼續使用 RapidAPI 即可。若想透過一組 JoJ 金鑰和錢包使用多個市集 API，則可選擇 JoJ API。

請將金鑰存放在原始碼管理範圍之外。如果 JoJ API 金鑰只需呼叫 Neper，請將金鑰權限限制在這個 API。

需要其他地區的新聞，或整合時遇到問題嗎？請聯絡 [email protected]。