文件

新聞分群-即時

Service: https://news.api.yating.tw/v2

此服務從新聞、社群內容中將文章進行分群,達成事件挖掘與摘要。你可以直接藉由 RESTful API 輸入查詢條件後,就可以到相關事件,並進行適當的排序。此功能讓你不用閱讀逐篇文章,而是更快地從事件的角度切入,讓你更快了解全貌。

一個事件會由多篇新聞所組成,並且你可以取得跟這事件相關的社群文章。


1 搜尋相關事件

一個事件由數篇文章組成,此事件中最早的文章是事件發生起點,最新的文章則終點。

Request

URL: /events
Method: GET

Header

Name Type Info
Authorization String Bearer {key}

Parameter

Name Type Info
*start String 給定 start, end 時間區間,如果一個事件中的起點與終點與此區段有重疊,就會回傳。
請輸入距離今90天內的日期 (時區為 UTC+0)
E.g.
2022-09-26T13:50:55Z
*end String 給定 start, end 時間區間,如果一個事件中的起點與終點與此區段有重疊,就會回傳。
請輸入距離今90天內的日期 (時區為 UTC+0)
E.g.
2022-09-26T13:50:55Z
category String Leave it empty or “all” when you need all categories. You can query single category at once by using: category=business
Here are all categories:
all,
world,
technology,
business,
sports,
entertainment,
health,
science,
others
collaberativeBehavior
query String
fields String If you need more information in response, you may pick the following fields.
title,
generativeShortSummary,
generativeLongSummary,
extractiveShortSummary,
extractiveLongSummary
sourceLanguage array Default en. Origin source language, default is en.
Available values
: en, zh-hant
sort String With Keywords search:
updatedAt
,
relevance
Without Keywords search:
,
updatedAt
, newsCount
, fbPosts, fbComments, fbLikes, fbShares
,
** updatedAt is the end of an event
limit int Use this parameter to specify a cursor search limit (number of results per page) for your API request.
Default limit value is 10, maximum allowed limit value is 50.
after String search next page by token (just use the value of positionKey in here)

Response
你會取得事件陣列,其中包含多個相關事件實體。關於 event 實體中包含哪些資訊,請看 5 Event 實體說明。

Name Type Info
total number
positionKey String
events object[] 關於 event 實體中包含哪些資訊,請看 5 Event 實體說明。
{
  "count":25,
  "positionKey":"290",
  "events":[
<event entity1>,
<event entity2>
  ]
}

2 取得單一事件詳細內容

This is to get detailed information for an event.

Request

URL: /events/{eventId}
Method: GET

Header

Name Type Info
Authorization String Bearer {key}

Parameter

Name Type Info
*eventId String
*fields String If you need more information in response, you may pick the following fields.
title,
generativeShortSummary,
generativeLongSummary,
extractiveShortSummary,
extractiveLongSummary

Response
你會得到一個 event 實體。此外,即時事件 event id 會變動,所以:

  • 有正確找到的回應是 200 跟 json response
  • event id 已改變,就會回傳 307
  • event id 不存在回傳 404

3 查詢事件的來源文章

來源包含新聞或社群媒體(e.g. ptt, facebook ...),回傳以 source 的 publish time 排序,越新的在前面

Request

URL: /events/{eventId}/sources
Method: GET

Header

Name Type Info
Authorization String Bearer {key}

Parameter

Name Type Info
type String Available values : news, social (default is all)
limit int The numbers of items to return (default is 15)
after String (just use the value of positionKey in here)

Response

Name Type Info
positionKey number
sources object[] {"
publishedOn
": "經濟日報","type": "news", "
publishedAt
": "2022-02-20T06:51:24", "title": "拜登將召開國安會議 重申俄隨時會進攻烏克蘭", "uri": "
https://money.udn.com/money/story/replace_by_spider/6111105
",
"commentCounts"
:
3
}
{
   "count":15,
   "totalResults":302,
   "positionKey":"2022-05-17T14:01:37",
   "sources":[
      {
         "id":"articleID",
         "publishedOn":"蘋果日報",
         "type":"news",
         "publishedAt":"2022-05-17T16:20:00Z",
         "title":"檢方:南加州槍擊案嫌犯周文偉將依謀殺罪起訴 可能面臨死刑",
         "uri":"https://tw.appledaily.com/international/20220518/T6THWU7SEVCKNN3PJ5P6Z65Z3E/",
         "commentCounts":3,
         "authorName":"author name"
      },
      {
         "id":"articleID",
         "publishedOn":"經濟日報",
         "type":"news",
         "publishedAt":"2022-05-17T16:11:15Z",
         "title":"南加州槍擊案嫌犯周文偉 台中一中畢業紀念照曝光",
         "uri":"https://money.udn.com/money/story/replace_by_spider/6320952",
         "commentCounts":3,
         "authorName":"author name"
      }
   ]
}
{
   "count":15,
   "totalResults":171,
   "positionKey":"2022-06-08T10:42:02",
   "sources":[
      {
         "id":"articleID",
         "publishedOn":"ptt",
         "type":"social",
         "publishedAt":"2022-06-08T15:41:01Z",
         "title":"[新聞] 籲中央明訂「火化政策」柯:會配合、不搗",
         "uri":"https://www.ptt.cc/bbs/HatePolitics/M.1654702864.A.59A.html",
         "commentCounts":3,
         "authorName":"author name"
      },
      {
         "id":"articleID",
         "publishedOn":"facebook",
         "type":"social",
         "publishedAt":"2022-06-08T14:49:55Z",
         "title":"北市府網軍案疑雲燒不停...",
         "uri":"fblinks",
         "commentCounts":3,
         "authorName":"author name"
      }
   ]
}

