TrendNews API

Швидкий старт

Базова адреса: https://trendnews.uk.app/api/v1. Зареєструйтесь, створіть API-ключ у кабінеті й надішліть перший запит:

curl -H "X-API-Key: ВАШ_КЛЮЧ" "https://trendnews.uk.app/api/v1/posts?country=UA&limit=5"

Країни задаються кодом ISO-2 (UA, US, DE, PL…). Повний список із мовами стрічок повертає /api/v1/countries. Нові пости з'являються щогодини.

Авторизація

Кожен запит, крім /v1/health, має містити API-ключ у заголовку:

X-API-Key: tn_live_…

Також приймається Authorization: Bearer tn_live_…. Передавати ключ у параметрах URL не можна: так він потрапив би в логи та історію браузера.

Тарифи та ліміти

Ліміти залежать від тарифу облікового запису. Денна квота спільна для всіх ключів облікового запису й оновлюється о 00:00 UTC. Ліміт на хвилину діє для кожного ключа окремо. Усі тарифи й ціни

Поточний стан повертається в заголовках кожної відповіді:

Відповіді можна кешувати до 60 секунд (Cache-Control: private, max-age=60): дані оновлюються раз на годину. Кешування також заощаджує квоту.

Формат відповіді та помилки

Успішна відповідь завжди має поле data, списки — ще й meta з пагінацією. Помилка має поле error з машинним кодом і поясненням.

// успіх{ "data": [ … ], "meta": { "total": 856, "limit": 20, "offset": 0, "has_more": true } }

// помилка{
  "error": {
    "code": "invalid_country",
    "message": "Unknown country code. The list of supported ISO-2 codes: /api/v1/countries"
  }
}

Пагінація

Списки повертають не більше limit записів (до 100). Щоб отримати наступну сторінку, збільште offset на limit, поки meta.has_more дорівнює true.

Ендпоінти

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

Події та докази: як це працює

Шар подій збирає статті з усіх стрічок у події: одна новина, яку передрукували десятки видань, — це одна подія з одним event_id. Нижче пояснено, як рахується кожне поле, щоб ви могли пояснити дані своїм читачам.

Подія та event_id

Статті об'єднуються за змістом (мультимовні векторні представлення multilingual-e5) у вікні 72 годин у межах країни стрічки. Додатково перевіряються спільні ключові слова та географія, щоб не склеювати різні події на схожу тему. event_id (формат ev_ + 13 символів) не змінюється, поки подія оновлюється: нові статті приєднуються до наявної події, а не створюють нову.

Незалежність джерел

Статті потрапляють в одну independence_group, якщо вони з одного сайту, посилаються на ту саму агенцію (Reuters, AP, AFP, PTI, ANI, Укрінформ тощо) або майже дослівно повторюють одна одну. sources_total — усі видання, independent_sources — кількість незалежних груп. Передрук агентської новини двадцятьма сайтами рахується як одне джерело. За замовчуванням /v1/events повертає події щонайменше з 2 незалежними джерелами (параметр min_independent).

Дата публікації

original_published_at — найраніша достовірна дата публікації серед джерел, first_seen — коли ми вперше побачили подію. Для кожної статті published_at_quality показує, звідки дата: feed — зі стрічки; feed_timezone_corrected — стрічка подала місцевий час як UTC, і ми виправили його за часовим поясом країни; page_metadata — із метаданих сторінки; unknown_used_first_seen — дати немає, використано час першого виявлення.

Географія

geo.source_country — країна стрічки, де опубліковано статтю. geo.event — де сталася подія: країна, регіон із кодом GeoNames (region_code, наприклад IN.35 — Мадх'я-Прадеш), місто з city_geonames_id і координатами. Місця шукаються в заголовках і описах за довідником GeoNames (міста від 15 000 мешканців і регіони, зокрема форми на кшталт «на Житомирщині»). Фільтри /v1/events: region (код або назва) і city (назва або GeoNames ID). Якщо місце не визначено впевнено, geo.event дорівнює null.

Мова і категорія

Мова кожної статті визначається за текстом (fastText) і замінює мову стрічки, якщо впевненість не нижча за 0,8. Мова події — мова більшості її статей. Категорія — голосування статей події, category.confidence — частка голосів за неї.

Метрики тренду

Поле trend прозоре: mentions_1h, mentions_6h, mentions_24h — нові статті за 1, 6 і 24 години, independent_sources_24h — незалежні групи за добу, velocity — темп останніх 6 годин відносно попередніх 18. Формула score також повертається в 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)

Докази: два шари

/v1/events/{id}/evidence читає повні тексти до 10 джерел (спершу незалежні, з дотриманням robots.txt) і повертає факти з посиланнями, цитати, суперечності, невідомі обставини, what_changed і suggested_length_words. Останнє — рекомендований обсяг тексту: він залежить від кількості підтверджених фактів, щоб матеріал не розтягувався «водою».

Екстрактивний шар (усі тарифи): факт — дослівне речення з джерела, речення з однаковим змістом групуються. confirmed — твердження є щонайменше у двох незалежних джерелах, single_source — в одному, disputed — джерела наводять різні числа.

Уточнений шар (тариф Business): Claude переписує речення джерел в атомарні факти й додає короткий нейтральний summary. Модель не може додати нічого від себе: кожен факт має посилатися на речення джерел, факт без посилання відкидається, snippet — дослівна цитата, а статус confirmed рахує система за незалежністю процитованих джерел, а не модель. Суперечність фіксується лише тоді, коли джерела дають взаємовиключні значення для того самого факту.

