Version 3 (categorical & numerical types) - Dataset Codebook

Released At: 25 Jan 2016Last Updated At: 26 Jan 2016

Get the codebook for a dataset.

URL

To call this method, use an HTTP GET request to the following URL:

http://data.unicef.ge/[locale]/api/v2/dataset_codebook

where:

  • [locale] = the locale of the language you want the data to be returned in (currently ka for Georgian or en for English)

Required Parameters

The following parameters must be included in the request:

ParameterDescription
access_token All requests must include an access_token. You can obtain an access token easily, and for free, by going here.
dataset_id The ID of the dataset.

Optional Parameters

There following parameters are optional for this call.

ParameterDescription
language Code of the language to return the dataset information in (e.g., en for English). If language is not provided, the default language of the dataset will be used.

What You Get

The return object is a JSON object of the dataset and it's questions and answers with the following information:

ParameterDescription
id Unique ID of the dataset
url URL to the dataset
title The title of the dataset
description A description of the dataset, may include html markup
source The name of the source that gathered the data
weights

An array of weights with the following information:

  • name - the name of the weight
  • is_default - a boolean flag indicating if this is the default weight for the dataset
  • applies_to_all - a boolean flag indicating if the weight applies to all questions in the dataset
  • codes - if applies_to_all is false, then this contains a list of all question codes that the weight applies to
items

An array of groups and questions. Groups have the following information:

  • title - the title of the group
  • description - a description of the group
  • items - an array of questions and groups that are in this group

Questions have the following information:

  • code - code of the question; you will use this value to run an analysis
  • original_code - the original code from the dataset; the difference between the code and original_code is that the code is lower case and has '.' replaced with '|'
  • text - the question text
  • notes - any special notes about the question
  • is_mappable - a boolean flag indicating if this question has been assigned to map shapes
  • answers - An array of the possible answers with the following values:
    • value - the answer value
    • text - the answer text
    • can_exclude - boolean flag indicating if this answer can be excluded from analysis
    • sort_order - order in which the answer should appear

Examples

Here is an example of what can be returned after calling this method with the following url:

http://data.unicef.ge/en/api/v2/dataset_codebook?access_token=123456789&dataset_id=1111111111
{
  id: "1111111111",
  url: "http://data.unicef.ge/en/datasets/dataset1",
  title: "This is a dataset!",
  description: "This is the description of the dataset.",
  source: "People",
  weights: [
    {
      name: "Individual Weight",
      is_default: true,
      applies_to_all: true,
      codes: []
    }
  ],
  items: [
    {
      group: {
        title: "Group 1",
        description: "This is a description of Group 1",
        items: [
          {
            question: {
              code: "gender",
              original_code: "GENDER",
              text: "What is your gender?",
              notes: null,
              is_mappable: false,
              answers:[
                {
                  value: "1",
                  text: "Male",
                  can_exclude: false,
                  sort_order: 1
                },
                {
                  value: "2",
                  text: "Female",
                  can_exclude: false,
                  sort_order: 2
                },
                {
                  value: "3",
                  text: "Refuse to Answer",
                  can_exclude: true,
                  sort_order: 3
                }
              ]
            }
          },
          {
            question: {
              code: "age",
              original_code: "AGE",
              text: "What is your age?",
              is_mappable: false,
              answers:[
                {
                  value: "1",
                  text: "< 18",
                  can_exclude: false,
                  sort_order: 1
                },
                {
                  value: "2",
                  text: "18-65",
                  can_exclude: false,
                  sort_order: 2
                },
                {
                  value: "3",
                  text: "> 65",
                  can_exclude: false,
                  sort_order: 3
                }
              ]
            }
          }
        ]
      }
    },
    {
      question: {
        code: "live",
        original_code: "LIVE",
        text: "Where do you live?",
        is_mappable: false,
        answers:[
          {
            value: "1",
            text: "Tbilisi",
            can_exclude: false,
            sort_order: 1
          },
          {
            value: "2",
            text: "London",
            can_exclude: false,
            sort_order: 2
          },
          {
            value: "3",
            text: "New York City",
            can_exclude: false,
            sort_order: 3
          }
        ]
      }
    }
  ]
}