API Home

Version 2 (groups & weights) - Dataset Analysis

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

Analyze data in a dataset. The dataset explore pages in this website use this API method to get the results of the analysis.

URL

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

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

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.
question_code The code of a question in 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.
broken_down_by_code Code of question to compare against question_code (i.e., a crosstab analysis)
filtered_by_code Code of question to filter the analysis by
weighted_by_code Code of question to weight the analysis by. If no value is given and the dataset has a default weight, the weight will automatically be used. If you want an unweighted analysis, use the value 'unweighted'.
can_exclude Boolean flag indicating if answers that can be excluded should be excluded (default value is false). Example of excluded answers are 'Do not know' and 'Refuse to answer'.
with_title Boolean flag indicating if titles summarizing the data should be included (default value is false)
with_chart_data Boolean flag indicating if the results should include data formatted for a Highcharts chart (default value is false)
with_map_data Boolean flag indicating if the results should include data formatted for a Highmaps map (default value is false)

What You Get

The return object is a JSON object of the dataset analysis with the following information:

ParameterDescription
dataset

An object with the following values:

  • id - the ID of the dataset that was analyzed
  • title - the title of the dataset that was analyzed
question

An object with the following values:

  • code - the code of the question that was analyzed
  • original_code - the original code of the question that was analyzed; the difference between the code and original_code is that the code is lower case and has '.' replaced with '|'
  • text - the text of the question that was analyzed
  • notes - any special notes about the question
  • is_mappable - a boolean flag indicating if this question has been assigned to map shapes
  • has_map_adjustable_max_range - a boolean flag indicating if the choropleth map range should be from 0 to 100% (a false value) or 0 to whatever the max value of the data is (a true value)
  • answers - an array of the following information:
    • 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
broken_down_by

Only if broken_down_by_code was provided. An object with the following values:

  • code - the code of the question that was analyzed
  • original_code - the original code of the question that was analyzed; the difference between the code and original_code is that the code is lower case and has '.' replaced with '|'
  • text - the text of the question that was analyzed
  • notes - any special notes about the question
  • is_mappable - a boolean flag indicating if this question has been assigned to map shapes
  • has_map_adjustable_max_range - a boolean flag indicating if the choropleth map range should be from 0 to 100% (a false value) or 0 to whatever the max value of the data is (a true value)
  • answers - an array of the following information:
    • 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
filtered_by

Only if filtered_by_code was provided. An object with the following values:

  • code - the code of the question that was analyzed
  • original_code - the original code of the question that was analyzed; the difference between the code and original_code is that the code is lower case and has '.' replaced with '|'
  • text - the text of the question that was analyzed
  • notes - any special notes about the question
  • is_mappable - a boolean flag indicating if this question has been assigned to map shapes
  • has_map_adjustable_max_range - a boolean flag indicating if the choropleth map range should be from 0 to 100% (a false value) or 0 to whatever the max value of the data is (a true value)
  • answers - an array of the following information:
    • 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
weighted_by

Only if weighted_by_code we provided or the dataset has a default weight and no weight was provided. An object with the following values:

  • weight_name - the name of the weight (i.e., Individual)
  • code - the code of the question
  • original_code - the original code of the question; the difference between the code and original_code is that the code is lower case and has '.' replaced with '|'
  • text - the text of the question
  • notes - any special notes about the question
analysis_type

Indicates what type of analysis was performed:

  • single - a summary of the question_code was created
  • comparative - a summary of question_code compared against broken_down_by_code was created
results

An object containing the results of the analysis with the following information:

  • total_responses - number indicating how many people responded to this question
  • total_possible_responses - number indicating how many total responses are in the dataset
  • analysis - an array of results for each answer in the question with the following information:
    • answer_value - the value of the answer
    • answer_text - the text of the answer
    • count - the number of people that had this answer (if analysis is not weighted)
    • percent - the percent of people with answer compared to the total responses (if analysis is not weighted)
    • unweighted_count - the number of people that had this answer (if analysis is weighted)
    • weighted_count - the weighted number of people that had this answer (if analysis is weighted)
    • weighted_percent - the weighted percent of people with answer compared to the weighted total responses (if analysis is weighted)

