General Query Constructs

The General Query Constructs define the standard query options available in the Classification API. These constructs allow you to customize responses and refine queries using parameters such as search, return fields, filters, and locales.

Search

Where available, search functionality supports searching of the id and name fields.

To search only id or name, preface the search term with the field name and a semicolon.

Example:

?q=id:data

Return Fields

Specifying return fields limits the contents of the response to the requested plus default fields for each concept. Not all concepts within a taxonomy will have the same fields (this is common for concepts at different levels in a hierarchical taxonomy).

When a concept does not contain a requested field, the response will return a null value for that concept.

For all taxonomies, the default fields are:

id
name
levelName

Example:

GET ?fields=
  
POST "fields": [ ]
  
-----

{
  "data": [
    {
      "id": "118",
      "name": "Data Science",
      "levelName": "subCategory",
      "parentId": "3",
      "level": 1
    },
    {
      "id": "BGS884A50229C6986B58",
      "name": "iOS Charts",
      "levelName": "skill",
      "parentId": "121",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": true,
      "isLanguage": false
    }
  ],
  "warnings": [],
  "errors": []
}

GET ?fields=isSoftware

POST "fields": [ "isSoftware" ]

-----

{
  "data": [
    {
      "id": "118",
      "name": "Data Science",
      "levelName": "subCategory",
      "isSoftware": null
    },
    {
      "id": "BGS884A50229C6986B58",
      "name": "iOS Charts",
      "levelName": "skill",
      "isSoftware": true
    }
  ],
  "warnings": [],
  "errors": []
}

Filter

Filter allows you to select data based on response field values.

For GET endpoints, a single filter may be specified for each available field.
For POST endpoints, multiple filters may be specified for each field.

Example:

GET ?filter=

POST "filter": { }
  
-----

{
  "data": [
    {
      "id": "13",
      "name": "Finance",
      "parentId": "13",
      "level": 0
    },
    {
      "id": "105",
      "name": "Office Management",
      "parentId": "1",
      "level": 1
    },
    {
      "id": "BGS10EE289B9FDE2C4B1",
      "name": "Investment Account Management",
      "parentId": "281",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": false,
      "isLanguage": false
    },
    {
      "id": "BGS1241B6719A7FE041D",
      "name": "Cloud Security Applications",
      "parentId": "392",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": true,
      "isLanguage": false
    },
    {
      "id": "ES2469BF1D94F8595276",
      "name": "Thai Language",
      "parentId": "498",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": false,
      "isLanguage": true
    }
  ],
  "warnings": [],
  "errors": []
}

GET ?filter=level:0

POST "filter": { "level": [ "0" ] }

-----

{
  "data": [
    {
      "id": "13",
      "name": "Finance",
      "parentId": "13",
      "level": 0
    }
  ]
}

GET N/A

POST "filter": { "level": [ "0", "1" ] }

-----

{
  "data": [
    {
      "id": "13",
      "name": "Finance",
      "parentId": "13",
      "level": 0
    },
    {
      "id": "105",
      "name": "Office Management",
      "parentId": "1",
      "level": 1
    }
  ]
}

GET ?filter=level:2,isLanguage:true

POST "filter": { "level": [ "2" ], "isLanguage": [ "true" ] }

-----

{
  "data": [
    {
      "id": "ES2469BF1D94F8595276",
      "name": "Thai Language",
      "parentId": "498",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": false,
      "isLanguage": true
    }
  ],
  "warnings": [],
  "errors": []
}

GET N/A

POST "filter": { "level": [ "1", "2" ], "isLanguage": [ "true", "false"] }

-----
  
{
  "data": [
    {
      "id": "BGS10EE289B9FDE2C4B1",
      "name": "Investment Account Management",
      "parentId": "281",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": false,
      "isLanguage": false
    },
    {
      "id": "BGS1241B6719A7FE041D",
      "name": "Cloud Security Applications",
      "parentId": "392",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": true,
      "isLanguage": false
    },
    {
      "id": "ES2469BF1D94F8595276",
      "name": "Thai Language",
      "parentId": "498",
      "level": 2,
      "skillType": "Specialized Skill",
      "isSoftware": false,
      "isLanguage": true
    }
  ],
  "warnings": [],
  "errors": []
}

Locales

Some endpoints accept one or more locale parameters. A locale refers to the language in which a piece of text is composed, sometimes qualified by country. Using locales allows you to retrieve content in the desired language or regional variation.

Format:

Locales follow the IETF language tag standard (RFC 5646):

The first subtag is required: a lowercase two-letter code representing the language (e.g., en for English).
The second subtag is optional: an uppercase two-letter country code for regional specificity (e.g., US for the United States).
When used, the country subtag is appended to the language subtag, separated by a hyphen (-).

Examples:

Example	Meaning
`en`	English
`en-US`	English (United States)
`fr`	French
`fr-CA`	French (Canada)
`es-ES`	Spanish (Spain)

Endpoints that accept locale parameters expect them as strings formatted according to the IETF language tags described above.

When a requested locale is not available, endpoints may default to the primary language or return a null value.

For reference: