Financial Data API — Documentation

The screener is the cross-country analogue of an equity stock screener. Instead of filtering tickers by fundamentals, you filter countries by the latest values of canonical macro indicators: “show me countries with CPI inflation above 3% and unemployment below 5%.” Financial Data API evaluates the latest public reading of each indicator per country and returns the countries that satisfy every clause.

The screener screens public indicator values only. It reads the latest public observation per canonical indicator and applies your filters to those numbers. It never exposes any internal scoring, and it never touches licensed or internal_only data.

How it works

The HTTP API is read-only and GET-only, so filters arrive as a single compact query parameter, the filter DSL. Each clause is field:operator:value, clauses are comma-separated, and they are AND-ed together. A country qualifies only when every clause matches one of its indicators and that indicator’s latest value satisfies the operator.

filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5

This reads as: CPI inflation greater than 3 and unemployment rate less than 5.

The filter DSL

Anatomy of a clause

A clause has three colon-separated parts:

Part	Example	Notes
`field`	`cpi_inflation_yoy`	A canonical indicator slug. Discover the full list at `/screener/filters`.
`operator`	`gt`	One of the operators below.
`value`	`3`	A number. The `in` operator takes pipe-separated numbers.

Operators

Operator	Meaning	Example
`gt`	Greater than	`cpi_inflation_yoy:gt:3`
`lt`	Less than	`unemployment_rate:lt:5`
`gte`	Greater than or equal	`policy_rate:gte:4`
`lte`	Less than or equal	`gdp_growth_yoy:lte:1`
`eq`	Equal	`policy_rate:eq:0`
`in`	Value is in a pipe-separated set	`policy_rate:in:0	0.25	0.5`

The in operator is the only one that takes more than one value. Separate its values with the pipe character |:

filter=policy_rate:in:0|0.25|0.5

AND semantics

Clauses are joined with commas and every clause must hold. There is no OR; build the union you want client-side by issuing separate requests. A country with no reading for a clause’s field, or a null latest value, does not satisfy that clause and is dropped.

# Inflation above 3 AND unemployment below 5 AND policy rate at or above 4
filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5,policy_rate:gte:4

Discovering fields

Field names are canonical indicator slugs. The authoritative list, with the operators, the syntax reminder, and an example, lives at GET /screener/filters.

curl -s "https://api.financialdatapi.com/screener/filters" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import os, requests

resp = requests.get(
    "https://api.financialdatapi.com/screener/filters",
    headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["operators"])
for f in data["fields"]:
    print(f["field"], "-", f["name"])

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });
const { data } = await client.screenerFields();
console.log(data.fields);

The response:

{
  "data": {
    "operators": ["gt", "lt", "gte", "lte", "eq", "in"],
    "syntax": "filter=field:operator:value,field:operator:value (clauses are AND-ed; the 'in' operator takes pipe-separated values)",
    "example": "filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5",
    "fields": [
      {
        "field": "cpi_inflation_yoy",
        "indicatorId": "indicator_cpi_inflation_yoy",
        "name": "CPI inflation, year over year",
        "category": "inflation",
        "unit": "percent"
      }
    ]
  }
}

Field matching is forgiving: it accepts the canonical slug, the indicator_-prefixed id, and registered aliases for the same indicator. When in doubt, use the field value exactly as returned by /screener/filters.

Running a screen

Send your clauses as the filter parameter to GET /screener. The filter parameter is required.

curl -s "https://api.financialdatapi.com/screener?filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import os, requests

resp = requests.get(
    "https://api.financialdatapi.com/screener",
    headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
    params={"filter": "cpi_inflation_yoy:gt:3,unemployment_rate:lt:5"},
)
resp.raise_for_status()
for hit in resp.json()["data"]:
    print(hit["country"], hit["name"])

import { FinancialDataApiClient, buildScreenerFilter } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

// Pass structured filters; the SDK serializes them into the DSL for you.
const { data } = await client.screen([
  { field: "cpi_inflation_yoy", operator: "gt", value: 3 },
  { field: "unemployment_rate", operator: "lt", value: 5 },
]);
console.log(data);

// Equivalent with a raw DSL string:
await client.screen("cpi_inflation_yoy:gt:3,unemployment_rate:lt:5");