If broken_down_by_code was provided, the analysis results will have the following information:

  • total_responses - number indicating how many people responded to both questions
  • total_possible_responses - number indicating how many total responses are in the dataset
  • analysis - an array of results for each answer in the question and each answer in the broken down by question with the following information:
    • answer_value - the value of the answer from the question
    • answer_text - the text of the answer from the question
    • broken_down_results - an array of results for each answer in the broken down by question with the following information:
      • broken_down_answer_value - the value of the answer from the broken down by question
      • broken_down_answer_text - the text of the answer from the broken down by question
      • count - the number of people that had both the question answer and the broken down by answer (if analysis is not weighted)
      • percent - the percent of people that had both the question answer and the broken down by answer compared to the total responses (if analysis is not weighted)
      • unweighted_count - the number of people that had both the question answer and the broken down by answer (if analysis is weighted)
      • weighted_count - the weighted number of people that had both the question answer and the broken down by answer (if analysis is weighted)
      • weighted_percent - the weighted percent of people that had both the question answer and the broken down by answer compared to the weighted total responses (if analysis is weighted)

If filtered_by_code was provided, the analysis results will have the following information:

  • filtered_analysis - an array of results grouped by each answer in the filter question with the following information:
    • filter_answer_value - the value of the answer from the filtered by question
    • filter_answer_text - the text of the answer from the filtered by question
    • filter_results - an array of results for each answer in the question that also responded with the filtered by answer with the following information:
      • total_responses - number indicating how many people responded to this question and also responded with the filtered by answer
      • total_possible_responses - number indicating how many total responses are in the dataset
      • analysis - an array of results for each answer in the question with the following information:
        • answer_value - the value of the answer from the question
        • answer_text - the text of the answer from the question
        • count - the number of people that had both the filtered by answer and the question answer (if analysis is not weighted)
        • percent - the percent of people that had both the filtered by answer and the question answer compared to the total responses (if analysis is not weighted)
        • unweighted_count - the number of people that had both the filtered by answer and the question answer (if analysis is weighted)
        • weighted_count - the weighted number of people that had both the filtered by answer and the question answer (if analysis is weighted)
        • weighted_percent - the weighted percent of people that had both the filtered by answer and the question answer compared to the weighted total responses (if analysis is weighted)

If broken_down_by_code and filtered_by_code were provided, the analysis results will have the following information:

  • filtered_analysis - an array of results grouped by each answer in the filter question with the following information:
    • filter_answer_value - the value of the answer from the filtered by question
    • filter_answer_text - the text of the answer from the filtered by question
    • filter_results - an array of results for each answer in the question that also responded with the filtered by answer with the following information:
      • total_responses - number indicating how many people responded to this question and also responded with the filtered by answer
      • analysis - an array of results for each answer in the question with the following information:
        • answer_value - the value of the answer from the question
        • answer_text - the text of the answer from the question
        • broken_down_results - an array of results for each answer in the broken down by question with the following information:
          • broken_down_answer_value - the value of the answer from the broken down by question
          • broken_down_answer_text - the text of the answer from the broken down by question
          • count - the number of people that had the filtered by answer, the question answer and the broken down by answer (if analysis is not weighted)
          • percent - the percent of people that had the filtered by answer, the question answer and the broken down by answer compared to the total responses (if analysis is not weighted)
          • unweighted_count - the number of people that had the filtered by answer, the question answer and the broken down by answer (if analysis is weighted)
          • weighted_count - the weighted number of people that had the filtered by answer, the question answer and the broken down by answer (if analysis is weighted)
          • weighted_percent - the weighted percent of people that had the filtered by answer, the question answer and the broken down by answer compared to the weighted total responses (if analysis is weighted)
chart