Параметр layer: auto (за замовчуванням: уточнений шар для Business, екстрактивний для інших тарифів), refined (лише Business, інакше 403 plan_required), extractive. Поле layer у відповіді показує, який шар повернуто. Перший запит Business-клієнта ставить уточнення в чергу: поки воно готується (зазвичай до 30 с), повертається екстрактивний шар із refined_status: processing і заголовком Retry-After. На тарифі Pro можна спробувати уточнений шар: layer=refined для 20 різних подій на місяць (залишок — у заголовку X-Refined-Trial-Remaining). Для інших тарифів відповідь містить refined_layer з посиланням на тарифи. Поле llm називає модель і кількість токенів.

«Підтверджено» означає, що це повідомили щонайменше два незалежні джерела, а не те, що твердження істинне. Для чутливих тем перевіряйте першоджерела за посиланнями в sources.

Оновлення і зберігання

Події перераховуються щогодини разом зі збором новин. Докази оновлюються автоматично для подій із 3 і більше незалежними джерелами та для подій, уточнення яких запитував Business-клієнт протягом останньої доби. stale: true означає, що після останнього обчислення з'явилися нові статті й оновлення вже в черзі. Статті, події та докази зберігаються 3 дні після останнього оновлення; пости й тренди — довше.

Вебхуки (Business)

Замість того щоб опитувати API, отримуйте POST із JSON на свою адресу https. Налаштування — у кабінеті, вкладка «Вебхуки»: адреса, країни, мінімум незалежних джерел і типи подій. event.created надходить один раз, коли подія набирає потрібну кількість незалежних джерел; evidence.updated — коли змінюються її докази (з полем what_changed; для Business — уточнений шар, якщо він є).

Кожен запит підписано: заголовок X-TrendNews-Signature: t=<unix-час>,v1=<hex>, де v1 = HMAC-SHA256 від рядка <t>.<сире тіло запиту> з вашим секретом. Перевіряйте підпис і відкидайте запити, старші за 5 хвилин. Відповідайте кодом 2xx протягом 8 секунд; інакше ми повторимо доставку через 1, 5, 30, 120 і 360 хвилин. Заголовок X-TrendNews-Delivery — унікальний номер доставки для захисту від дублів.

Приклад тіла 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"
  }
}

Перевірка підпису (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);

Збережені пошуки

Збережений пошук — це запит, який ми щогодини самі перевіряємо на нових новинах. Збіги зберігаються 30 днів і доступні у вашому приватному RSS (rss_url), через API та — на Business — у вебхуку з типом watch.match. Ліміт: Free — 1 пошук, Pro — 10, Business — 100. Створити пошук можна в кабінеті або через API.

Синтаксис запиту: слова через пробіл мають бути всі (у заголовку чи лиді); "точна фраза"; OR — будь-який із варіантів; -слово — виключити. Режим events надсилає кожну подію, де є збіг і щонайменше min_sources незалежних джерел (від 2); режим articles — кожну нову статтю зі збігом.

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

Приклад тіла 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" }
  }
}

Перша перевірка нового пошуку заповнює RSS збігами за останню добу без надсилання у вебхук; далі у вебхук надходить лише нове. Підпис і повтори — як для інших вебхуків.

Ринки

Ціни біткоїна, ефіріуму, солани, XRP, золота, срібла, нафти Brent, S&P 500, Nasdaq, EUR/USD і USD/UAH разом із новинами, що на них тиснуть. Claude позначає кожну подію щонайменше з двома незалежними джерелами: про який актив ідеться, у який бік новина тисне на ціну (up, down, neutral) і наскільки вона важлива (impact 1–3). Ціни — Binance і Yahoo Finance, оновлення кожні 15 хвилин.

Активи: bitcoin, ethereum, solana, xrp, gold, silver, brent, sp500, nasdaq, eurusd, usduah. Ті самі дані — на сторінці https://trendnews.uk.app/markets/.

curl -H "X-API-Key: ВАШ_КЛЮЧ" "https://trendnews.uk.app/api/v1/markets/bitcoin/moves?lang=en&limit=5"

Зв'язок між новинами й ціною — імовірний, а не доведений. Це не інвестиційна порада.

MCP для ШІ-агентів

TrendNews має MCP-сервер (Model Context Protocol): ШІ-агент — Claude, Cursor чи ваш власний — сам шукає події, читає докази з цитатами, дивиться тренди й керує збереженими пошуками. Адреса: https://trendnews.uk.app/mcp (Streamable HTTP). Авторизація — той самий API-ключ у заголовку X-API-Key; кожен виклик інструмента рахується як один запит до API у квоті вашого тарифу.

Інструменти: 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: ВАШ_КЛЮЧ"

# Cursor, Windsurf, Claude Desktop… (mcp.json)
{
  "mcpServers": {
    "trendnews": {
      "url": "https://trendnews.uk.app/mcp",
      "headers": { "X-API-Key": "ВАШ_КЛЮЧ" }
    }
  }
}

Сервер підказує агенту, що «підтверджено» означає «повідомили щонайменше два незалежні джерела», а не «правда», і просить посилатися на першоджерела.

Приклади коду

Отримати 10 останніх економічних постів України:

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

// Node.js 18+ (на сервері — не у браузері)
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"])

Обійти всі сторінки результатів:

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

Спробувати

Ключ можна створити в кабінеті. Запит іде прямо з вашого браузера. Ключ ніде не зберігається й зникає після перезавантаження сторінки.