// buildScreenerFilter() is exported if you want the string without calling screen():
const filter = buildScreenerFilter([
  { field: "policy_rate", operator: "in", value: [0, 0.25, 0.5] },
]);
// filter === "policy_rate:in:0|0.25|0.5"

The response

Each result is a country that satisfied every clause, with the matched indicator values inlined so you can see what it scored on without a second call.

{
  "data": [
    {
      "entity": "USA",
      "country": "USA",
      "name": "United States",
      "values": [
        {
          "field": "cpi_inflation_yoy",
          "indicatorId": "cpi_inflation_yoy",
          "indicatorName": "CPI inflation, year over year",
          "value": 3.1,
          "unit": "percent",
          "periodEnd": "2026-05-31",
          "observedAt": "2026-05-31"
        },
        {
          "field": "unemployment_rate",
          "indicatorId": "unemployment_rate",
          "indicatorName": "Unemployment rate",
          "value": 4.2,
          "unit": "percent",
          "periodEnd": "2026-05-31",
          "observedAt": "2026-05-31"
        }
      ]
    }
  ],
  "meta": { "api_version": "v1" },
  "requestId": "0c4f..."
}

string

The matched entity key (the country ISO code).

string

ISO alpha-3 country code.

string

Country display name.

object[]

One entry per clause, showing the indicator value that satisfied it.

Optional parameters

Besides the required filter, the screener accepts three optional parameters.

Param	Values	Description
`country`	ISO code	Restrict the screen to a single country (useful as a yes/no test).
`freshness`	`fresh`	Only consider readings that pass the freshness gate, so stale prints cannot qualify a country.
`limit`	1 to 500, default 100	Cap the number of returned countries.

# Same screen, but only over fresh readings, limited to 20 countries
curl -s "https://api.financialdatapi.com/screener?filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5&freshness=fresh&limit=20" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

freshness=fresh is recommended for live decision-making. Without it, a country can qualify on an old print that is past its publication cadence. With it, those stale readings are excluded before filtering.

More examples

# Inflation above target and a tight policy stance
curl -s "https://api.financialdatapi.com/screener?filter=cpi_inflation_yoy:gt:2,policy_rate:gte:4&freshness=fresh" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

# Countries at one of a set of policy rates
curl -s "https://api.financialdatapi.com/screener?filter=policy_rate:in:0|0.25|0.5" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

# Does the UK currently meet these conditions?
curl -s "https://api.financialdatapi.com/screener?filter=cpi_inflation_yoy:gt:3&country=GBR" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

Errors

The screener fails closed and returns a stable error code on bad input.

Situation	Code	Status
`filter` is missing	`bad_request`	400
A clause is malformed (not `field:operator:value`)	`bad_request`	400
An unknown operator	`bad_request`	400
A non-numeric value (or empty `in` set)	`bad_request`	400
`limit` out of the 1 to 500 range	`bad_request`	400
An unknown query parameter	`bad_request`	400

The error message names the offending clause so you can fix it quickly. The @financialdatapi/client SDK throws a FinancialDataApiError carrying the code, HTTP status, and requestId:

import { FinancialDataApiError } from "@financialdatapi/client";

try {
  await client.screen("cpi_inflation_yoy:gt:notanumber");
} catch (error) {
  if (error instanceof FinancialDataApiError) {
    console.error(error.code, error.status, error.message);
  }
}

Next steps

Discover fields

The catalog guide covers the full indicator list the screener fields come from.

Pull the values

Once a screen narrows your set, fetch the full point-in-time series with the observations API.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Macro screener

How it works

The filter DSL

Anatomy of a clause

Operators

AND semantics

Discovering fields

Running a screen

The response

Optional parameters

More examples

Errors

Next steps

Discover fields

Pull the values

​How it works

​The filter DSL

​Anatomy of a clause

​Operators

​AND semantics

​Discovering fields

​Running a screen

​The response

​Optional parameters

​More examples

​Errors

​Next steps

Discover fields

Pull the values

How it works

The filter DSL

Anatomy of a clause

Operators

AND semantics

Discovering fields

Running a screen

The response

Optional parameters

More examples

Errors

Next steps