TrendNews API

Quick start

Base URL: https://trendnews.uk.app/api/v1. Sign up, create an API key in your account and send your first request:

curl -H "X-API-Key: YOUR_KEY" "https://trendnews.uk.app/api/v1/posts?country=UA&limit=5"

Countries are given as ISO-2 codes (UA, US, DE, PL…). The full list with feed languages is returned by /api/v1/countries. New posts appear every hour.

Authentication

Every request except /v1/health, must include the API key in a header:

X-API-Key: tn_live_…

Also accepted: Authorization: Bearer tn_live_…. Passing the key in URL parameters is not allowed: it would end up in logs and browser history.

Plans and limits

Limits depend on the account's plan. The daily quota is shared by all keys of the account and resets at 00:00 UTC. The per-minute limit applies to each key separately. All plans and prices

The current state is returned in the headers of every response:

Responses may be cached for up to 60 seconds (Cache-Control: private, max-age=60): data is updated once an hour. Caching also saves your quota.

Response format and errors

A successful response always has the data; lists also have meta with pagination. An error has the error field with a machine-readable code and a message.

// success{ "data": [ … ], "meta": { "total": 856, "limit": 20, "offset": 0, "has_more": true } }

// error{
  "error": {
    "code": "invalid_country",
    "message": "Unknown country code. The list of supported ISO-2 codes: /api/v1/countries"
  }
}

Pagination

Lists return at most limit records (up to 100). To get the next page, increase offset by limit, as long as meta.has_more is true.

Endpoints

{
  "data": {
    "status": "ok",
    "last_post_at": "2026-10-24T14:05:09Z",
    "countries": 6,
    "time": "2026-10-24T14:31:38Z"
  }
}

{
  "data": [
    { "code": "UA", "name": "Україна", "flag": "🇺🇦", "lang": "uk", "post_count": 856, "last_post_date": "2026-10-24" },
    { "code": "SI", "name": "Словенія", "flag": "🇸🇮", "lang": "sl", "post_count": 150, "last_post_date": "2026-10-24" },
    { "code": "GB", "name": "Велика Британія", "flag": "🇬🇧", "lang": "en", "post_count": 284, "last_post_date": "2026-10-24" }
  ]
}

{
  "data": [
    { "slug": "politics", "label": "Politics", "posts": 61 },
    { "slug": "sport", "label": "Sport", "posts": 54 },
    { "slug": "other", "label": "Other", "posts": 48 }
  ],
  "meta": { "country": "GB" }
}

{
  "data": [
    {
      "id": 24239,
      "country": "SI",
      "lang": "sl",
      "category": { "slug": "other", "label": "Drugo" },
      "trend": "češka korak bližje ukinitvi prispevka",
      "date": "2026-10-24",
      "title": "Tema dneva: Češka korak bližje ukinitvi prispevka",
      "digest": "»češka korak bližje ukinitvi prispevka« se danes pojavlja v več medijih (2). …",
      "source_count": 2,
      "published_at": "2026-10-24T14:05:09Z",
      "url": "https://trendnews.uk.app/post.php?id=24239"
    }
  ],
  "meta": { "total": 150, "limit": 1, "offset": 0, "has_more": true }
}

{
  "data": {
    "id": 24242,
    "country": "GB",
    "lang": "en",
    "category": { "slug": "sport", "label": "Sport" },
    "trend": "aston villa man city",
    "date": "2026-10-24",
    "title": "Story of the day: Aston villa man city",
    "digest": "One of the day's top stories is “aston villa man city”, reported by 3 sources. …",
    "source_count": 3,
    "published_at": "2026-10-24T14:05:10Z",
    "url": "https://trendnews.uk.app/post.php?id=24242",
    "sources": [
      { "title": "…", "url": "https://www.standard.co.uk/…", "host": "www.standard.co.uk", "sitename": "Evening Standard" }
    ]
  }
}

