Version 3 (categorical & numerical types) - Time Series Analysis

Released At: 25 Jan 2016Last Updated At: 10 Jul 2019

Analyze data in a time series. The time series 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/v3/time_series_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:

Parameter	Description
access_token	All requests must include an access_token. You can obtain an access token easily, and for free, by going here.
time_series_id	The ID of the time series.
question_code	The code of a question in the time series.

Optional Parameters

There following parameters are optional for this call.

Parameter	Description
language	Code of the language to return the time series information in (e.g., 'en' for English). If language is not provided, the default language of the time series will be used.
filter_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 time series 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)
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 to be put into a Highcharts chart (default value is false)

What You Get

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

Parameter	Description
time_series	An object with the following values: id - the ID of the time series that was analyzed title - the title of the time series that was analyzed
datasets	An array of the datasets that are in the time series with the following values: id - the ID of the dataset title - the title of the dataset label - the label of the dataset in this time series
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 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 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 time series 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: time_series - a time series analysis of question_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 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 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 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)
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 data - an array of data points for each dataset with the following information: 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)

Examples

Example 1

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

http://data.unicef.ge/en/api/v3/time_series_analysis?access_token=123456789&time_series_id=1111111111&question_code=gender

{
  time_series: 
  {
    id: "1111111111",
    title: "This is a time series!"
  },
  datasets:[
    {
      id: "11112009",
      title: "Dataset from 2009"
      label: "2009"
    },
    {
      id: "11112011",
      title: "Dataset from 2011"
      label: "2011"
    },
    {
      id: "11112013",
      title: "Dataset from 2013"
      label: "2013"
    }
  ],
  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: "time_series",
  results:
  {
    total_responses:[
      {
        dataset_label: '2009',
        dataset_title: 'Dataset from 2009',
        count: 150
      },
      {
        dataset_label: '2011',
        dataset_title: 'Dataset from 2011',
        count: 160
      },
      {
        dataset_label: '2013',
        dataset_title: 'Dataset from 2013',
        count: 200
      }
    ],
    analysis: [
      {
        answer_value: '1',
        answer_text: 'Male',
        dataset_results:[
          {
            dataset_label: '2009',
            dataset_title: 'Dataset from 2009',
            count: 80,
            percent: 53.33
          },
          {
            dataset_label: '2011',
            dataset_title: 'Dataset from 2011',
            count: 85,
            percent: 53.13
          },
          {
            dataset_label: '2013',
            dataset_title: 'Dataset from 2013',
            count: 100,
            percent: 50
          }
        ]
      },
      {
        answer_value: '2',
        answer_text: 'Female',
        dataset_results:[
          {
            dataset_label: '2009',
            dataset_title: 'Dataset from 2009',
            count: 68,
            percent: 45.33
          },
          {
            dataset_label: '2011',
            dataset_title: 'Dataset from 2011',
            count: 75,
            percent: 46.88
          },
          {
            dataset_label: '2013',
            dataset_title: 'Dataset from 2013',
            count: 95,
            percent: 47.5
          }
        ]
      },
      {
        answer_value: '3',
        answer_text: 'Refuse to Answer',
        dataset_results:[
          {
            dataset_label: '2009',
            dataset_title: 'Dataset from 2009',
            count: 2,
            percent: 1.33
          },
          {
            dataset_label: '2011',
            dataset_title: 'Dataset from 2011',
            count: 0,
            percent: 0
          },
          {
            dataset_label: '2013',
            dataset_title: 'Dataset from 2013',
            count: 5,
            percent: 2.5
          }
        ]
      }
    ]
  }
}

Example 2

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

http://data.unicef.ge/en/api/v3/time_series_analysis?access_token=123456789&time_series_id=1111111111&question_code=gender&filtered_by_code=live

{
  time_series: 
  {
    id: "1111111111",
    title: "This is a time series!"
  },
  datasets:[
    {
      id: "11112009",
      title: "Dataset from 2009"
      label: "2009"
    },
    {
      id: "11112011",
      title: "Dataset from 2011"
      label: "2011"
    },
    {
      id: "11112013",
      title: "Dataset from 2013"
      label: "2013"
    }
  ],
  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: "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: "time_series",
  results:
  {
    filter_analysis: [
      {
        filter_answer_value: '1',
        fitler_answer_text: 'Tbilisi',
        filter_results: {
          total_responses:[
            {
              dataset_label: '2009',
              dataset_title: 'Dataset from 2009',
              count: 15
            },
            {
              dataset_label: '2011',
              dataset_title: 'Dataset from 2011',
              count: 16
            },
            {
              dataset_label: '2013',
              dataset_title: 'Dataset from 2013',
              count: 20
            }
          ],
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 8,
                  percent: 53.33
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 9,
                  percent: 56.25
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 10,
                  percent: 50
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 7,
                  percent: 46.67
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 7,
                  percent: 43.75
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 10,
                  percent: 50
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 0,
                  percent: 0
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 0,
                  percent: 0
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 0,
                  percent: 0
                }
              ]
            }
          ]
        }
      },
      {
        filter_answer_value: '2',
        fitler_answer_text: 'London',
        filter_results: {
          total_responses:[
            {
              dataset_label: '2009',
              dataset_title: 'Dataset from 2009',
              count: 60
            },
            {
              dataset_label: '2011',
              dataset_title: 'Dataset from 2011',
              count: 80
            },
            {
              dataset_label: '2013',
              dataset_title: 'Dataset from 2013',
              count: 75
            }
          ],
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 35,
                  percent: 58.33
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 42,
                  percent: 52.5
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 40,
                  percent: 53.33
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 25,
                  percent: 41.67
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 38,
                  percent: 47.5
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 35,
                  percent: 46.67
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 0,
                  percent: 0
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 0,
                  percent: 0
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 0,
                  percent: 0
                }
              ]
            }
          ]
        }
      },      
      {
        filter_answer_value: '3',
        fitler_answer_text: 'New York City',
        filter_results: {
          total_responses:[
            {
              dataset_label: '2009',
              dataset_title: 'Dataset from 2009',
              count: 75
            },
            {
              dataset_label: '2011',
              dataset_title: 'Dataset from 2011',
              count: 80
            },
            {
              dataset_label: '2013',
              dataset_title: 'Dataset from 2013',
              count: 100
            }
          ],
          analysis: [
            {
              answer_value: '1',
              answer_text: 'Male',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 37,
                  percent: 49.33
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 40,
                  percent: 50
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 50,
                  percent: 50
                }
              ]
            },
            {
              answer_value: '2',
              answer_text: 'Female',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 36,
                  percent: 48
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 40,
                  percent: 50
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 45,
                  percent: 45
                }
              ]
            },
            {
              answer_value: '3',
              answer_text: 'Refuse to Answer',
              dataset_results:[
                {
                  dataset_label: '2009',
                  dataset_title: 'Dataset from 2009',
                  count: 2,
                  percent: 2.67
                },
                {
                  dataset_label: '2011',
                  dataset_title: 'Dataset from 2011',
                  count: 0,
                  percent: 0
                },
                {
                  dataset_label: '2013',
                  dataset_title: 'Dataset from 2013',
                  count: 5,
                  percent: 5
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

API Home