API Guide

If you are a developer and would like to incorporate our API into your application, please contact us for more information.

Current URIs

The API focuses on both exposing the full codebook data in the underlying database, and filtering that data based on user input. The following endpoints are currently available:

/ced2ar-web/rest/codebooks
/ced2ar-web/rest/codebooks/{handle}
/ced2ar-web/rest/codebooks/{handle}/docdesc
/ced2ar-web/rest/codebooks/{handle}/filedesc
/ced2ar-web/rest/codebooks/{handle}/studydesc
/ced2ar-web/rest/codebooks/{handle}/vargroups
/ced2ar-web/rest/codebooks/{handle}/vargroups/{vargroupID}
/ced2ar-web/rest/codebooks/{handle}/vargroups/{vargroupID}/vars
/ced2ar-web/rest/codebooks/{handle}/variables
/ced2ar-web/rest/codebooks/{handle}/variables/{variable name}
/ced2ar-web/rest/search

Accessing the API

The API is open to use - no registration required. All resources are read only.

Available Content Types

Resources are available in XML and JSON. By default, XML is returned.

Example
In cURL add a header to change content type:

For endpoints that return variables, a minified representation can also be returned. Adding the header partial-text, and setting the value to true will strip out many of the DDI wrappings.

Variable resources can also be requested in CSV format (text/csv). CSV is only returned if partial-text is set to true. The format of the csv is variable name, variable label, codebook;

/search

Performs a query across variables or codebooks

Required Parameter

return
Specifies which category to search. Options are as follows:

• variables - variables found within all codebooks
• codebooks - a list of all codebooks

Examples

Optional Parameters

where- Provides filtering criterion. Syntax for the operators includes:

• , and
• | or
• = equals
• != does not equal
• < less than
• > greater than
• * wildcard
• art contains art
• *art ends with art
• art* starts with art
• ar*t invalid, wildcard selector must be used at the end and/or beginning of phrase

Phrases can be compared with the syntax against a specific field or every field. To compare against every field, use the keyword allfields.

For variables, the following fields can be used:

• variablename - The name of the variable as shown in its codebook.
• variablelabel - A short description of a variable
• variabletext - A full description of a variable
• variablecodeinstructions - Coder instructions
• variableconcept - A high level concept which the variable belongs to
• codebooktitle - The name of the codebook which the variable is in
• productdate -The date the codebook was released
• id -The ID attribute of a variable. May be null.

For codebooks only codebooktitle is valid.

sort - Arranges results by field. A prefix of + or - specifies ascending or descending respectively. By default, sorting is in ascending order. For variables, the following fields can be sorted:

• variablename
• variablelabel
• variabletext
• variablecodeinstructions
• variableconcept
• codebooktitle

Sorting is not available for codebooks.

Example

limit - Filters the number of results returned. Syntax is either a single number to specify a maximum number of results, or a range to specify a subset of results.

Example - Return the first 100 variables

Example - Return variables 10 through 20.

Note the start point cannot be greater than the endpoint. limit=30-20 is invalid.

Headers

When returning variables for the search endpoint, the API will return a counter header. This is the total number of matching results available without the limit parameter applied.

/ced2ar-web/rest/codebooks

Returns a list of all codebooks. This endpoint return CSV with semicolons denoting linebreaks, or space separated values. For this endpoint the header id-type can be used to specify how the list is formated. Acceptable values for this header are all, access, sn, fn and no value.
All returns the file handle, short name and title in CSV. Access returns the same fields, plus the available access levels. SN return the shortnames, fn returns the file/handle names, and a null value returns the title names. Those last three are in space separated format.

/ced2ar-web/rest/codebooks/{handle}

Returns detailed information a on specific codebook, where {handle} is the name of the codebook.

/ced2ar-web/rest/codebooks/{handle}/docdesc

Provides detailed information in docDscr element of a codebook, such as production, contact and title information.

/ced2ar-web/rest/codebooks/{handle}/filedesc

Provides detailed information on file that the specific codebook is stored in.

/ced2ar-web/rest/codebooks/{handle}/studydesc

Provides information on a specific study

/ced2ar-web/rest/codebooks/{handle}/vargroups

Returns DDI varGrp classification associated with the codebook

/ced2ar-web/rest/codebooks/{handle}/vargroups/{vargroupID}

Returns specific vargroup

/ced2ar-web/rest/codebooks/{handle}/vargroups/{vargroupID}/vars

Returns all variables in a specific vargroup

/ced2ar-web/rest/codebooks/{handle}/variables

Returns a detailed list of all variables in a codebook.

/ced2ar-web/rest/codebooks/{handle}/variables/{variableId}

Returns information on a specific variable

Example Queries

Simple Search Example 1

Explanation

• Return variables
• Where variable name starts with "a"
• Sort by variable name in ascending order

Simple Search Example 2

Explanation

• Return variables
• And where any of the fields contains "war"
• Sort by variable name in ascending order

Advanced Search Example

Explanation

• Return variables
• Where any supported field contains war
• And variable name equals payment
• Or variable name is not equal to debt
• Sort by variable name in ascending order, then by codebook id in descending order
• Limit results to top 100