All APIs which return potentially a lot of records offer the possibility to page and filter the data. For big result sets paging is essential since the server disconnects long running calls after 3 minutes for the sake of system stability.
Filtering
A filter consists of the following components:
Conjunction
- And
- Or
Since the filter doesn’t support brackets, repeat all And filters after an Or filter.
ConditionType
- Question
- CustomVariable
- UrlVariable
- Panel (Also used for Sample)
- SQL
ConditionOperator
- IsLessThan
- IsLessThanOrEqualTo
- IsGreaterThan
- IsGreaterThanOrEqualTo
- IsEqualTo
- IsNotEqualTo
- IsEmpty
- IsNotEmpty
- Contains
- DoesNotContain
- MatchRegex
- DoesNotMatchRegex
- AnyIsEqual
- AnyIsNotEqual
- AnyIsEmpty
- AnyIsNotEmpty
- AnyMatchRegex
- AnyDoesNotMatchRegex
Identifier
- For member variables uses member. as prefix
- For custom variables use custom. as prefix
- In conjunction with SQL the following identifiers could be used
- Id
- DistributorId
- SamplingProjectId
- PanelId
- PanelMemberId
- Language
- StartDate
- EndDate
- Link
- State
- Mode
- ExpiryDate
- CreatedAt
- CreatedBy
- UpdatedAt
- UpdatedBy
Value
- Provide the value of the filter
- In case of date use “yyyy-mm-dd”
- In case of a timestamp use “yyyy-mm-dd hh:mm:ss.fff” where ss and fff are optional
- All timestamps need to be UTC
- For all “Any” ConditionOperators use , to separate multiple values
The following examples show common use cases.
Case 1: Receive Completes since last request (simply delta load of new completes)
"conditions": [{
"conjunction": "And",
"identifier": "State",
"conditionOperator": "IsEqualTo",
"value": "Completed",
"conditionType": "SQL"
},{
"conjunction": "And",
"identifier": "EndDate",
"conditionOperator": "IsGreaterThanOrEqualTo",
"value": "2022-01-01", //value of the last day
"conditionType": "SQL",
},{
"conjunction": "And",
"identifier": "EndDate",
"conditionOperator": "IsLessThan",
"value": "2022-01-02", //value of the current day
"conditionType": "SQL",
}]Case 2: Receive all changes since last request (advanced delta load of all changes)
"conditions": [{
"conjunction": "And",
"identifier": "CreatedAt",
"conditionOperator": "IsGreaterThanOrEqualTo",
"value": "2022-01-01 16:00:00", //Value of last call
"conditionType": "SQL"
},{
"conjunction": "And",
"identifier": "CreatedAt",
"conditionOperator": "IsLessThan",
"value": "2022-01-01 17:00:00", //value of current call
"conditionType": "SQL",
},{
"conjunction": "Or",
"identifier": "UpdatedAt",
"conditionOperator": "IsGreaterThanOrEqualTo",
"value": "2022-01-01 16:00:00", //Value of last call
"conditionType": "SQL"
},{
"conjunction": "And",
"identifier": "UpdatedAt",
"conditionOperator": "IsLessThan",
"value": "2022-01-01 17:00:00", //value of current call
"conditionType": "SQL",
}]For large scale surveys it’s essential to not load each tie the full set of data but get only the delta since the last call. Generally the received data should never exceed 10k records. If more is expected the usage of paging is crucial.
Paging
The paging object consists of 4 properties:
- PageSize
- Page
- OrderField
- OrderDirection (Ascending, Descending)
Example
"paging": {
"pageSize": 10000,
"page": 1,
"orderField": "Id",
"orderDirection": "Ascending"
}The result collection always has a property TotalRows which allows to calculate the amount of pages.1
var pages = Math.ceil(TotalRows / PageSize);