Only if with_chart_data was true. An object with the following values:

  • embed_id - unique ID that can be used to embed this chart on a web page by using the url: http://data.unicef.ge/en/embed/v1/embed_id, where embed_id is the unique ID
  • data - an array of data points with the following information:
    • name - the answer_text value from the results
    • y - the percent value from the results (if analysis is weighted, this is the weighted_percent, else the percent for unweighted analysis)
    • count - the count value from the results (if analysis is weighted, this is the weighted_count, else the count for unweighted analysis)
    • answer_value - the answer_value from the results
map

Only if with_map_data was true. An object with the following values:

  • shape_question_code - indicates the code of the questions that is being mapped
  • map_sets - an object with the following values:
    • embed_id - unique ID that can be used to embed this map on a web page by using the url: http://data.unicef.ge/en/embed/v1/embed_id, where embed_id is the unique ID
    • data - an array of data points for each shape with the following information:
      • shape_name - the name of the shape in the geojson file that is used to match the data to the correct shape
      • display_name - the name of the shape to display when the user hovers over the shape
      • value - the percent value from the results (if analysis is weighted, this is the weighted_percent, else the percent for unweighted analysis)
      • count - the count value from the results (if analysis is weighted, this is the weighted_count, else the count for unweighted analysis)

Examples

Example 1

Here is an example of analyzing the results of Gender with the following url:

http://data.unicef.ge/en/api/v2/dataset_analysis?access_token=123456789&dataset_id=1111111111&question_code=gender
{
  dataset: 
  {
    id: "1111111111",
    title: "This is a dataset!"
  },
  question: 
  {
    code: "gender",
    original_code: "GENDER",
    text: "What is your gender?",
    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
      }
    ]
  },
  analysis_type: "single",
  results:
  {
    total_responses: 234,
    analysis: [
      {
        answer_value: '1',
        answer_text: 'Male',
        count: 134,
        percent: 57.26
      },
      {
        answer_value: '2',
        answer_text: 'Female',
        count: 98,
        percent: 41.88
      },
      {
        answer_value: '3',
        answer_text: 'Refuse to Answer',
        count: 2,
        percent: 0.85
      }
    ]
  }
}

Example 2

Here is an example of analyzing the results of Gender, broken down by Live:

http://data.unicef.ge/en/api/v2/dataset_analysis?access_token=123456789&dataset_id=1111111111&question_code=gender&broken_down_by_code=live
{
  dataset: 
  {
    id: "1111111111",
    title: "This is a dataset!"
  },
  question: 
  {
    code: "gender",
    original_code: "GENDER",
    text: "What is your gender?",
    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
      }
    ]
  },
  broken_down_by: 
  {
    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
      }
    ]
  },
  analysis_type: "comparative",
  results:
  {
    total_responses: 234,
    analysis: [
      {
        answer_value: '1',
        answer_text: 'Male',
        broken_down_results: [
          {
            broken_down_answer_value: '1',
            broken_down_answer_text: 'Tbilisi',
            count: 30,
            percent: 22.39
          },
          {
            broken_down_answer_value: '2',
            broken_down_answer_text: 'London',
            count: 40,
            percent: 29.85
          },
          {
            broken_down_answer_value: '3',
            broken_down_answer_text: 'New York City',
            count: 64,
            percent: 47.76
          }
        ]
      },
      {
        answer_value: '2',
        answer_text: 'Female',
        broken_down_results: [
          {
            broken_down_answer_value: '1',
            broken_down_answer_text: 'Tbilisi',
            count: 18,
            percent: 18.37
          },
          {
            broken_down_answer_value: '2',
            broken_down_answer_text: 'London',
            count: 35,
            percent: 35.71
          },
          {
            broken_down_answer_value: '3',
            broken_down_answer_text: 'New York City',
            count: 45,
            percent: 45.92
          }
        ]
      },
      {
        answer_value: '3',
        answer_text: 'Refuse to Answer',
        broken_down_results: [
          {
            broken_down_answer_value: '1',
            broken_down_answer_text: 'Tbilisi',
            count: 0,
            percent: 0
          },
          {
            broken_down_answer_value: '2',
            broken_down_answer_text: 'London',
            count: 0,
            percent: 0
          },
          {
            broken_down_answer_value: '3',
            broken_down_answer_text: 'New York City',
            count: 2,
            percent: 100
          }
        ]
      }
    ]
  }
}

