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
  }
}

Eventos y evidencias: cómo funciona

La capa de eventos agrupa los artículos de todos los feeds en eventos: una noticia reproducida por decenas de medios es un solo evento con un único event_id. A continuación se explica cómo se calcula cada campo, para que pueda explicar los datos a sus lectores.

Evento y event_id

Los artículos se agrupan por significado (embeddings multilingües multilingual-e5) en una ventana de 72 horas dentro del país del feed. También se comprueban palabras clave comunes y la geografía para no fusionar eventos distintos sobre un tema parecido. El event_id (formato ev_ + 13 caracteres) no cambia mientras el evento se actualiza: los artículos nuevos se suman al evento existente en lugar de crear uno nuevo.

Independencia de las fuentes

Los artículos comparten un independence_group si proceden del mismo sitio, citan la misma agencia (Reuters, AP, AFP, PTI, ANI, Ukrinform, etc.) o son copias casi idénticas. sources_total cuenta todos los medios, independent_sources cuenta los grupos independientes. Una noticia de agencia reproducida por veinte sitios cuenta como una sola fuente. Por defecto /v1/events devuelve eventos con al menos 2 fuentes independientes (parámetro min_independent).

Fecha de publicación

original_published_at es la fecha de publicación fiable más temprana entre las fuentes, first_seen es cuándo vimos el evento por primera vez. Para cada artículo, published_at_quality indica de dónde viene la fecha: feed — del feed; feed_timezone_corrected — el feed dio la hora local marcada como UTC y la corregimos con la zona horaria del país; page_metadata — de los metadatos de la página; unknown_used_first_seen — sin fecha, se usa la hora de la primera detección.

Geografía

geo.source_country es el país del feed donde se publicó el artículo. geo.event es dónde ocurrió el evento: país, región con código GeoNames (region_code, p. ej. IN.35 — Madhya Pradesh), ciudad con city_geonames_id y coordenadas. Los lugares se buscan en títulos y descripciones con el nomenclátor GeoNames (ciudades de más de 15 000 habitantes y regiones, incluidas formas locales). Filtros de /v1/events: region (código o nombre) y city (nombre o ID de GeoNames). Si el lugar no se determina con confianza, geo.event es null.

Idioma y categoría

El idioma de cada artículo se detecta a partir del texto (fastText) y sustituye al idioma del feed si la confianza es de al menos 0,8. El idioma del evento es el de la mayoría de sus artículos. La categoría es una votación de los artículos del evento; category.confidence es la proporción de votos a su favor.

Métricas de tendencia

El campo trend es transparente: mentions_1h, mentions_6h, mentions_24h son artículos nuevos en 1, 6 y 24 horas, independent_sources_24h son grupos independientes en un día y velocity es el ritmo de las últimas 6 horas frente a las 18 anteriores. La fórmula de score también se devuelve en 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)

Evidencias: dos capas

/v1/events/{id}/evidence lee los textos completos de hasta 10 fuentes (primero las independientes, respetando robots.txt) y devuelve hechos con enlaces, citas, contradicciones, incógnitas, what_changed y suggested_length_words. Este último es una extensión de texto recomendada: depende del número de hechos confirmados, para no rellenar la noticia con paja.

Capa extractiva (todos los planes): un hecho es una frase literal de una fuente, y las frases con el mismo significado se agrupan. confirmed significa que la afirmación aparece en al menos dos fuentes independientes, single_source en una, disputed que las fuentes dan cifras distintas.

Capa refinada (plan Business): Claude reescribe las frases de las fuentes como hechos atómicos y añade un breve summary neutral. El modelo no puede añadir nada propio: cada hecho debe citar frases de las fuentes, un hecho sin cita se descarta, snippet es una cita literal y el estado confirmed lo calcula el sistema según la independencia de las fuentes citadas, no el modelo. Solo se registra una contradicción cuando las fuentes dan valores mutuamente excluyentes para el mismo hecho.

El parámetro layer: auto (por defecto: capa refinada para Business, extractiva para los demás planes), refined (solo Business; si no, 403 plan_required), extractive. El campo layer de la respuesta indica qué capa se devolvió. La primera solicitud de un cliente Business pone el refinamiento en cola: mientras se prepara (normalmente menos de 30 s) se devuelve la capa extractiva con refined_status: processing y la cabecera Retry-After. En el plan Pro puede probar la capa refinada: layer=refined para 20 eventos distintos al mes (el resto, en la cabecera X-Refined-Trial-Remaining). Para otros planes la respuesta incluye refined_layer con un enlace a los planes. El campo llm indica el modelo y el número de tokens.