{
  "data": [
    {
      "country": "SK",
      "lang": "sk",
      "date": "2026-10-24",
      "trends": [
        { "rank": 1, "term": "bayernu mníchov vincent kompany", "score": 24, "mentions": 2,
          "example_headline": "Ako dlho bude Bayernu Mníchov chýbať hlavný tréner? …" }
      ]
    }
  ]
}

{
  "data": [
    {
      "id": "ev_k3v9q2m7x1a4d",
      "title": "Satna: Two killed as truck rams bike near Maihar",
      "country": "IN",
      "lang": "en",
      "category": { "slug": "society", "confidence": 0.67 },
      "first_seen": "2026-10-25T09:12:40Z",
      "original_published_at": "2026-10-25T08:41:00Z",
      "last_updated": "2026-10-25T13:05:12Z",
      "articles": 7,
      "sources_total": 6,
      "independent_sources": 4,
      "geo": {
        "source_country": "IN",
        "event": { "country": "IN", "region": "Madhya Pradesh", "region_code": "IN.35", "city": "Satna",
                   "city_geonames_id": 1257806, "lat": 24.6, "lon": 80.83, "confidence": 0.86 }
      },
      "trend": { "mentions_1h": 1, "mentions_6h": 5, "mentions_24h": 7, "independent_sources_24h": 4, "velocity": 2.5, "score": 18.6 },
      "evidence": { "available": true, "version": 2, "computed_at": "2026-10-25T13:20:03Z", "url": "https://trendnews.uk.app/api/v1/events/ev_k3v9q2m7x1a4d/evidence" }
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "has_more": false, "sort": "trend",
            "trend_formula": "score = independent_sources_24h × log2(1 + mentions_6h) × (1 + min(velocity, 3) / 3); …" }
}

{
  "data": {
    "id": "ev_k3v9q2m7x1a4d",
    "title": "Satna: Two killed as truck rams bike near Maihar",
    "independent_sources": 4,
    "…": "усі поля з /v1/events",
    "sources": [
      { "url": "https://…", "publisher": "Dainik Bhaskar", "title": "…", "lang": "hi",
        "published_at": "2026-10-25T08:41:00Z", "published_at_quality": "page_metadata",
        "first_seen": "2026-10-25T09:12:40Z", "agency": null, "independence_group": 1 },
      { "url": "https://…", "publisher": "…", "agency": "PTI", "independence_group": 2 },
      { "url": "https://…", "publisher": "…", "agency": "PTI", "independence_group": 2 }
    ]
  }
}

{
  "data": {
    "event_id": "ev_k3v9q2m7x1a4d",
    "version": 2,
    "computed_at": "2026-10-25T13:20:03Z",
    "independent_sources": 4,
    "sources_read": 6,
    "full_text_read": 5,
    "layer": "refined",
    "summary": "A speeding truck hit a motorcycle near Maihar in Satna district on Saturday morning, killing two people; police say the driver fled.",
    "facts": [
      { "claim": "Two people were killed when a speeding truck hit a motorcycle near Maihar in Satna district on Saturday morning.",
        "kind": "number", "status": "confirmed", "independent_sources": 3,
        "sources": [ { "url": "https://…", "publisher": "…", "published_at": "2026-10-25T08:41:00Z", "snippet": "…" } ] },
      { "claim": "Police said the truck driver fled the spot.", "kind": "statement", "status": "single_source", "independent_sources": 1, "sources": [ … ] }
    ],
    "quotes": [ { "text": "The driver fled after the accident, a search is under way", "speaker": "SP Ashutosh Gupta", "source": { "url": "https://…", "publisher": "…" } } ],
    "contradictions": [ { "topic": "Three people were injured…", "versions": [ { "claim": "Three people were injured…", "source": "https://…" }, { "claim": "Four people were injured…", "source": "https://…" } ] } ],
    "unknowns": [ { "statement": "The cause of the accident is not yet known.", "source": "https://…" } ],
    "what_changed": { "since_version": 1, "since": "2026-10-25T10:02:11Z",
                      "items": [ { "type": "new_fact", "claim": "Police said the truck driver fled the spot.", "status": "single_source" } ] },
    "suggested_length_words": 250,
    "method": "extractive + LLM: … confirmed = cited in >= 2 independent sources (computed, not by the model)",
    "llm": { "model": "claude-haiku-5-5", "input_tokens": 6050, "output_tokens": 1800 },
    "stale": false
  }
}

Ereignisse und Belege: so funktioniert es

Die Ereignisschicht fasst Artikel aus allen Feeds zu Ereignissen zusammen: Eine Meldung, die Dutzende Medien übernehmen, ist ein Ereignis mit einer event_id. Unten steht, wie jedes Feld berechnet wird, damit Sie die Daten Ihren Lesern erklären können.

Ereignis und event_id

Artikel werden nach Bedeutung gruppiert (mehrsprachige multilingual-e5-Embeddings), in einem 72-Stunden-Fenster innerhalb des Feed-Landes. Zusätzlich werden gemeinsame Schlüsselwörter und die Geografie geprüft, damit verschiedene Ereignisse zu einem ähnlichen Thema nicht verschmelzen. Die event_id (Format ev_ + 13 Zeichen) bleibt gleich, solange das Ereignis aktualisiert wird: Neue Artikel kommen zum bestehenden Ereignis hinzu, statt ein neues anzulegen.

Unabhängigkeit der Quellen

Artikel teilen sich eine independence_group, wenn sie von derselben Website stammen, dieselbe Agentur nennen (Reuters, AP, AFP, PTI, ANI, Ukrinform u. a.) oder nahezu identische Kopien sind. sources_total zählt alle Medien, independent_sources die unabhängigen Gruppen. Eine Agenturmeldung, die zwanzig Websites übernehmen, zählt als eine Quelle. Standardmäßig liefert /v1/events Ereignisse mit mindestens 2 unabhängigen Quellen (Parameter min_independent).

Veröffentlichungsdatum

original_published_at ist das früheste verlässliche Veröffentlichungsdatum unter den Quellen, first_seen der Zeitpunkt, zu dem wir das Ereignis zuerst gesehen haben. Für jeden Artikel zeigt published_at_quality die Herkunft des Datums: feed — aus dem Feed; feed_timezone_corrected — der Feed lieferte Ortszeit als UTC, wir haben sie mit der Zeitzone des Landes korrigiert; page_metadata — aus den Metadaten der Seite; unknown_used_first_seen — kein Datum, verwendet wird der Zeitpunkt der ersten Erfassung.

Geografie

geo.source_country ist das Land des Feeds, in dem der Artikel erschien. geo.event gibt an, wo das Ereignis stattfand: Land, Region mit GeoNames-Code (region_code, z. B. IN.35 — Madhya Pradesh), Stadt mit city_geonames_id und Koordinaten. Orte werden in Titeln und Beschreibungen anhand des GeoNames-Verzeichnisses erkannt (Städte ab 15 000 Einwohnern und Regionen, auch lokale Formen). Filter von /v1/events: region (Code oder Name) und city (Name oder GeoNames-ID). Ist der Ort nicht sicher bestimmt, ist geo.event null.

Sprache und Kategorie

Die Sprache jedes Artikels wird anhand des Textes erkannt (fastText) und ersetzt die Feed-Sprache, wenn die Sicherheit mindestens 0,8 beträgt. Die Sprache des Ereignisses ist die Sprache der Mehrheit seiner Artikel. Die Kategorie ergibt sich aus einer Abstimmung der Artikel, category.confidence ist der Stimmenanteil.

Trend-Kennzahlen

Das Feld trend ist transparent: mentions_1h, mentions_6h, mentions_24h sind neue Artikel in 1, 6 und 24 Stunden, independent_sources_24h unabhängige Gruppen pro Tag, velocity das Tempo der letzten 6 Stunden im Vergleich zu den 18 davor. Die Formel für score steht auch in meta.trend_formula:

score = independent_sources_24h × log2(1 + mentions_6h) × (1 + min(velocity, 3) / 3)
velocity = (mentions_6h / 6) / ((mentions_24h − mentions_6h) / 18)

Belege: zwei Schichten

/v1/events/{id}/evidence liest die Volltexte von bis zu 10 Quellen (unabhängige zuerst, unter Beachtung von robots.txt) und liefert Fakten mit Links, Zitate, Widersprüche, offene Punkte, what_changed und suggested_length_words. Letzteres ist eine empfohlene Textlänge: Sie hängt von der Zahl bestätigter Fakten ab, damit der Text nicht mit Füllmaterial gestreckt wird.

Extraktive Schicht (alle Tarife): Ein Fakt ist ein wörtlicher Satz aus einer Quelle, Sätze mit gleicher Bedeutung werden gruppiert. confirmed heißt, die Aussage steht in mindestens zwei unabhängigen Quellen, single_source in einer, disputed bedeutet, dass die Quellen unterschiedliche Zahlen nennen.

Verfeinerte Schicht (Business-Tarif): Claude formuliert die Quellensätze zu atomaren Fakten um und ergänzt eine kurze neutrale summary. Das Modell kann nichts Eigenes hinzufügen: Jeder Fakt muss Quellensätze zitieren, ein Fakt ohne Zitat wird verworfen, snippet ist ein wörtliches Zitat, und den Status confirmed berechnet das System aus der Unabhängigkeit der zitierten Quellen, nicht das Modell. Ein Widerspruch wird nur gemeldet, wenn Quellen sich gegenseitig ausschließende Werte für denselben Fakt nennen.

Der Parameter layer: auto (Standard: verfeinerte Schicht für Business, extraktive für andere Tarife), refined (nur Business, sonst 403 plan_required), extractive. Das Feld layer in der Antwort zeigt, welche Schicht geliefert wurde. Die erste Anfrage eines Business-Kunden stellt die Verfeinerung in die Warteschlange: Solange sie vorbereitet wird (meist unter 30 s), kommt die extraktive Schicht mit refined_status: processing und dem Header Retry-After. Im Pro-Tarif können Sie die verfeinerte Schicht testen: layer=refined für 20 verschiedene Ereignisse pro Monat (Rest im Header X-Refined-Trial-Remaining). Für andere Tarife enthält die Antwort refined_layer mit einem Link zu den Tarifen. Das Feld llm nennt Modell und Tokenzahl.

„Bestätigt“ bedeutet, dass mindestens zwei unabhängige Quellen es gemeldet haben, nicht dass die Aussage wahr ist. Prüfen Sie bei sensiblen Themen die Originalquellen über die Links in sources.

Aktualisierung und Aufbewahrung

Ereignisse werden stündlich zusammen mit der Nachrichtenerfassung neu berechnet. Belege werden automatisch aktualisiert für Ereignisse mit 3 oder mehr unabhängigen Quellen und für Ereignisse, deren Verfeinerung ein Business-Kunde in den letzten 24 Stunden angefordert hat. stale: true bedeutet, dass nach der letzten Berechnung neue Artikel eingegangen sind und die Aktualisierung bereits ansteht. Artikel, Ereignisse und Belege werden 3 Tage nach ihrer letzten Aktualisierung aufbewahrt, Beiträge und Trends länger.

Webhooks (Business)

Statt die API abzufragen, erhalten Sie einen POST mit JSON an Ihre https-Adresse. Einrichtung im Kundenbereich, Reiter „Webhooks“: Adresse, Länder, Mindestzahl unabhängiger Quellen und Ereignistypen. event.created kommt einmal, wenn ein Ereignis Ihre Zahl unabhängiger Quellen erreicht; evidence.updated, wenn sich seine Belege ändern (mit what_changed; für Business die verfeinerte Schicht, falls vorhanden).

Jede Anfrage ist signiert: Header X-TrendNews-Signature: t=<Unix-Zeit>,v1=<hex>, wobei v1 = HMAC-SHA256 von <t>.<roher Body> mit Ihrem Secret ist. Prüfen Sie die Signatur und verwerfen Sie Anfragen, die älter als 5 Minuten sind. Antworten Sie innerhalb von 8 Sekunden mit 2xx, sonst wiederholen wir nach 1, 5, 30, 120 und 360 Minuten. X-TrendNews-Delivery ist eine eindeutige Zustell-ID gegen Duplikate.

Beispiel für einen event.created-Body:

{
  "type": "event.created",
  "created_at": "2026-10-25T18:04:11Z",
  "data": {
    "id": "ev_aacw4p3jhkye6", "title": "Storm Boelo brings 80mph gusts and travel disruption to Scotland",
    "country": "GB", "lang": "en", "category": "society",
    "first_seen": "2026-10-23T18:16:53Z", "original_published_at": "2026-10-23T18:16:53Z",
    "independent_sources": 17, "sources_total": 22,
    "geo": { "country": "GB", "region": "Scotland", "region_code": "GB.SCT", "city": null },
    "api_url": "https://trendnews.uk.app/api/v1/events/ev_aacw4p3jhkye6",
    "evidence_url": "https://trendnews.uk.app/api/v1/events/ev_aacw4p3jhkye6/evidence",
    "page_url": "https://trendnews.uk.app/event.php?id=ev_aacw4p3jhkye6"
  }
}

Signaturprüfung (PHP):

$body = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([0-9a-f]{64})/', $_SERVER['HTTP_X_TRENDNEWS_SIGNATURE'] ?? '', $m);
$ok = $m && abs(time() - (int)$m[1]) < 300
   && hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, getenv('TRENDNEWS_WEBHOOK_SECRET')), $m[2]);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($body, true);   // handle $event['type'] … then
