How to compare news trends between two periods#

To compare news trends between two periods, call /v1/news/trends with compare=true and a compare_window. The endpoint counts each value in your current window, then counts the same window shifted back by compare_window, and returns the difference per value as previous_count, change_absolute and change_percent. This compares the top entities in the last 7 days against the 7 days before:

curl "https://api.apitube.io/v1/news/trends?field=entity.id&published_at.start=NOW-7DAYS&compare=true&compare_window=7DAYS&api_key=YOUR_API_KEY"

This is the period-over-period mode built on top of the ranking described in How to discover trending topics and entities. Pass your key as the api_key query parameter or an X-API-Key header, with GET (query parameters) or POST (JSON body).

How does the compare_window work?#

compare_window is the offset between your two periods, not a second date range. The endpoint takes your current window (set by published_at.start / published_at.end, or the default last 30 days) and shifts a copy of it backwards by compare_window to build the “previous” period. So with a 7-day current window and compare_window=7DAYS, you compare this week against last week. Set compare_window=1YEAR to compare the same recent window against the matching window a year ago.

compare_window is required whenever compare=true; omitting or mistyping it returns error ER0352. It accepts the same relative-duration formats as the date filters — 24HOURS, 7DAYS, 1WEEK, or short aliases like 1w and 2m. The shift is clamped between 1 hour and 1 year.

What does the comparison response add?#

With compare=true, every trend keeps its normal count and gains three fields:

{
  "status": "ok",
  "field": "entity.id",
  "compare_window": "7DAYS",
  "trends": [
    {
      "value": { "id": 1599, "name": "OpenAI", "type_id": 3, "wikidata_id": "Q21708200" },
      "count": 412,
      "previous_count": 250,
      "change_absolute": 162,
      "change_percent": 64.8
    }
  ],
  "request_id": "8a4d1f6c-3e75-49b2-b8c0-2f9a6d4e1c73"
}

previous_count is the value’s count in the shifted period, change_absolute is count − previous_count, and change_percent is the percentage change. When a value had zero articles in the previous period but appears now, change_percent is reported as 100 — that flags a genuinely new trend. The response echoes the compare_window you used.

How to rank by the biggest movers#

By default the list is ranked by count, so a story that is large but flat sits at the top. To surface what is moving instead, add sort=change: it orders the trends by change_percent, so the fastest risers (or, with order=asc, the fastest fallers) come first. The change sort mode is only available when compare=true.

curl "https://api.apitube.io/v1/news/trends?field=topic.id&compare=true&compare_window=1WEEK&sort=change&api_key=YOUR_API_KEY"

How to see the trend as a time series#

A second way to study change over time is time_bucket, which breaks the current window into intervals instead of comparing to a past one. Set it to hour, day, week or month, and each value comes back with a buckets map of counts per interval plus a total:

curl "https://api.apitube.io/v1/news/trends?field=category.id&published_at.start=NOW-14DAYS&time_bucket=day&api_key=YOUR_API_KEY"

{
  "status": "ok",
  "field": "category.id",
  "time_bucket": "day",
  "trends": [
    { "value": "medtop:04000000", "total": 318, "buckets": { "2026-06-25": 41, "2026-06-26": 55 } }
  ]
}

In time_bucket mode the value is the raw id (it is not enriched with a name), and results are ordered by total descending. Use compare when you want a single period-over-period delta, and time_bucket when you want the day-by-day shape; run them as separate requests rather than combining the two in one call.

What are the limits and cost?#

The current window is capped at 30 days (and defaults to the last 30 days if you pass no dates) — a wider range returns ER0353. The compare_window offset is separate from that cap and may reach a year back. field is required and accepts up to five comma-separated values from source.id, category.id, topic.id, industry.id and entity.id; per_page defaults to 10 and maxes at 100. Each call costs 1 point regardless of compare or bucketing. On a test key the structure returns but every value is masked as [Upgrade subscription plan], so use a live key for real comparisons.

Common Questions#

• What is the difference between compare and time_bucket?
• Why does change_percent show 100?
• Can I compare against a period more than 30 days ago?
• Which error codes apply when comparing?

What is the difference between compare and time_bucket?#

compare returns one delta per value — the current count versus the same window shifted back by compare_window — which answers “is this up or down versus last period?”. time_bucket returns a series of counts split by hour, day, week or month, which answers “what shape did it take across the window?”. Use compare for a headline change number and time_bucket to chart the curve.

Why does change_percent show 100?#

A change_percent of 100 means the value had no articles in the previous period and appears in the current one, so it is treated as a brand-new trend rather than a normal percentage rise. Read it together with change_absolute and count to judge how big the new entry actually is.

Can I compare against a period more than 30 days ago?#

Yes. The 30-day cap applies only to the current window you measure; the compare_window offset can reach back up to a year. For example, keep a 7-day current window and set compare_window=1YEAR to compare this week against the same week last year.

Which error codes apply when comparing?#

ER0352 means compare_window is missing or malformed while compare=true. ER0350 means field is missing or invalid, and ER0353 means your date range exceeds 30 days. The usual codes also apply: ER0201/ER0202 (401) for a missing or invalid key, ER0176 (402) when you are out of points, and ER0203 (429) for the 50-requests-per-minute rate limit on a live key.