Sign in

v2

latestOpenAPI 3.0.32026-07-26112274.7 KB

Rank driver datasets for your timeseries

Retrieves drivers ranked by how well they explain your timeseries, returning a scored list of potential economic drivers. Results are ordered by relevance score descending.

This is a synchronous billed endpoint — you are charged per driver returned. No charge is recorded on validation errors or upstream failures.

post/api/v1/drivers

Request body

recency_factornumber double required

Weight given to more recent observations when ranking drivers. 0.0 = equal weight; 1.0 = strongest recency bias.

timeseriesobject

Optional. Map of YYYY-MM-DD date keys to numeric observation values. When supplied, all keys must parse as YYYY-MM-DD and all values must be finite. Unlike /forecasts, this endpoint is frequency-agnostic — no monthly alignment, gap detection, or minimum length is enforced. When omitted, the handler does not forward the field upstream.

version'v1' required

Recommend pipeline version. Closed set; only v1 is supported today. Used locally to select the per-version validator and is not forwarded to the upstream Recommend service.

Example request

{
  "version": "v1",
  "recency_factor": 0.6,
  "timeseries_metadata": {
    "title": "Brent Crude Oil Price Monthly",
    "description": "Monthly average Brent crude oil spot price in USD/barrel, sourced from EIA.",
    "keywords": [
      "oil",
      "brent",
      "energy",
      "commodity"
    ]
  },
  "filters": {
    "limit": 20,
    "categories": [
      3,
      7
    ],
    "regions": [
      42
    ]
  },
  "timeseries": {
    "2023-07-01": 79.6,
    "2023-08-01": 84.77,
    "2023-09-01": 93.39,
    "2023-10-01": 91.05,
    "2023-11-01": 81.77,
    "2023-12-01": 76.1
  }
}

Response

Ranked driver candidates for your timeseries.

messagestring
statusinteger

Example response

{
  "data": {
    "drivers": [
      {
        "hash_id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
        "driver_name": "Natural Gas Futures Price (Henry Hub)",
        "score": 0.87
      }
    ]
  },
  "message": "Success"
}