Skip to main content

Using Filters in Requests

Using filters is a standard technique that works uniformly in the search methods of the Dateno API. Filters allow your application to exclude irrelevant results from the response, which can contain multiple dataset descriptors.

In API v2, filters are applied in the Search API using the /search/0.2/query endpoint.

Filter Usage​

The filters supported in Dateno API requests generally correspond to the facets available in the Dateno web application. Each filter relates to one of the properties of datasets or catalogs, such as:

  • language
  • country
  • catalog type
  • data format
  • topic

Most filter values are represented as directory entries (objects with id and name).

A filter defined in a request restricts descriptors included in the response by matching specific values of the corresponding fields.

Finding Filter Names​

Available filters can be discovered by inspecting dataset descriptors returned by the search API.

Example fragment from a dataset descriptor:

{
  "source": {
    "countries": [
      {
        "id": "CA",
        "name": "Canada"
      }
    ],
    "langs": [
      {
        "id": "EN",
        "name": "English"
      }
    ]
  }
}

From this structure, valid filter names include:

  • source.countries.id
  • source.countries.name
  • source.langs.id
  • source.langs.name

Adding Filters to Requests​

Use the filters query parameter to pass filters to the API.

Each filter is expressed as:

filters="<field>"="<value>"

Multiple filters can be included by repeating the filters parameter.

Example​

Retrieve datasets related to rabbits, published in Canada, written in French:

curl "https://api.dateno.io/search/0.2/query?q=rabbits&limit=10&apikey=YOUR_API_KEY &filters=\"source.countries.name\"=\"Canada\" &filters=\"source.langs.id\"=\"FR\""

This request:

  • searches for datasets matching the term rabbits
  • restricts results to catalogs associated with Canada
  • restricts results to French-language datasets

Notes​

  • Filters apply only to search endpoints
  • Dataset cards retrieved via /raw/0.1/entry/{entry_id} do not support filtering
  • Field names used in filters must match the descriptor JSON structure exactly