sugra.blog

Blogfoundation

Sugra News

Curated global headlines, GDELT media analytics, and Wikipedia attention - three layers of the news cycle under one key.

Arman Obosyan - Founder and CEO of Sugra Systems
Founder & CEO

Arman Obosyan

Published
  • #news
  • #gdelt
  • #api
ShareXLinkedInFacebookTelegramRedditEmailCopy linkMarkdown
Sugra News - Sugra API blog

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):

{
  "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):

{
  "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

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.

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/gdelt/timeline?q=energy&mode=timelinevol&timespan=2weeks"
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/gdelt/timeline?q=energy&mode=timelinetone&timespan=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.

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

Integrate with one key across every product direction.

Get API keyDocsFamily