Filtering

All data endpoints have an extensive filter request property allowing you to filter profiles down to specific subsets for analysis. A list of all of the available facets, filters, and metrics can be found in the /meta endpoint.

Most filters are associated with a particular taxonomy and have both id filters and name filters. For instance, to filter by job title you may use the title filter with job title codes or the title_name filter with job title names. These filters require exact matches, including capitalization, punctuation, and whitespace, in order to work as expected. Supported codes and/or names can be found by performing a ranking along the filter's facet (see /rankings for more details) or by searching in one of the taxonomy endpoints (see /taxonomies).

Each taxonomy filter has both a shorthand and a verbose syntax.

Shorthand: a list of items.

{
  "title_name": ["Data Scientist", "Computer Scientist"]
}

These filters match all profiles that include either one of the job titles "Data Scientist" or "Computer Scientist".

This shorthand filter syntax is equivalent to the following in the verbose form:

{
  "title_name": {
    "include": ["Data Scientist", "Computer Scientist"],
    "include_op": "or"
  }
}

Verbose: an object defining inclusive/exclusive items and optional operators defining how to match those items in a profile.

{
  "skills_name": {
    "include": ["SQL (Programming Language)", "C++ (Programming Language)"],
    "include_op": "and",
    "exclude": ["Java (Programming Language)", "C Sharp (Programming Language)"],
    "exclude_op": "or"
  }
}

These filters match all profiles that mention both SQL and C++ skills while not mention Java or C# skills.

Note: the include_op and exclude_op fields apply to include and exclude fields respectively, they default to or if unspecified.

and – match profiles that include/exclude all items in the list
or – match profiles that include/exclude any of the items in the list

Combining multiple values in the include/exclude fields of a filter with an and operator currently is only useful for filters that have multiple values per profile (e.g., skills and certifications). Using this approach on filters that only have a single value per profile (i.e., company, occupation, job title, etc.) would always result in 0 matching profiles.

Note: the include_op and exclude_op fields can only be used with an or operator on the educations filter.

All filters applied to a request must be true for a profile to be included in the response. See the "Full Reference" tab under each endpoint for the full listing of filters and metrics that can be applied to your requests.