Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The /table endpoint allows you to submit table queries and receive the results.

Overview

Endpoint
http://<server>/webapi/rest/v1/table
HTTP MethodPOST

Request Headers

Excerpt Include
Reference - Open Data API
Reference - Open Data API
nopaneltrue

Content-Type
Must be set to application/json.Required in all requests.

...

ObjectReturns
query

The query that was submitted. This object contains the databasemeasuresrecodes, and dimensions objects from your query.

The recodes object is returned in the response even if you did not include it in the query, or did not specify recodes for all fields. The response will contain the full list of returned field values for any fields that were not recoded in the original request. This allows you to use the recodes object in the response to determine what the returned cell values represent.

For example, the above sample query requests a table containing Marital Status and Gender, but only specifies a recode for the Marital Status field. The recodes object in the response would therefore include all field values for Gender, as well as the two specified field values for Marital Status.

database

Details of the dataset that was queried:

id
The SuperADMIN ID of this dataset
annotationKeys
An array of keys to annotations for this dataset. If any annotations are available, their descriptions will be returned in the annotationMap object.
fields

Details of the fields that were queried:

uri
The Open Data ID of this field. This matches the ID format this is returned by the /schema endpoint.
label
The display name for this field. This is the label that is displayed in SuperWEB2. If the dataset is available in multiple languages, then the label will be returned in the language you specified in the Accept-Language header.
items

An array containing all the field values returned for this field:

type
The field type (RecodeItem).
labels
The display name(s) for this field item. In most cases there will be a single label. However, if you have used the recodes in the query to combine multiple field items into a single value, then this will contain the labels of each constituent field value.
annotationKeys
An array of keys to annotations for this field item (or these field items, if you have combined multiple field items into a single value). If any annotations are available, their descriptions will be returned in the annotationMap object.
uris
The Open Data ID of this field item (or these field items, if you have combined multiple field items into a single value). This matches the ID format this is returned by the /schema endpoint.
annotationKeys
An array of keys to annotations for this field. If any annotations are available, their descriptions will be returned in the annotationMap object.
measures

An array containing all the measures (summation options) returned for this query. For each measure, the API returns:

uri
The Open Data ID of this measure. This matches the ID format this is returned by the /schema endpoint.
label
The display name for this measure. This is the label that is displayed in SuperWEB2. If the dataset is available in multiple languages, then the label will be returned in the language you specified in the Accept-Language header.
cubes

An array containing the results of the query.

There will be one item in this array for each measure you requested.

Each item specifies the measure, and then provides the values for each cell in the cube for that measure.

This will contain both the values returned by the tabulation as well as the recommended precision for those values.

For example:

Code Block
"cubes": {
    "<measure>": {
      "values": [ ... ],
      "precision": <precision>
    },
    "<measure>" {
      ...
    }
}
Info
iconfalse

Please note that the API returns the full (unrounded) results of the tabulation, at the maximum available precision provided by the server. This is so that your application can perform any additional calculations without introducing rounding errors.

The precision value that is returned tells you the recommended number of decimal places that have been set by the system administrator for this measure in the display options catalog. If you want your application to match the values shown in SuperWEB2, then you should use the precision value to round the results accordingly before displaying them.

annotationMap
Any annotations that apply to this query. If there are annotations for the dataset or its fields, then the annotation keys and descriptions will be returned in this object.

...