Search & ranking

Hybrid full-text and fuzzy search, weighted by freshness.

Parameters

How ranking works

Each candidate gets a base relevance score: the greater of the PostgreSQL full-text rank (tsvector) and the trigram similarity on the title. That score is then multiplied by a recency weight with a 30-day half-life, so fresh reporting outranks older archive that happens to match the query more strongly.

score = base_relevance * 0.5 ^ (age_days / 30)

Results are ordered by score descending, then by published_at. A 30-day-old article carries half the weight of a fresh one; a year-old article carries a fraction of a percent.

Example

curl "https://api.kontextnews.online/v1/search?q=OpenAI&category=ai&limit=5" \
  -H "X-API-Key: kn_live_..."

[
  {
    "title": "To comply with the EU AI Act, OpenAI plans to add text watermarking...",
    "category": "ai",
    "region": "global",
    "published_at": "2026-10-05T13:55:03+00:00",
    "rank": 0.802
  },
  {
    "title": "Depois da Anthropic, OpenAI anuncia que tambem deixara marca d'agua...",
    "category": "ai",
    "region": "south_america",
    "published_at": "2026-10-05T15:55:00+00:00",
    "rank": 0.729
  }
]