This REST service provides query capabilities that range from the retrieval of data aggregate or summary computations, geographic location values, multimedia files as well as other alphanumeric data fields of forms. These queries can also be filtered to restrict returned data sets to those that fit within constraints of certain form entries. The code blocks on this page are used to describe the processes associated with querying data. Note that it is assumed that the REST client is already authenticated and in possession of a valid session ID.

Please select the preferred scripting/programming language for the examples presented in the drop down box below.

Forms IDs

To retrieve the identities of forms with data that can be queried, format and send a request analogous to that shown in the Form IDs Request code block.

If non-empty forms exist, then their names and identities are returned in a JSON structure similar to that shown in the Form IDs Response code block.

Form Definition

The definition for forms with data can be retrieved using the format typified by the Form Defs Request code block. See the Form Defs Response for the format of the returned data.

REST Data Query Format

A query request must align with the fields present on the form(s) being queried, as well as conform to a specific structure. Even though the query language is very simple, ccasystem.io provides a menu button that automatically generates valid queries when clicked. When using any of the items under the Data Analysis menu, select the applicable form fields and, optionally, set the data filter as would have been done when analyzing data on the CCA System. Find and click the Show Query Code menu text/button. This action will generate a valid JSON query acceptable to this REST service as highlighted in the image above.

A valid query is a JSON object that consists of one or more of the following properties; primaryFormID, querySelect, queryGroupBy, queryDelete and queryFilters.

Data Query I

The example presented in this section is based on the City Census form discussed in Walkthrough I. It assumes that the rest client wants to retrieve the population count in 1950, 2000 and expected population count in 2050, as well as the GPS location for the city of Paris. Examine the queryString JSON object in the Data Query Request I code block to see how this query is formatted.

The data returned based on this request is shown in Data Query Response I. The queryData JSON object includes the actual data returned i.e., dataDump, as well as a dataSchema property which is the JSON v4 schema that describes the contents of the dataDump object.

Data Query II (Aggregates/Summaries)

The query presented in this section requires the mathematical calculations of fields of the City Census form before they are returned. In this example, the average population of all cities in France and Germany in 1950 is requested. The returned data is to be grouped by the country name. See the Data Query Request II code block for the format of this query.

The response to the query discussed previously is shown in the Data Query Response II code block.

Data Query III (Pagination)

For large datasets, data can be retrieved in small sequential subsets using the Pagination mechanism provided by the API. Please note that Pagination cannot be used with aggregation queries, i.e., queries that involve averages, maximums, minimums, variance and standard deviations. To enable Pagination two query fields are required, i.e., queryID and queryPage.

The queryID contains a unique string that identifies the query. The queryPage contains an integer value corresponding to the data page to be retrieved. The queryPage value must begin at 1 and be monotonically increased by 1 for subsequent requests, i.e., 1, 2, 3, 4, 5 etc. Note that for a specific query, the queryID string must remain the same even as the queryPage value changes. Also note that if the queryPage sequence value is skipped an error would be returned. For example, if the last data page queried is 2 and the next queryPage value is set to 4 instead of 3 an error is returned.

The Data Query Request III and Data Query Response III shown below demonstrate an example of a paginated query and the query data returned.

Data Query IV (Multimedia Files)

Finally, to demonstrate the retrieval of form fields that have as inputs multimedia files, the M and E form presented in Walkthrough II is used. The query in this example is asking for the photos of the signboards of all building with exactly three defects. See the Data Query Request IV code block for the format of this query.

The REST service returns the URLs of all images of signboards that satisfy the query constraints. In addition to the URL returned, notice the value of the urlTTLSec parameter value. This value specifies the time, in seconds, for which the URL is valid. After this time interval, the URL is unusable.