Filters and signals

Filters narrow a query without making ranking fuzzier. Adding words to q costs relevance; adding a filter costs nothing.

Every filter

All of these work on /search, /stories and /top-headlines, and as arguments to the equivalent MCP tools.

Name	Type	Description
source	string	Source domain, e.g. bbc.co.uk.
source_type	string	web \| citation \| academic_archive \| defense_archive \| journal_archive \| non_textual \| other.
publisher_country	string	The publisher's canonical two-character country identifier.
language	string	Source language, ISO-639-3, e.g. eng, fra, ara, zho.
story_id	string	A cluster id from /stories, to expand one story into its articles.
topic	string	An exact canonical topic identifier returned by the API.
organization	string	An exact organization entity.
person	string	An exact person entity.
country	string	A mentioned country's canonical two-character identifier.
author	string	An exact article author.
location	string	An exact mentioned location.
location_id	string	An exact canonical location identifier.
city	string	An exact mentioned city.
region	string	An exact mentioned region.
name	string	An exact proper name.
mentioned_date	string	An exact date mentioned in the article text.
quote_verb	string	An exact verb introducing a quotation.
amount_object	string	An exact object described by a numeric amount.

Where the values come from

Filter	Vocabulary
`language`	ISO 639-3, three letters: `eng`, `fra`, `ara`, `zho`. Not `en`.
`country`, `publisher_country`	Two-character country identifiers. `country` is a country mentioned in the article; `publisher_country` is where the outlet is.
`topic`	Canonical topic identifiers, returned in every article's `topics`. Coarse and machine-generated — treat them as a filter, not as a taxonomy to show a user.
`organization`, `person`, `name`	Extracted entities, lower-cased and canonicalised. Read them off a result.
`location`, `city`, `region`	Full location strings as extracted ("Austin, Texas, United States"). For stable matching prefer `location_id`.
`location_id`	A numeric canonical identifier, from an article's `location_details` via `/doc/{id}`.
`source`	The publisher's domain, e.g. `bbc.co.uk`. No scheme, no `www.`.
`story_id`	A cluster id from `/stories` or from any article's `story_id`.
`mentioned_date`	A date mentioned in the text, `YYYY-MM-DD` — not the publication date.
`quote_verb`, `amount_object`	From an article's `quotes` and `amounts`; see `/doc/{id}`.

Signals

Every article carries derived intensities across three families. They are not sentiment and not a classification — they measure how strongly an article's language sits in a given register, so range-filtering on them finds coverage with a particular character rather than a particular word.

Each article reports the version that produced them (signals.version), so a change to the model is visible in the data rather than silently shifting your thresholds.

Industry

What sector the coverage is about.

economy · healthcare · agriculture · labor · environment · energy · transportation · real_estate · finance · defense · science_technology · trade · public_sector

Business context

The financial register the article is written in.

financial_uncertainty · financial_negative · financial_positive · legal_litigation · financial_stability_stress

Risk context

Disruption, threat and instability language.

anxiety · conflict · supply_disruption · cyber_incident · climate · health_security · governance_risk

Filtering on them

One constraint:

curl -s -G "https://api.unzoi.com/search" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=quarterly results" \
  --data-urlencode "signal=financial_uncertainty" \
  --data-urlencode "signal_min=2.0"

Several at once, ANDed, as name[:min[:max]] separated by commas — an empty bound means unbounded:

curl -s -G "https://api.unzoi.com/search" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=shipping" \
  --data-urlencode "signals=supply_disruption:1.5:,transportation:0.5:3"

Over MCP the same thing is an array of objects, which is easier for a model to emit correctly:

{
  "name": "search_news",
  "arguments": {
    "q": "shipping",
    "signals": [
      { "name": "supply_disruption", "min": 1.5 },
      { "name": "transportation", "min": 0.5, "max": 3 }
    ]
  }
}

There is no absolute scale to memorise — intensities are relative, and the useful thresholds depend on the corpus slice you are looking at. Entity and signal filtering shows how to find a threshold empirically instead of guessing one.