http_response_code(204);

Gespeicherte Suchen

Eine gespeicherte Suche ist eine Anfrage, die wir stündlich auf neue Nachrichten anwenden. Treffer werden 30 Tage gespeichert und sind in Ihrem privaten RSS (rss_url), über die API und – im Business-Tarif – per Webhook vom Typ watch.match verfügbar. Limits: Free – 1 Suche, Pro – 10, Business – 100. Anlegen im Konto oder über die API.

Syntax: durch Leerzeichen getrennte Wörter müssen alle vorkommen (in Überschrift oder Vorspann); "exakte Phrase"; OR für Alternativen; -wort zum Ausschließen. Modus events sendet jedes Ereignis mit Treffer und mindestens min_sources unabhängigen Quellen (ab 2); Modus articles jeden neuen passenden Artikel.

# create
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"query": "\"green hydrogen\" OR electrolyser", "countries": ["DE","NL"], "mode": "events", "min_sources": 2}' \
  https://trendnews.uk.app/api/v1/watches

# list, one, delete
curl -H "X-API-Key: $KEY" https://trendnews.uk.app/api/v1/watches
curl -H "X-API-Key: $KEY" https://trendnews.uk.app/api/v1/watches/12
curl -X DELETE -H "X-API-Key: $KEY" https://trendnews.uk.app/api/v1/watches/12

