Implementation in web surveys (CAWI mode)

There are four modes of data retrieval. Each mode is used in different situations. You can view a complete example when inspecting the html and javascript code on the Database live search pages throughout this website.

Good to know

  • Each mode has a specific set of combination of options. Please see the description of each mode below for the correct options.
  • Always tell the API what database to use. This is done with the type argument. See below for details.
  • The API is returns all data in JSON format. 
    The first argument starts with a question mark ?, the following arguments start with &. See the examples on how to write a complete URL correctly.

Common arguments

Argument  Options Description Example
type education
occupation
industry
Tells the API in which database to search the codings. There are three different databases with codings. With argument type=[database] you can tell the API which database to use. Always use this argument.

type=education
type=occupation
type=industry

mode country
search
tree
coding
Tells the API what to do.

mode=country
mode=search
mode=tree
mode=coding

Mode 1: List of countries

Tell the API to return a JSON format of all countries in the education database that have codings. The arguments type and mode are used to retrieve the requested data. See the above section on what they do.

Example: https://api.surveycodings.org/codings/search.json?type=education&mode=country

Argument  Options Description Example
mode country The above URL tells the API to return a JSON format of all countries.

mode=country

    Mode 2: Search (used in autocomplete)

    Tell the API to return a JSON list of all codings for a specific context where the description matches a given search string.

    Example education database: 
    https://api.surveycodings.org/codings/search.json?type=education&mode=search&context=52800&search=pr

    Example occupation/industry database:
    https://api.surveycodings.org/codings/search.json?type=occupation&mode=search&context=en_GB&search=pr
    https://api.surveycodings.org/codings/search.json?type=industry&mode=search&context=en_GB&search=pr

      Argument  Options Description Example
      mode search Tells the API to search for codings based on a text search. mode=search
      context [integer] or [string]

      This tells the database in which context to look for codings. The context for education is an integer. The context for industry and occupation are strings. 

      Example education: context=52800 Dutch codings. 
      Example occupation: context=nl_NL Dutch codings. 
      Example industry: context=nl_NL Dutch codings. 
      search [string] A string that will be broken down into parts. Any (partially) match on any parts will return results. Multiple parts are allowed. For example 'search=a b' will return all results with either an 'a' or 'b' in it.

      search=tea
      search=any string

      Mode 3: Tree view

      Tell the API to return a JSON tree representation of all codings for a specific context.

      Example education database: 
      https://api.surveycodings.org/codings/search.json?type=education&mode=tree&context=52800

      Example occupation/industry database:
      https://api.surveycodings.org/codings/search.json?type=occupation&mode=tree&context=nl_NL
      https://api.surveycodings.org/codings/search.json?type=industry&mode=tree&context=nl_NL

        Argument  Options Description Example
        mode tree Tells the API to return a full tree of all codings. mode=tree
        context [integer] or [string]

        This tells the database in which context to look for codings. The context for education is an integer. The context for industry and occupation are strings. 

        Example education: context=52800 Dutch codings. 
        Example occupation: context=nl_NL Dutch codings. 
        Example industry: context=nl_NL Dutch codings. 

        Mode 4: Retrieving data of specific coding

        Tell the API to return detailed data about the requested coding.

        https://api.surveycodings.org/codings/search.json?type=education&mode=coding&coding=52800079

        Returns an empty set if 

          Argument  Options Description Example
          mode coding Tells the API to return the details of a specific coding. mode=coding
          coding [integer] 

          Tells the database which coding is requested. This is the name of the coding. 

          coding=52800079