Version 1 - Time Series Analysis

Released At: 29 Apr 2015Last Updated At: 02 Nov 2015

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/v1/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:

ParameterDescription
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.

ParameterDescription
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
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:

ParameterDescription
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
  • is_mappable - a boolean flag indicating if this question has been assigned to map shapes
  • 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
  • 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
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
    • percent - the percent of people with answer compared to the total responses

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 
        • percent - the percent of people that had both the filtered by answer and the question answer compared to the total responses
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:
      • - the percent value from the results
      • count - the count value from the results

Examples

Example 1

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

http://data.unicef.ge/en/api/v1/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/v1/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
                }
              ]
            }
          ]
        }
      }
    ]
  }
}