# new hits since the last one you have
curl -H "X-API-Key: $KEY" "https://trendnews.uk.app/api/v1/watches/12/hits?since_id=3051&limit=100"

Beispiel für einen watch.match-Body:

{
  "type": "watch.match",
  "created_at": "2026-10-26T19:12:40Z",
  "data": {
    "watch": { "id": 12, "name": "Hydrogen", "query": "\"green hydrogen\" OR electrolyser" },
    "hit": { "kind": "event", "id": "ev_x8ox05csqqyae", "title": "…", "url": "https://trendnews.uk.app/event.php?id=ev_x8ox05csqqyae",
             "country": "DE", "lang": "de", "independent_sources": 3, "published_at": "2026-10-26T17:40:02Z",
             "api_url": "https://trendnews.uk.app/api/v1/events/ev_x8ox05csqqyae" }
  }
}

Der erste Lauf einer neuen Suche füllt den RSS mit den Treffern des letzten Tages, ohne sie an den Webhook zu senden; danach geht nur Neues an den Webhook. Signatur und Wiederholungen wie bei anderen Webhooks.

Märkte

Kurse von Bitcoin, Ethereum, Solana, XRP, Gold, Silber, Brent-Öl, S&P 500, Nasdaq, EUR/USD und USD/UAH zusammen mit den Nachrichten, die sie bewegen. Claude markiert jedes Ereignis mit mindestens zwei unabhängigen Quellen: um welches Asset es geht, in welche Richtung es den Kurs drückt (up, down, neutral) und wie wichtig es ist (impact 1–3). Kurse von Binance und Yahoo Finance, alle 15 Minuten aktualisiert.

