Documentation

rafaelsmedina edited this page Jul 18, 2018 · 5 revisions

Summary

Quickstart

The best way to explain the features of the API gives you is to show it in use. Basically, this is how the API url looks like:

staging.api.dataviva.info/<dataset>/<dimension>/<another_dimension>/.../?<filters>

And this is how the results of the queries are returned:

{
  "data": [
    ...
  ], 
  "headers": [
    ...
  ]
}

The result is a json object that contains two objects: data and headers. The data is an array where each of its items is an array of values and the headers object contains the meaning of each value. As we can see in the example below. Each item of the data object contains a list of values and the value are described by the headers object and its position. So in this example, we have in each item of the data object, the year, the value and the kg.

{
  "data": [
    [
      2015, 
      36258, 
      78410
    ],
    [
      2014, 
      75493, 
      11140
    ]
  ], 
  "headers": [
    "year", 
    "value", 
    "kg"
  ]
}

Dataset

The dataset specifies the source of the data. Each dataset is represented by a model. You can see all datasets that are available here.

Dimensions

The dimensions are the fields that allow the data can be grouped. The dimensions are specific for each dataset. You can see which dimensions are avaliable in the respective model. In a query you can use as many dimensions as you want.

http://staging.api.dataviva.info/secex/year/
{
  "data": [
    [
      1999, 
      97314347639, 
      314166038952
    ], 
    ...
  ], 
  "headers": [
    "year", 
    "value", 
    "kg"
  ]
}

or

http://staging.api.dataviva.info/secex/year/state
{
  "data": [
    [
      1997, 
      "33", 
      9064984833, 
      22579526998
    ], 
    ...
  ], 
  "headers": [
    "year", 
    "state", 
    "value", 
    "kg"
  ]
}

Aggregate Functions

Each model also has a list of values that are result of aggregate functions. You can see the aggregate function of each model in the aggregate class method in the models. By default, a list of values specified by the values class method is returned at each query. But you can specify what values of the list of aggregate functions you want using the parameter value.

  http://staging.api.dataviva.info/sc/year/?value=students

Will return:

{
  "data": [
    [
      2008, 
      41458105
    ], 
    [
      2009, 
      41068828
    ], 
    ...
  ], 
  "headers": [
    "year", 
    "students"
  ]
}

Is also possible to get more than one value.

http://staging.api.dataviva.info/sc/year/?value=average_age&value=students

Which will return this:

{
  "data": [
    [
      2008, 
      12, 
      41458105
    ], 
    [
      2009, 
      12, 
      41068828
    ],
    ...
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students"
  ]
}

Filters

You can filter by any dimension available. For this, use the name of the dimension as key in the parameters list.

http://staging.api.dataviva.info/sc/year/?year=2014&state=31

Will return:

{
  "data": [
    [
      2014, 
      12, 
      3703869
    ]
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students"
  ]
}

It is also possible to use the not equal operator !=. In this example we will filter by all years, except 2008:

http://staging.api.dataviva.info/sc/year/?year!=2008&order=year

{
  "data": [
    [
      2009, 
      12, 
      41068828, 
      1598048, 
      25, 
      160974
    ], 
    [
      2010, 
      12, 
      40432207, 
      1600936, 
      25, 
      158067
    ], 
    [
      2011, 
      12, 
      39886289, 
      1596159, 
      24, 
      155655
    ], 
    [
      2012, 
      12, 
      39268961, 
      1594245, 
      24, 
      154549
    ], 
    [
      2013, 
      12, 
      38604664, 
      1585579, 
      24, 
      151561
    ], 
    [
      2014, 
      12, 
      38247972, 
      1574103, 
      24, 
      148857
    ], 
    [
      2015, 
      12, 
      37308904, 
      1546803, 
      24, 
      145776
    ], 
    [
      2016, 
      12, 
      37035289, 
      1530006, 
      24, 
      144386
    ]
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students", 
    "classes", 
    "average_class_size", 
    "schools"
  ]
}

Limit

You can set a limit for your data. For this, use the parameter limit.

http://staging.api.dataviva.info/sc/year/?limit=1

Will return:

{
  "data": [
    [
      2010, 
      12, 
      40432207
    ]
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students"
  ]
}

Order

You can also sort your response. For this, use the parameter order.

http://staging.api.dataviva.info/sc/year?order=year

And it will return this:

{
  "data": [
    [
      2008, 
      12, 
      41458105
    ], 
    [
      2009, 
      12, 
      41068828
    ],
    ...
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students"
  ]
}

and define the sort direction [asc|desc] with the parameter direction.

http://staging.api.dataviva.info/sc/year?sort=year&direction=asc

Which will return:

{
  "data": [
    [
      2010, 
      12, 
      40432207
    ], 
    [
      2011, 
      12, 
      39886289
    ],
    ...
  ], 
  "headers": [
    "year", 
    "average_age", 
    "students"
  ]
}

Metadata

There is also metadata, which summarizes basic information about data, and makes it easier to search and work with specific instances of data. Each data returned by the API is a value or id. For any data that is an id, it is possible to get more information about it. To do this just use the metadata API. This is how the metadata API looks like:

http://staging.api.dataviva.info/metadata/<dimension>/[id]

For using it, just select the dimension of the data desired.

http://staging.api.dataviva.info/metadata/sc_course_field

By doing this, you will get a list of all items of the data that you want.

{
  "00": {
    "name_en": "Unspecified", 
    "name_pt": "N\u00e3o especificado"
  }, 
  "01": {
    "name_en": "Environment and Health", 
    "name_pt": "Ambiente e Sa\u00fade"
  }, 
  "02": {
    "name_en": "Educational and Social Development", 
    "name_pt": "Desenvolvimento Educacional e Social"
  }, 
  "03": {
    "name_en": "Control and Industrial Process", 
    "name_pt": "Controle e Processos Industriais"
  }, 
  "04": {
    "name_en": "Business and Management", 
    "name_pt": "Gest\u00e3o e Neg\u00f3cios"
  }, 
  "05": {
    "name_en": "Tourism, Hospitality and Leisure", 
    "name_pt": "Turismo, Hospitalidade e Lazer"
  }, 
  "06": {
    "name_en": "Information and Communication", 
    "name_pt": "Informa\u00e7\u00e3o e Comunica\u00e7\u00e3o"
  }, 
  "07": {
    "name_en": "Infrastructure", 
    "name_pt": "Infraestrutura"
  }, 
  "08": {
    "name_en": "Military", 
    "name_pt": "Militar"
  }, 
  "09": {
    "name_en": "Food Production", 
    "name_pt": "Produ\u00e7\u00e3o Aliment\u00edcia"
  }, 
  "10": {
    "name_en": "Cultural Production and Design", 
    "name_pt": "Produ\u00e7\u00e3o Cultural e Design"
  }, 
  "11": {
    "name_en": "Industrial production", 
    "name_pt": "Produ\u00e7\u00e3o Industrial"
  }, 
  "12": {
    "name_en": "Natural resources", 
    "name_pt": "Recursos Naturais"
  }, 
  "13": {
    "name_en": "Work safety", 
    "name_pt": "Seguran\u00e7a do Trabalho"
  }, 
  "xx": {
    "name_en": "Basic Education", 
    "name_pt": "Ensino Fundamental"
  }
}

But if you want just a specified item, just pass the id in the API.

http://staging.api.dataviva.info/metadata/sc_course_field/12

And it returns this:

{
  "name_en": "Natural resources", 
  "name_pt": "Recursos Naturais"
}
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.