# Top News RSS

<figure><img src="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2Fn9qaRalCQkqWAkCIzqOC%2FDOC7.png?alt=media&#x26;token=858a617d-17ab-45e7-88da-40340b39ace2" alt=""><figcaption></figcaption></figure>

### 1. Overview

Top News RSS clusters the past 24 hours of important news at the story level and delivers a ranked Top 10 by structural importance. Out of hundreds of articles published across 20+ media outlets, AI selects the 10 most important stories and ranks them.

* **Story-level Top 10**: A ranking of stories (same event merged into one), not individual articles.
* **Important news only**: Only articles classified as Level 1–2 by the news analysis pipeline are used.
* **Updated every hour**: To keep the ranking current, a new edition is generated on the hour using the most recent 24-hour window.
* **16 languages**: Every ranking is delivered simultaneously in 16 languages.
* **AI Insight included**: Every item includes structured analysis across five sections: Key Point, Market Sentiment, Similar Past Cases, Ripple Effect, and Opportunities & Risks.

[News RSS](https://docs.ns3.ai/ns3-api/news-rss) delivers every individual article. Top News RSS delivers the 10 most important stories from the past 24 hours.

***

### 2. How the Ranking Is Generated

The ranking takes articles that the news analysis pipeline has determined to be important (Level 1–2) as input, then applies story clustering and structural importance sorting to produce the output.

<figure><img src="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2FniFM6SSDPxMNsjkRI6aZ%2Ftop.png?alt=media&#x26;token=f42aaf8d-2968-44c9-b41a-95c270aa1d7c" alt=""><figcaption></figcaption></figure>

**Input: Level 1–2 articles only**

Only articles classified as Level 1–2 by the news analysis pipeline are used. These are pre-verified important news.

**Story clustering**

Multiple reports about the same event are merged into a single story. Clustering is based on same actor + same action + same object. If five outlets cover the same event, the ranking delivers it as one consolidated story.

**Representative item selection**

For each story, the article that best reflects the latest material update is selected as the representative item. The title, description, link, and pubDate exposed in the RSS correspond to this representative item.

**Importance-based sorting**

Sorting uses structural importance (Impact × Actionability × Transmission) as the primary criterion, and coverage volume (how many outlets reported it) as the secondary criterion. When structural importance is equal, stories validated by more outlets rank higher. Repeated coverage from the same outlet is capped to prevent ranking distortion.

**Top 10 output**

The top 10 stories from the sorted list are selected and assigned rank 1–10. If fewer than 10 stories exist, only the available stories are returned.

> This ranking shares the same input pipeline and story clustering with [Daily Market Update RSS](https://docs.ns3.ai/ns3-api/daily-market-update-rss). The difference is the output format: Daily Market Update delivers a five-section narrative briefing, Top News RSS delivers a ranked Top 10 list.

***

### 3. How RSS Fields Map to UI

This section shows how each RSS field is rendered in the actual NS3 app.

<figure><img src="https://4099730103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fypf00vlh3dJz4PJ2Q67s%2Fuploads%2FZJPN1iHNCnHo4X7HPrLu%2Ftop%20news%202.png?alt=media&#x26;token=e4e405e7-7418-4030-890f-18024cf063f3" alt=""><figcaption></figcaption></figure>

| UI Element                           | RSS Field                       |
| ------------------------------------ | ------------------------------- |
| ① Update time ("Update an hour ago") | `lastBuildDate` (channel level) |
| ② Ranking badge (#1, #2, ... #10)    | `rank`                          |
| ③ Headline text                      | `title`                         |
| Tap/click destination                | `link` (AI Insight page)        |

In the app UI, the Top News ranking displays only rank and title. Description, images, and coin tags are not shown in the ranking list. When a user taps an individual item, the full analysis is available on the AI Insight detail page via `link`. This design is optimized for scannability and priority ordering.

The RSS feed also includes `description`, `media:content`, `mentionedCoins`, and `insight` fields, so platforms can render summaries, images, coin tags, and AI Insight alongside the ranking as needed.

Example feed: <https://ns3.ai>

***

### 4. Validate the Data Yourself

Verify ranking quality directly before integration.

**Validate the ranking**

Ask any AI model to search for recent crypto news first, then compare it against the Top News ranking.

```
https://api.ns3.ai/feed/news-ranking?lang=en
```

**Example prompt:**&#x20;

{% hint style="success" %}
Search for the most important crypto news from the past 24 hours. Then read the Top 10 ranking at the following URL and evaluate whether the ranking accurately reflects the most important events.\
<https://api.ns3.ai/feed/news-ranking?lang=en>
{% endhint %}

**Translation quality**

Provide a language-specific Top News RSS to any AI model and ask whether it reads naturally to local financial news readers.

```
https://api.ns3.ai/feed/news-ranking?lang=ko
```

Replace the language code to test any of the 16 supported languages: \
`en · zh-CN · zh-TW · ko · ja · ru · tr · de · es · fr · vi · th · id · hi · it · pt`

**Example prompt:**

{% hint style="success" %}
Read the Top 10 ranking at the following URLs, one in English and one in Korean. Compare the two and evaluate whether a Korean-speaking user would get the same level of information and the same ability to act on the news as an English-speaking user.\
<https://api.ns3.ai/feed/news-ranking?lang=en\\>
<https://api.ns3.ai/feed/news-ranking?lang=ko>
{% endhint %}

***

<details>

<summary>Technical specification for developers starts below</summary>

Section 5-11 is documentation for developers.

</details>

### 5. RSS URL & Languages

#### Base URL

```
https://api.ns3.ai/feed/news-ranking?lang=en
```

#### 16 Language URLs

<table><thead><tr><th width="169.88885498046875">Language</th><th width="99.6666259765625">Code</th><th>URL</th></tr></thead><tbody><tr><td>English</td><td>en</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=en</code></td></tr><tr><td>简体中文</td><td>zh-CN</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=zh-CN</code></td></tr><tr><td>繁體中文</td><td>zh-TW</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=zh-TW</code></td></tr><tr><td>한국어</td><td>ko</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=ko</code></td></tr><tr><td>日本語</td><td>ja</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=ja</code></td></tr><tr><td>Русский</td><td>ru</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=ru</code></td></tr><tr><td>Türkçe</td><td>tr</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=tr</code></td></tr><tr><td>Deutsch</td><td>de</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=de</code></td></tr><tr><td>Español</td><td>es</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=es</code></td></tr><tr><td>Français</td><td>fr</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=fr</code></td></tr><tr><td>Tiếng Việt</td><td>vi</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=vi</code></td></tr><tr><td>ไทย</td><td>th</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=th</code></td></tr><tr><td>Bahasa Indonesia</td><td>id</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=id</code></td></tr><tr><td>हिन्दी</td><td>hi</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=hi</code></td></tr><tr><td>Italiano</td><td>it</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=it</code></td></tr><tr><td>Português</td><td>pt</td><td><code>https://api.ns3.ai/feed/news-ranking?lang=pt</code></td></tr></tbody></table>

`lang` is a required parameter. This feed has no other filter parameters.

***

### 6. Item Field Specification

This feed returns the latest single set of the Top 10 ranking. Maximum 10 items.

#### 6.1 Standard RSS Fields

```xml
<item>
    <title><![CDATA[U.S. February Jobs Report Shows 92,000 Job Losses Against Forecast of Gains]]></title>
    <description><![CDATA[The U.S. February employment report showed a loss of 92,000 jobs instead of the previously expected gain of 50,000 jobs. The weaker data has fueled expectations that the Federal Reserve may cut interest rates to support the economy.]]></description>
    <link>https://ns3.ai/en/news/VvDysMBZIl</link>
    <guid isPermaLink="false">https://ns3.ai/en/news/VvDysMBZIl</guid>
    <pubDate>Sat, 07 Mar 2026 12:47:37 GMT</pubDate>
    <media:content medium="image" url="https://example.com/image.jpg">
    </media:content>
    <mentionedCoins>BTC</mentionedCoins>
    <rank>1</rank>
    <insight><![CDATA[## Key Point
The U.S. February employment report showed a loss of 92,000 jobs.

Why it matters: The weaker labor data may shift expectations for Federal Reserve rate cuts.

## Market Sentiment
Neutral, Macro-driven, Volatile

Reason: The report showed a loss of 92,000 jobs, which complicates the outlook for growth and Federal Reserve policy.

## Similar Past Cases
Analysis of comparable past events and outcomes.

## Ripple Effect
Transmission mechanism analysis.

## Opportunities & Risks
**Opportunities**: Conditional opportunity cues.

**Risks**: Conditional risk cues.]]></insight>
</item>
```

**`title`**

* Meaning: Headline of the representative item
* Type: `string` (CDATA-wrapped)
* Use: Headline text in the ranking list

**`description`**

* Meaning: Core summary of the representative item (1–4 sentences)
* Type: `string` (CDATA-wrapped)
* Use: Article preview snippet

**`link`**

* Meaning: NS3 AI Insight page URL for the representative item
* Type: `URL string`
* Use: Click destination for the AI Insight detail page

**`guid`**

* Meaning: Unique item identifier
* Type: `URL string`, `isPermaLink="false"`
* Note: Each item has a unique value. Standard RSS guid-based deduplication works.

**`pubDate`**

* Meaning: Original publish time of the representative item
* Type: RFC 822/1123 format
* Use: Article publish time display

**`media:content`**

* Meaning: Social preview image URL
* Type: `URL string`, `medium="image"`
* Note: **May be missing.** Some sources do not provide preview images.

#### 6.2 Top News Extended Fields

**`rank`**

* Meaning: Story importance ranking position
* Values: `1` – `10` (1 = most important)
* Type: `integer`
* Use: Ranking badge (#1, #2, ... #10), sort order

**`mentionedCoins`**

* Meaning: Token symbols related to the representative item
* Type: `string` (CSV format, e.g., `BTC,ETH,SOL`)
* Note: **May be missing.** If no token is explicitly mentioned, the value may be empty or the tag absent.
* Parsing: Split by `,` → trim each item → normalize to uppercase

#### 6.3 Channel-Level Fields

**`lastBuildDate`**

* Meaning: Time when the ranking was generated (channel level)
* Type: RFC 822/1123 format
* Use: "Update 3 minutes ago" display. Used to judge ranking freshness. Distinct from each item's `pubDate` (article publish time).

#### 6.4 AI Insight Field

**`insight`**

* Meaning: Full AI structured analysis
* Type: `string` (CDATA-wrapped, markdown format)
* Structure: Sections delimited by `##` headings. All items include all five sections (input is Level 1–2 only).

```xml
<insight><![CDATA[## Key Point
Fact-based core summary.

Why it matters: Why this event is significant.

## Market Sentiment
Cautiously Bullish, Regulatory-driven

Reason: Rationale for the directional label.

## Similar Past Cases
Analysis of comparable past events and outcomes.

## Ripple Effect
Transmission mechanism analysis.

## Opportunities & Risks
**Opportunities**: Conditional opportunity cues.

**Risks**: Conditional risk cues.]]></insight>
```

**Parsing guide**: Split on the `##` string to extract individual sections.

#### 6.5 Fields Not Included

`newsType` and `level` are absent from this feed. All items are representative items of Level 1–2 stories, so priority is expressed through `rank` rather than a separate level field.

***

### 7. Error Handling & Edge Cases

#### 7.1 Missing `media:content` (no image)

* Cause: The original source does not provide a social preview image.
* Product: Use a default image/logo or a no-image layout.
* Engineering: Treat missing `media:content@url` as null.

#### 7.2 Missing or empty `mentionedCoins`

* Cause: No token is explicitly mentioned in the representative item.
* Product: Hide the coin tag area.
* Engineering: Allow both missing tag and empty string.

#### 7.3 Fewer than 10 items

* Cause: Fewer than 10 Level 1–2 stories exist within the 24-hour window (weekends, holidays).
* Product: Display only the available items. A natural list rendering is preferable to a "N of 10" label.
* Engineering: `rank` is sequential starting from 1, so item count can be determined directly.

#### 7.4 `pubDate` vs `lastBuildDate`

* `pubDate`: Original publish time of the representative article (item level)
* `lastBuildDate`: Generation time of the ranking set (channel level)
* In UI, use `lastBuildDate` for "Update N minutes ago" and `pubDate` for individual article timestamps.

#### 7.5 **HTTP error handling**

<table><thead><tr><th width="150.33331298828125">Status</th><th>Meaning</th><th>Recommended action</th></tr></thead><tbody><tr><td>200</td><td>Success</td><td>Process feed normally</td></tr><tr><td>304</td><td>Not Modified</td><td>Use cached version (when conditional request headers are supported)</td></tr><tr><td>400</td><td>Bad Request (e.g., invalid <code>lang</code> code)</td><td>Check parameter values</td></tr><tr><td>500, 502, 503</td><td>Server error</td><td>Retry after 30–60 seconds. Do not retry immediately in a tight loop.</td></tr></tbody></table>

> If the server is unreachable or returns a non-200 response, continue serving the last successfully fetched ranking until the next successful poll.

***

### 8. Polling & Caching

**Generation cycle**: A new ranking is generated every hour on the hour.

**Recommended polling window**: Between minute 15 and minute 20 of each hour. Generation may be delayed when important news volume is high, so polling 15–20 minutes after the hour is more reliable than polling immediately.

```
Poll between minute 15–20 of each hour
(e.g., 01:15, 02:15, 03:15 ...)
```

**Feed scope**: Only the latest single ranking set is returned.

**Translation delay**: Translated rankings may arrive approximately 5–10 minutes after the English ranking is generated. When using non-English languages, adjust the polling window to minute 25–30.<br>

***

### 9. Timezone & Display

* `lastBuildDate` and `pubDate` are provided in GMT (RFC 822/1123).
* Convert to local time for UI display, but keep sorting and freshness checks anchored to UTC.
* Calculate "Update N minutes ago" based on `lastBuildDate`.

***

### 10. Implementation Checklist

* [x] Render ranking order using `rank` field (#1–#10)
* [x] Deduplicate using `guid` (each item has a unique value)
* [x] Display ranking freshness with `lastBuildDate` ("Update N minutes ago")
* [x] Distinguish `pubDate` (article time) from `lastBuildDate` (ranking generation time)
* [x] Handle missing `media:content` with thumbnail fallback
* [x] Parse `mentionedCoins` CSV (allow empty)
* [x] Parse `insight` markdown (split sections on `##` )
* [x] Handle fewer than 10 items
* [x] Set polling window to minute 15–20 of each hour
* [x] Adjust to minute 25–30 when using translated rankings
* [x] Support 16 languages via `lang` parameter

***

### 11. FAQ

**Q: How is this different from News RSS?**

[News RSS](https://docs.ns3.ai/ns3-api/news-rss) delivers every individual article in real time. Top News RSS clusters the past 24 hours of important articles (Level 1–2) at the story level and delivers the Top 10 by importance. Multiple reports about the same event are merged into one story, so readers can immediately see the 10 most important events without duplication.

**Q: What is the relationship with** [**Daily Market Update RSS**](https://docs.ns3.ai/ns3-api/daily-market-update-rss)**?**

They share the same input pipeline (Level 1–2 articles) and story clustering. The difference is the output format: Top News RSS delivers a ranked Top 10 list, Daily Market Update delivers a five-section narrative briefing.

**Q: Why "Top 10 stories" instead of "Top 10 articles"?**

If five outlets cover the same event, five articles exist. Ranking by article would fill the top positions with the same event. Clustering at the story level removes this duplication, ensuring the Top 10 shows 10 genuinely distinct events.

**Q: Can two items have the same rank?**

No. Rank is assigned sequentially starting from 1. Even in cases of tied scores, deterministic tiebreak rules ensure every story receives a unique rank.

**Q: Can fewer than 10 items be returned?**

Yes. If fewer than 10 Level 1–2 stories exist within the 24-hour window, only the available stories are returned. This is more likely on weekends and holidays when news volume is lower.

**Q: What is the difference between pubDate and lastBuildDate?**

`pubDate` is the original publish time of each representative article. `lastBuildDate` is the time the entire ranking set was generated. In UI, use `lastBuildDate` for "Update N minutes ago" and `pubDate` for individual article timestamps.

**Q: Can translations be delayed?**

Translated rankings may arrive approximately 5–10 minutes after the English ranking is generated. When using non-English languages, poll at minute 25–30 of each hour.