Assets: bitcoin, ethereum, solana, xrp, gold, silver, brent, sp500, nasdaq, eurusd, usduah. Dieselben Daten finden Sie auf der Seite https://trendnews.uk.app/markets/.

curl -H "X-API-Key: YOUR_KEY" "https://trendnews.uk.app/api/v1/markets/bitcoin/moves?lang=en&limit=5"

Der Zusammenhang zwischen Nachrichten und Kurs ist wahrscheinlich, nicht bewiesen. Dies ist keine Anlageberatung.

MCP für KI-Agenten

TrendNews hat einen MCP-Server (Model Context Protocol): Ein KI-Agent – Claude, Cursor oder Ihr eigener – sucht selbst Ereignisse, liest Belege mit Zitaten, prüft Trends und verwaltet gespeicherte Suchen. Adresse: https://trendnews.uk.app/mcp (Streamable HTTP). Autorisierung mit demselben API-Schlüssel im Header X-API-Key; jeder Tool-Aufruf zählt als eine API-Anfrage im Kontingent Ihres Tarifs.

Tools: search_events, get_event, get_event_evidence, get_trends, list_digests, list_countries, get_markets, explain_price_moves, list_saved_searches, create_saved_search, get_saved_search_hits.

# Claude Code
claude mcp add --transport http trendnews https://trendnews.uk.app/mcp --header "X-API-Key: YOUR_KEY"

