Keyword Filters

Filter and sort keyword results server-side using a simple, unified filter format across every keyword endpoint.

Every keyword endpoint accepts an optional filters, match, and sort block so you can narrow results down to exactly the keywords you care about — high volume, low difficulty, commercial intent, and so on — without post-processing the response yourself.

The same format works on all of these endpoints:

Example

curl -X POST https://api.yepapi.com/v1/seo/keywords/ideas \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "running shoes",
    "limit": 100,
    "filters": [
      { "field": "volume", "op": ">=", "value": 500 },
      { "field": "difficulty", "op": "<", "value": 40 },
      { "field": "intent", "op": "in", "value": ["informational", "commercial"] }
    ],
    "match": "all",
    "sort": ["volume:desc"]
  }'

This returns keyword ideas with at least 500 monthly searches and a difficulty below 40 and an informational or commercial intent, sorted by search volume, highest first.

Request Fields

Parameter	Type	Required	Description	Default
`filters`	`object[]`	No	Up to 8 filter expressions (see below)	—
`match`	`string`	No	How to combine filters: `"all"` (AND) or `"any"` (OR)	`"all"`
`sort`	`string[]`	No	Up to 3 sort rules, e.g. `"volume:desc"`	—

Filter Expression

Each entry in filters is an object with three keys:

Key	Type	Description
`field`	`string`	The field to filter on (see Filterable Fields)
`op`	`string`	The comparison operator (see Operators)
`value`	`number` \| `string` \| `array`	The value to compare against. `in` / `nin` take an array.

Filterable Fields

Filter on the same friendly field names you get back in the response — no need to learn the underlying provider's nested field paths.

Field	Type	Description
`keyword`	`string`	The keyword text
`volume`	`number`	Average monthly search volume
`cpc`	`number`	Cost per click in USD
`competition`	`number`	PPC competition index (0–1)
`competitionLevel`	`string`	`LOW`, `MEDIUM`, or `HIGH` (case-insensitive)
`difficulty`	`number`	SEO difficulty score (0–100)
`intent`	`string`	`informational`, `commercial`, `navigational`, or `transactional`
`words`	`number`	Number of words in the keyword (great for isolating long-tail terms)
`length`	`number`	Number of characters in the keyword

Filtering by keyword length

words and length let you target short, punchy keywords or long-tail phrases:

{
  "filters": [
    { "field": "volume", "op": ">=", "value": 200 },
    { "field": "words", "op": ">=", "value": 4 }
  ],
  "match": "all"
}

This returns only long-tail keywords (4+ words) with at least 200 monthly searches.

A couple of notes on how these are evaluated:

words is filtered upstream on /v1/seo/keywords/ideas. On all other endpoints it's computed from the returned keyword string.
length (character count) is always computed from the returned keyword string — there is no upstream equivalent.
Because they may be evaluated on the returned page, words/length can only be combined with other filters using match: all on the DataForSEO-backed endpoints; pairing a client-side field with upstream fields under match: any returns a 400.
words and length are filter-only — you can't sort by them.

Operators

Operator	Aliases	Meaning
`>`	`gt`	Greater than
`>=`	`gte`	Greater than or equal
`<`	`lt`	Less than
`<=`	`lte`	Less than or equal
`=`	`eq`	Equals
`!=`	`ne`	Not equal
`in`	—	Value is in the provided array
`nin`	`not_in`	Value is not in the provided array
`like`	—	Substring match (text fields)
`not_like`	—	Negated substring match (text fields)

Sorting

Each sort rule is a "field:direction" string. Direction is asc or desc and defaults to desc if omitted. The first rule is the primary sort key.

"sort": ["volume:desc", "difficulty:asc"]

Notes

A maximum of 8 filters and 3 sort rules are allowed per request.
match applies one connector to the whole set — mixing AND and OR in a single request is not supported.
For /v1/seo/keywords (exact search-volume lookups), filters and sorting are applied to the returned list rather than upstream, but the format and behavior are identical.
Invalid fields, operators, or value types return a 400 validation error before any data is fetched, so you are never charged for a malformed filter.

Keyword Filters

On this page