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/{handle}/variables/{variable name}

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.

In cURL add a header to change content type:

-H "Accept: application/json"
-H "Accept: application/xml"

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;


Performs a query across variables or codebooks

Required Parameter

Specifies which category to search. Options are as follows:

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



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.



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.


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.


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.


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


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


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


Provides information on a specific study


Returns DDI varGrp classification associated with the codebook


Returns specific vargroup


Returns all variables in a specific vargroup


Returns a detailed list of all variables in a codebook.


Returns information on a specific variable

Example Queries

Simple Search Example 1
curl -v /ced2ar-web/rest/search?return=variables&where=variablename=a*&sort=+variablename


  • Return variables
  • Where variable name starts with "a"
  • Sort by variable name in ascending order
Simple Search Example 2
curl -v /ced2ar-web/rest/search?return=variables&where=allfields=war&sort=+variablename


  • Return variables
  • And where any of the fields contains "war"
  • Sort by variable name in ascending order
Advanced Search Example
curl -v /ced2ar-web/rest/search?return=variables& where=allfields=money,variablename=payment|variablename!=debt&sort=+variablename,-codebookid&limit=100


  • 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