URL reach

Estimated impressions per URL over time, and the top-reaching URLs for a market and window.

URL-reach is the low-level counterpart to the feed: read-only access to the incrementally maintained Google Discover reach forecast per (url, country, lang). The underlying table refreshes about every five minutes via pg_cron, and responses are cached in Redis. Two endpoints are available — hourly /url-reach rows and a windowed /url-reach/top aggregate — both mounted identically under /v1 and /v2.

#Hourly URL reach

GET/v2/url-reachAPI key

Per-hour reach rows for the Discover reach forecast, filtered by url / url_id / country / lang / hour range and paginated. Also available at /v1/url-reach with the same behaviour.

Query parameters

urlstringoptional: Exact feed URL (equality match).
url_idstringoptional: The URL id (urls.id, a UUID).
countrystringoptional: ISO 3166-1 alpha-2 (e.g. us, ru), lower-cased internally. Validated against the key; single-country keys apply their country implicitly when omitted.
langstringoptional: ISO 639-1 language code (e.g. en, ru), lower-cased internally.
date_fromstringoptional: ISO 8601 timestamp — inclusive lower bound on hour_bucket.
date_tostringoptional: ISO 8601 timestamp — inclusive upper bound on hour_bucket.
sortstringoptionaldefault hour: One of hour, reach, views. hour sorts newest hour_bucket first; reach sorts by highest est_url_reach; views sorts by highest count_views. All descending; reach and views tie-break by newest hour. An invalid value returns 400.
limitintegeroptionaldefault 100: Page size, 1–1000.
offsetintegeroptionaldefault 0: Page offset (≥ 0).

curl

curl "https://d2tr.com/api/v2/url-reach?country=us&lang=en&sort=reach&date_from=2026-06-30T00:00:00Z&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "rows": [
    {
      "url_id": "6f1c2e0a-8d5b-4a9e-9c2f-1a2b3c4d5e6f",
      "country_code": "us",
      "lang_code": "en",
      "url": "https://example.com/big-game-recap",
      "hour_bucket": "2026-06-30T18:00:00+00:00",
      "local_ts": "2026-06-30T14:00:00-04:00",
      "avg_position": 3.1,
      "count_views": 5400,
      "est_url_reach": 48200
    }
  ],
  "total": 312,
  "limit": 2,
  "offset": 0
}

#Top URLs by reach

GET/v2/url-reach/topAPI key

Top URLs by estimated reach aggregated over a trailing window (across hours and days), backed by the get_url_reach_top RPC over the daily rollup. Also available at /v1/url-reach/top. Unlike hourly reach, this is a single top-N slice — it is not paginated.

Query parameters

daysintegeroptionaldefault 7: Trailing window size in days, 1–30. The window is purely days back from now (UTC).
countrystringoptional: ISO 3166-1 alpha-2 (e.g. us, br). Validated against the key; single-country keys apply their country implicitly.
langstringoptional: ISO 639-1 language code (e.g. en, pt).
limitintegeroptionaldefault 100: Number of top URLs to return, 1–1000.

curl

curl "https://d2tr.com/api/v2/url-reach/top?days=7&country=us&lang=en&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "rows": [
    {
      "url": "https://example.com/big-game-recap",
      "country_code": "us",
      "lang_code": "en",
      "total_est_reach": 1840230.0,
      "total_views": 355120,
      "avg_position": 2.9
    }
  ],
  "window_days": 7,
  "country": "us",
  "lang": "en",
  "limit": 2
}