Business Search query syntax

A Business Search structured query is a nested JSON object sent as the query property in Ludicrous mode. Field operators create conditions, and logical operators combine them.

Which operators does a structured query accept?

Operator	Meaning
`and`	All child conditions must match
`or`	At least one child condition must match
`not`	Exclude records matching its child condition
`equals`	Match an exact field value
`in`	Match any value in a supplied list
`range`	Match numeric bounds using `>`, `>=`, `<` or `<=`
`text`	Search a supported text field

and, or and not take conditions as children. equals, in, range and text take a field name and a value.

How do you combine conditions?

Nest logical operators to build the boolean expression you need. This company query searches for software or technology companies in the US or GB, excluding records whose organization type is Educational:

{
  "and": [
    {
      "or": [
        { "text": { "industry": "software" } },
        { "text": { "industry": "technology" } }
      ]
    },
    { "in": { "headquarters_country_code": ["US", "GB"] } },
    { "not": { "equals": { "organization_type": "Educational" } } }
  ]
}

Use in instead of chaining or plus equals on the same field. It suits country lists, industry lists and any enumerated value set.

How does text matching work?

A text condition can contain a string, as in the company example above, or an object with value and mode. Use mode: "all" when every search word must match. The words do not need to form an exact phrase:

{
  "text": {
    "current_title": {
      "value": "machine learning engineer",
      "mode": "all"
    }
  }
}

mode accepts seven values, and the API rejects any other value with an HTTP 400 that lists them:

Mode	Behavior
`top-bm25`	Default. BM25-ranked partial matches
`all`	Every search word must match
`all-or-top-bm25`	All-word match first, backfilled with BM25 matches when there are too few
`top-idf`	IDF-ranked partial matches
`all-or-top-idf`	All-word match first, backfilled with IDF matches
`any`, `top-bm25-daat`	Accepted, not documented here

top-k caps how many candidate records the text condition retrieves, 100 by default. No mode matches an exact phrase. text works only on text fields. On a typed field such as headquarters_country_code it returns HTTP 400 with Operator does not support field type 'string'. Supported types: array<text>, text. equals does not work on text fields. The operator a field accepts depends on its type: fields typed as text, such as industry and current_title, accept only text, and sending equals to one returns HTTP 400 with Operator does not support field type 'text'. equals, in and range are for typed fields such as headquarters_country_code, city and followers.

How do you express a numeric bound?

range takes a field name and one or two comparison keys. Supply both keys for a closed interval:

{
  "range": {
    "employees_in_linkedin": { ">=": 50, "<=": 500 }
  }
}

Supply one key for an open bound, such as { "followers": { ">=": 1000 } }.

Which fields can you search?

Field names differ by category, and the operator a field accepts depends on its type. The full lists are on Company search and People search. A field that appears in view output is not necessarily searchable: people connections is returned in summary but cannot be used in a range condition. When a condition is rejected, correct the request rather than retrying the same body. Business Search returns HTTP 400 with a message naming the field, the operator and the types the operator supports. See Business Search error handling.

Frequently asked questions

Does the query object change between company and people searches?

The operators are identical. The field names are not. The company category uses industry, headquarters_country_code and linkedin_followers. The people category uses current_title, country_code and followers. See Company search and People search.

Can I use a structured query with Instant or Smart mode?

No. ludicrous takes a structured object, and instant and smart take a natural-language string. A mismatch is rejected with HTTP 400: an object in Instant returns request: "query" must be a string, and a string in Ludicrous returns request: "query" must be of type object. See What is Business Search?.

Does adding a field to view filter the results?

No. view selects output fields only. Search conditions live in query, and the two are evaluated independently.

Get started

Data extraction

Web search

AI training data

Proxy networks

Which operators does a structured query accept?

How do you combine conditions?

How does text matching work?

How do you express a numeric bound?

Which fields can you search?

Frequently asked questions

Does the query object change between company and people searches?

Can I use a structured query with Instant or Smart mode?

Does adding a field to view filter the results?

​Which operators does a structured query accept?

​How do you combine conditions?

​How does text matching work?

​How do you express a numeric bound?

​Which fields can you search?

​Frequently asked questions

​Does the query object change between company and people searches?

​Can I use a structured query with Instant or Smart mode?

​Does adding a field to view filter the results?

Which operators does a structured query accept?

How do you combine conditions?

How does text matching work?

How do you express a numeric bound?

Which fields can you search?

Frequently asked questions

Does the query object change between company and people searches?

Can I use a structured query with Instant or Smart mode?

Does adding a field to view filter the results?