Making Search Queries
GET requests for searching resources (series, cases, jobs, etc.) accept shared query parameters. This page explains how to form search requests for CIRCUS API.
Query Parameters#
These are specified as URL query parameters (e.g., ?limit=10&page=2). Special characters must be URL-encoded.
filter(string)- Specifies the search criterion in JSON string. See Forming Filters and Available Filters.
sort(string)- Sort order of search results, in JSON string. A value of 1 means ascending and -1 means descending. The default is
{ createdAt: -1 }. limit(number)- Number of search results per page.
page(number)- Page number starting from 1.
Example#
Example Request
GET /api/cases?filter=<filter>&sort=<sort>&page=1&limit=20 HTTP/1.1Assign URL-encoded JSON to <filter> and <sort> respectively.
Example 'filter' before URL-encoding
{
"$and": [
{ "patientInfo.age": { "$gt": 50 } },
{ "patientInfo.age": { "$lte": 70 } },
{ "patientInfo.sex": "M" },
{ "createdAt": { "$gt": { "$date": "2023-01-10" } } },
{ "createdAt": { "$lte": { "$date": "2023-02-20" } } }
]
}Example 'sort' before URL-encoding
{
"projectId": -1
}Forming Filters#
The format of filters accepted by CIRCUS API is basically a small subset of MongoDB filters.
Comparison Operators#
$gt- Matches values greater than the specified value.
$gte- Matches values that are greater than or equal to the specified value.
$lt- Matches values that are less than the specified value.
$lte- Matches values that are less than or equal to the specified value.
$ne- Matches all values that are not equal to the specified value.
$in- Matches any of the values specified in the array.
$all- Matches arrays that contain all elements specified in the query.
Logical Operators#
$and- Joins query clauses with a logical AND.
$or- Joins query clauses with a logical OR.
Example#
This filter is used to search for cases of men aged ≥ 50, created between 10 January 2023 and 20 february 2023 (UTC).
{
"$and": [
{ "patientInfo.age": { "$gte": 50 } },
{ "patientInfo.sex": "M" },
{ "createdAt": { "$gte": { "$date": "2023-01-10T00:00:00.000Z" } } },
{ "createdAt": { "$lt": { "$date": "2023-02-21T00:00:00.000Z" } } }
]
}URL-encode the above filter and assign it to <filter>.
GET /api/cases?filter=<filter> HTTP/1.1Available Filter Keys#
Different filters are available for different search targets.
searching Targets#
Cases, Series, Plugin-jobs