# Cursor, Windsurf, Claude Desktop… (mcp.json)
{
  "mcpServers": {
    "trendnews": {
      "url": "https://trendnews.uk.app/mcp",
      "headers": { "X-API-Key": "YOUR_KEY" }
    }
  }
}

Der Server weist den Agenten darauf hin, dass „bestätigt“ „von mindestens zwei unabhängigen Quellen berichtet“ bedeutet, nicht „wahr“, und bittet ihn, die Originalquellen zu zitieren.

Code examples

Get the 10 latest economy posts for Ukraine:

curl -H "X-API-Key: $TN_KEY" \
  "https://trendnews.uk.app/api/v1/posts?country=UA&category=economy&limit=10"

// Node.js 18+ (on the server — not in the browser)
const res = await fetch(
  "https://trendnews.uk.app/api/v1/posts?country=UA&category=economy&limit=10",
  { headers: { "X-API-Key": process.env.TN_KEY } }
);
if (!res.ok) throw new Error((await res.json()).error.message);
const { data, meta } = await res.json();
data.forEach(p => console.log(p.date, p.title, p.url));

$ch = curl_init('https://trendnews.uk.app/api/v1/posts?country=UA&category=economy&limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('TN_KEY')],
    CURLOPT_TIMEOUT        => 10,
]);
$body = json_decode(curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($code !== 200) throw new RuntimeException($body['error']['message'] ?? "HTTP $code");
foreach ($body['data'] as $p) echo $p['date'], ' ', $p['title'], PHP_EOL;

import os, requests

r = requests.get(
    "https://trendnews.uk.app/api/v1/posts",
    params={"country": "UA", "category": "economy", "limit": 10},
    headers={"X-API-Key": os.environ["TN_KEY"]},
    timeout=10,
)
r.raise_for_status()
for p in r.json()["data"]:
    print(p["date"], p["title"], p["url"])

Iterate over all result pages:

offset = 0
while True:
    page = requests.get(f"{BASE}/api/v1/posts", params={"country": "GB", "limit": 100, "offset": offset},
                        headers={"X-API-Key": KEY}, timeout=10).json()
    handle(page["data"])
    if not page["meta"]["has_more"]:
        break
    offset += 100

Try it

You can create a key in your account. The request goes straight from your browser. The key is not stored anywhere and is gone after a page reload.