Example 3

Here is an example of analyzing the results of Gender, filtered by Age:

http://data.unicef.ge/en/api/v2/dataset_analysis?access_token=123456789&dataset_id=1111111111&question_code=gender&filtered_by_code=age
{
  dataset: 
  {
    id: "1111111111",
    title: "This is a dataset!"
  },
  question: 
  {
    code: "gender",
    original_code: "GENDER",
    text: "What is your gender?",
    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
      }
    ]
  },
  filtered_by:
  {
    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
      }
    ]
  }
  analysis_type: "single",
  results:
  {
    filter_analysis: [
      {
        filter_answer_value: '1',
        fitler_answer_text: '< 18',
        filter_results: {
          total_responses: 23,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              count: 15,
              percent: 65.22
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              count: 8,
              percent: 34.78
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              count: 0,
              percent: 0
            }
          ]
        }
      },
      {
        filter_answer_value: '2',
        fitler_answer_text: '18-65',
        filter_results: {
          total_responses: 196,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              count: 100,
              percent: 51.02
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              count: 94,
              percent: 47.96
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              count: 2,
              percent: 1.02
            }
          ]
        }
      },
      {
        filter_answer_value: '3',
        fitler_answer_text: '> 65',
        filter_results: {
          total_responses: 15,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              count: 6,
              percent: 40
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              count: 9,
              percent: 60
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              count: 0,
              percent: 0
            }
          ]
        }
      }
    ]
  }
}

Example 4

Here is an example of analyzing the results of Gender, broken down by Live, filtered by Age:

http://data.unicef.ge/en/api/v2/dataset_analysis?access_token=123456789&dataset_id=1111111111&question_code=gender&broken_down_by_code=live&filtered_by_code=age
{
  dataset: 
  {
    id: "1111111111",
    title: "This is a dataset!"
  },
  question: 
  {
    code: "gender",
    original_code: "GENDER",
    text: "What is your gender?",
    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
      }
    ]
  },
  broken_down_by: 
  {
    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
      }
    ]
  },
  filtered_by:
  {
    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: "> 65",
        text: "New York City",
        can_exclude: false,
        sort_order: 3
      }
    ]
  }
  analysis_type: "comparative",
  results:
  {
    filter_analysis: [
      {
        filter_answer_value: '1',
        fitler_answer_text: '< 18',
        filter_results: 
        {
          total_responses: 23,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 2,
                  percent: 15.38
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 5,
                  percent: 38.46
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 6,
                  percent: 46.15
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 2,
                  percent: 20
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 4,
                  percent: 40
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 4,
                  percent: 40
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 0,
                  percent: 0
                }
              ]
            }
          ]
        }
      },
      {
        filter_answer_value: '2',
        fitler_answer_text: '18-65',
        filter_results: 
        {
          total_responses: 196,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 25,
                  percent: 25
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 35,
                  percent: 35
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 40,
                  percent: 40
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 20,
                  percent: 23.4
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 30,
                  percent: 31.91
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 44,
                  percent: 46.81
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 2,
                  percent: 100
                }
              ]
            }
          ]
        }
      },
      {
        filter_answer_value: '3',
        fitler_answer_text: '> 65',
        filter_results: 
        {
          total_responses: 15,
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 1,
                  percent: 12.5
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 3,
                  percent: 37.5
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 4,
                  percent: 50
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 1,
                  percent: 14.29
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 3,
                  percent: 42.86
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 3,
                  percent: 42.86
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              broken_down_results: [
                {
                  broken_down_answer_value: '1',
                  broken_down_answer_text: 'Tbilisi',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '2',
                  broken_down_answer_text: 'London',
                  count: 0,
                  percent: 0
                },
                {
                  broken_down_answer_value: '3',
                  broken_down_answer_text: 'New York City',
                  count: 0,
                  percent: 0
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

 

 

Version 2 (groups & weights)
API Home