--- title: "Sugra News" description: "Curated global headlines, GDELT media analytics, and Wikipedia attention - three layers of the news cycle under one key." slug: sugra-news status: published published_at: 2026-06-16 author: Arman Obosyan author_url: https://sugra.systems/about section: foundation series_order: 5 primary_keyword: sugra news api gdelt hero_image: /blog/images/posts/sugra-news-hero.jpg hero_alt: "Sugra News - Sugra API blog" og_image: /blog/images/posts/sugra-news-hero.jpg tags: - news - gdelt - api --- # Sugra News: headlines, global media analytics, and public attention **Series:** Sugra product directions (5 of 7) **Audience:** developers integrating the Sugra API over HTTP **Live samples verified:** 2026-07-24 against `https://sugra.ai` **Auth:** `x-api-key` header on every data call Standalone article. Sugra News is the news and events direction - three layers of the news cycle under one key. --- ## Essence > Global news and event signal - curated feeds on a short cadence, plus the world's events, plus reader attention. Three layers (do not collapse them in product design): | Layer | Base path | What it measures | |---|---|---| | Curated headlines | `/api/v1/news/*` | What selected feeds just published | | GDELT media / events | `/api/v1/gdelt/*` | What global media is covering, volume, tone, themes | | Wikipedia attention | `/api/v1/news/wikipedia/*` | What readers are looking up (demand-side attention) | Live catalog: **`GET /api/v1/news/sources` returned count 42 feeds** (2026-07-24). Prefer this live count over marketing badges that may say 43. --- ## What this direction is not | Not this | Why | |---|---| | Full-text news archive / clipping suite | Headlines and analytics, not a media library | | Enterprise media monitoring UI | API data, you build the UI | | Investment advice | Even ticker-adjacent sentiment is a signal only | | Official macro prints | **Sugra Macro** | | Market quotes | **Sugra Finance** | Copy rule: commercial RSS outlets ship under the **Sugra News** brand on public surfaces; GDELT and Wikipedia are named openly (GDELT is a vetted named exception). --- ## Capability map | Module | Endpoints (approx.) | Coverage | |---|---|---| | Curated feeds | ~7 | latest, region, category, feed slug, search, sources, stats | | GDELT | ~11 | articles, timeline volume/tone, sentiment, context, TV, trending themes/events/entities, by-country | | Wikipedia | ~8 | pageviews series, top charts, by country, devices, editors, cross-language | Adjacent: some equity news-sentiment surfaces live under equities categories - still a screening signal, not advice. --- ## Why the response shape is useful ### 1. Curated items ready for boards Live business latest (truncated fields): ```json { "data": { "count": 3, "items": [ { "title": "Why there are still more Trump tariffs expected - even after this past week's rollouts", "published": "2026-07-24T17:41:00Z", "source": "marketwatch", "region": "us", "category": "business", "link": "https://..." } ] }, "meta": { "source": "news_rss", "data_time": "2026-07-24T17:41:00Z" } } ``` Note: source text in items may include outlet names in `source_name` for filtering; public product copy should still lead with Sugra News branding for commercial feed classes. ### 2. Theme radar with freshness flags Live GDELT themes (6h window): ```json { "data": { "themes": [ { "theme": "TAX_FNCACT", "count": 29348, "share": 0.031 }, { "theme": "EPU_POLICY", "count": 13111, "share": 0.0138 } ], "total": 946899, "stale": false, "partial": false }, "meta": { "source": "gdelt_live" } } ``` Agents should refuse to treat aggregates as fresh when `stale` or `partial` is true. ### 3. Supply vs demand GDELT volume = media supply. Wikipedia pageviews = public attention demand. They answer different questions. ### 4. Explicit flaky upstream behavior `/gdelt/timeline` and sometimes `/gdelt/articles` can return **503** under upstream load. Portal recipe documents retry with backoff and last-good cache. Live run: themes OK, articles OK on retry, timeline **503**. --- ## Developer path ```bash export SUGRA_API_KEY="YOUR_API_KEY" curl -H "x-api-key: $SUGRA_API_KEY" \ "https://sugra.ai/api/v1/news/latest?category=business&limit=10" curl -H "x-api-key: $SUGRA_API_KEY" \ "https://sugra.ai/api/v1/gdelt/themes/trending?period=6h&limit=10" curl -H "x-api-key: $SUGRA_API_KEY" \ "https://sugra.ai/api/v1/news/sources" ``` --- ## Use case 1: Headline board **Goal.** Desk view of what just published by region or category. **Call.** `GET /api/v1/news/latest?region=&category=&limit=` **Regions include:** us, europe, asia, mideast, china, india, latam, africa, oceania, russia, global. **Categories include:** news, defense, business, tech, science, energy, disasters. **Strength.** Short-cadence curated digest. **Pitfalls.** Not full web; curated set only. --- ## Use case 2: Theme radar **Goal.** What themes dominate global media now. **Call.** `GET /api/v1/gdelt/themes/trending?period=1h|6h|24h&limit=` **Strength.** Share-ranked themes + stale/partial. **Pitfalls.** Theme codes are GKG codes - map to human labels in UI. --- ## Use case 3: Topic volume and tone tracker **Goal.** Is coverage of "energy" spiking, and is tone shifting? **Calls.** ```bash curl -H "x-api-key: $SUGRA_API_KEY" \ "https://sugra.ai/api/v1/gdelt/timeline?q=energy&mode=timelinevol×pan=2weeks" curl -H "x-api-key: $SUGRA_API_KEY" \ "https://sugra.ai/api/v1/gdelt/timeline?q=energy&mode=timelinetone×pan=2weeks" ``` **Strength.** Story-breaking detection against baseline. **Pitfalls.** 503 possible - retry, cache last good JSON (see portal `news-signal-dashboard`). --- ## Use case 4: Article drill-down **Goal.** Evidence behind a theme spike. **Call.** `GET /api/v1/gdelt/articles?q=...&max_records=` (+ optional `/gdelt/context`). **Strength.** Titles, domains, languages, timestamps. **Pitfalls.** Query language; handle empty and 503. --- ## Use case 5: Regional pulse **Goal.** Europe / Asia / Mideast desk slices. **Calls.** `/news/region/{region}` or `latest?region=`. **Strength.** Regional filter without N scrapers. **Pitfalls.** Region taxonomy is Sugra's feed map, not UN regions. --- ## Use case 6: Keyword watch on curated layer **Goal.** Track a product, company, or event string in curated feeds. **Call.** `GET /api/v1/news/search?q=inflation&limit=` **Strength.** Same item shape as latest; different from GDELT breadth. **Pitfalls.** Curated search is not global media completeness. --- ## Use case 7: Public attention proxy **Goal.** What people read on Wikipedia about a topic or day. **Calls.** `/news/wikipedia/pageviews/top`, per-article series, by-country tops. **Strength.** Demand-side complement to media supply. **Pitfalls.** Top charts include noise pages (Main_Page, Special:Search) - filter. --- ## Use case 8: Events and entities trending **Goal.** Structured event/entity rise signals. **Calls.** `/gdelt/events/trending`, `/gdelt/entities/trending`, `/gdelt/events/by-country/{country}`. **Strength.** Beyond headlines into event aggregates. **Pitfalls.** Definitions are GDELT's; document them. --- ## Use case 9: Feed catalog integrity **Goal.** Drive UI filters from live catalog. **Call.** `GET /api/v1/news/sources` -> `count`, `regions`, `categories`, `sources[]` with slug/name/region/category. **Live:** 42 sources, 11 regions, 7 categories. --- ## Antipatterns 1. Treating GDELT theme codes as English UI strings without mapping 2. Ignoring `stale` / `partial` 3. No retry policy on GDELT 503 4. Confusing curated News with full web search 5. Naming commercial outlet brands as the product story on public marketing --- ## Scenarios where News alone is enough - Agent current-events context windows - Editorial / research theme monitors - Regional headline boards - Attention research via Wikipedia - Crisis media volume trackers --- ## Live verification (2026-07-24) | Call | Result | |---|---| | news/latest business | 200 | | news/sources (42 feeds) | 200 | | news/search inflation | 200 | | gdelt/themes/trending | 200, stale=false | | gdelt/articles | 200 on retry | | gdelt/timeline | 503 (upstream) | | wikipedia pageviews top | 200 | --- ## Where to go next - Portal: Sugra News direction + sources - Recipe: `news-signal-dashboard` - Cookbook: `03_news_global_flow.py` - Series: NetAtlas (previous), Earth (next) | # | Direction | Status | |---|---|---| | 1-4 | Finance ... NetAtlas | Published | | 5 | **News** | This article | | 6 | Earth | Next | | 7 | Research | Upcoming | ---