4 一次取得多個事件的資訊

Request

URL: /events/batch
Method: GET

Header

Name Type Info
Authorization String Bearer {key}

Parameter

Name Type Info
*id String 可以給多個事件 ID 一次查找,至多一次 10個事件。
例如:例如:/event/batch?id=1234&id=5678999&id=00079ce4c046'
fields string If you need more information in response, you may pick the following fields.
title,
generativeShortSummary,
generativeLongSummary,
extractiveShortSummary,
extractiveLongSummary

Response
關於 event 實體中包含哪些資訊,請看 5 Event 實體說明。

{
   "fail":[
      {
         "id":"id1",
         "reason":"......"
      },
      {
         "id":"id2",
         "reason":"......"
         "redirectTo":"id4"
      }
   ],
   "success":[
      <event entity1>,
<event entity2>
   ]
}

5 Event 實體說明

一個 event 實體包含以下資訊:

Name Type Info
eventId String
sourceLanguage String
title object
sourceTotal object The count of news related to this event.
imgUri String
hashtags String[]
categories String [] 0 Politics, 1 world, 2 technology, 3 business, 4 sports, 6 entertainment, 8 health, 9 science, 10000 others
updatedAt String datetime: string, event last update time
generativeShortSummary String Event summary
String Event summary
socialMediaPopularity object It’s trending indicators for frontend services to evaluate an event. These values will be updated every 4 hours within 24 hours for each event.
{
   "eventId":"0fabb849aaea",
   "sourceLanguage":"en",
   "title":{
      "en":"Russia says Britain's foreign minister yet to answer for supporting Kyiv",
      "source":"N-a3ea4a20e97eb920e6046b4e4e90be7f31e2d305",
      "zh_hant":"俄羅斯說,英國外交部長尚未回答支持基輔的問題"
   },
   "sourceTotal":{
      "news":387,
      "social":2043
   },
   "imgUri":"https://media.zenfs.com/en/reuters.com/fe7c87c76555927828264bc64c218814",
   "hashtags":[
      "Ukraine",
      "Russian",
      "Russia",
      "Ukrainian",
      "U. S."
   ],
   "categories":[
      "1",
      "3"
   ],
   "updatedAt":"2023-01-18T11:17:25Z",
   "generativeShortSummary":[
      {
         "en":"Russia's foreign ministry spokeswoman says British foreign minister James cleverly is yet to answer for his support of Ukraine. cleverly said on Monday that he was happy to be sanctioned by the Kremlin.",
         "zh_hant":"俄羅斯外交部發言人說,英國外交部長詹姆斯巧妙地沒有回答他對烏克蘭的支持。他在週一巧妙地說,他很高興受到克里姆林宮的制裁。"
      }
   ],
   "generativeLongSummary":[
      {
         "en":"Russia's foreign ministry spokeswoman says British foreign minister James cleverly is yet to answer for his support of Ukraine. cleverly said on Monday that he was happy to be sanctioned by the Kremlin.",
         "zh_hant":"俄羅斯外交部發言人說,英國外交部長詹姆斯巧妙地沒有回答他對烏克蘭的支持。他在週一巧妙地說,他很高興受到克里姆林宮的制裁。"
      },
      {
         "en":"\"This is for the support of the Kyiv regime and Neo-Nazism,\" Zakharova Said.",
         "zh_hant":"\"這是為了基輔政權和新納粹主義的支持,\"扎哈羅娃說。"
      },
      {
         "en":"Ukraine's first lady Olena Zelenska urged world leaders and corporate executives at the world economic forum's annual gathering in Davos to do more to help her Country.",
         "zh_hant":"烏克蘭第一夫人奧列娜·澤倫斯卡(OlenaZelenska)在達沃斯舉行的世界經濟論壇年度聚會上敦促世界領導人和企業高管做更多的事情來幫助她的國家。"
      }
   ],
   "extractiveShortSummary":[
      
   ],
   "extractiveLongSummary":[
      
   ],
   "socialMediaPopularity":{
      "fbComments":53276,
      "fbPosts":2043,
      "fbLikes":184408,
      "fbShares":10411
   }
}

6使用限制

60 requests per minutes per IP