«Confirmado» significa que al menos dos fuentes independientes lo publicaron, no que la afirmación sea verdadera. En temas sensibles, compruebe las fuentes originales mediante los enlaces de sources.

Actualización y conservación

Los eventos se recalculan cada hora junto con la recogida de noticias. Las evidencias se actualizan automáticamente para eventos con 3 o más fuentes independientes y para los eventos cuyo refinamiento solicitó un cliente Business en las últimas 24 horas. stale: true significa que llegaron artículos nuevos tras el último cálculo y la actualización ya está en cola. Los artículos, eventos y evidencias se conservan 3 días tras su última actualización; las publicaciones y tendencias, más tiempo.

Webhooks (Business)

En lugar de consultar la API, reciba un POST con JSON en su dirección https. Se configura en el panel, pestaña «Webhooks»: dirección, países, mínimo de fuentes independientes y tipos de eventos. event.created se envía una vez, cuando un evento alcanza su número de fuentes independientes; evidence.updated, cuando cambian sus evidencias (con what_changed; para Business, la capa refinada si existe).

Cada solicitud va firmada: cabecera X-TrendNews-Signature: t=<hora unix>,v1=<hex>, donde v1 = HMAC-SHA256 de <t>.<cuerpo sin procesar> con su secreto. Verifique la firma y rechace solicitudes de más de 5 minutos. Responda con 2xx en 8 segundos; si no, reintentamos tras 1, 5, 30, 120 y 360 minutos. X-TrendNews-Delivery es un id único de entrega para evitar duplicados.

Ejemplo de cuerpo event.created:

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

Verificación de la firma (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);

Búsquedas guardadas

Una búsqueda guardada es una consulta que ejecutamos cada hora sobre las noticias nuevas. Las coincidencias se guardan 30 días y están disponibles en su RSS privado (rss_url), en la API y —en Business— en un webhook de tipo watch.match. Límites: Free — 1 búsqueda, Pro — 10, Business — 100. Créelas en su cuenta o mediante la API.

Sintaxis: las palabras separadas por espacios deben aparecer todas (en el titular o la entradilla); "frase exacta"; OR para alternativas; -palabra para excluir. El modo events envía cada evento con coincidencia y al menos min_sources fuentes independientes (2 o más); el modo articles, cada artículo nuevo que coincida.

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

Ejemplo de cuerpo watch.match:

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

La primera ejecución de una búsqueda nueva llena el RSS con las coincidencias del último día sin enviarlas al webhook; después, al webhook solo llega lo nuevo. Firma y reintentos, como en los demás webhooks.

Mercados

Precios de Bitcoin, Ethereum, Solana, XRP, oro, plata, petróleo Brent, S&P 500, Nasdaq, EUR/USD y USD/UAH junto con las noticias que los empujan. Claude etiqueta cada evento con al menos dos fuentes independientes: de qué activo trata, hacia dónde empuja el precio (up, down, neutral) y cuán importante es (impact 1–3). Precios de Binance y Yahoo Finance, actualizados cada 15 minutos.

Activos: bitcoin, ethereum, solana, xrp, gold, silver, brent, sp500, nasdaq, eurusd, usduah. Los mismos datos están en la página 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"

La relación entre las noticias y el precio es probable, no demostrada. Esto no es asesoramiento de inversión.

MCP para agentes de IA

TrendNews tiene un servidor MCP (Model Context Protocol): un agente de IA —Claude, Cursor o el suyo propio— busca eventos, lee evidencias con citas, consulta tendencias y gestiona búsquedas guardadas por sí mismo. Dirección: https://trendnews.uk.app/mcp (Streamable HTTP). La autorización es la misma clave de API en el encabezado X-API-Key; cada llamada a una herramienta cuenta como una solicitud a la API en la cuota de su plan.

Herramientas: 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" }
    }
  }
}

El servidor indica al agente que «confirmado» significa «publicado por al menos dos fuentes independientes», no «verdadero», y le pide citar las fuentes originales.

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.