JSON-stat Javascript Toolkit v.1 ▸ API Reference
This is the documentation of JSON-stat Javascript Toolkit version 1. Version 0 has a slightly different API and is documented elsewhere.
- Reading: JSONstat()
- Traversing: Dataset(), Dimension(), Category(), Data(), Item()
- Transforming: toTable(), Dice(), Slice()
- JSONstat():
class, coordinates, error, extension, hierarchy, href, id, label, length, link, n, size, note, role, size, source, status, unit, updated, value
object JSONstat ( object or string res [, object init] [, function typedArray] )It can be an object in the JSON-stat format or the string "version" or a string representing a URL.
When an object is specified, it processes it to build a jsonstat instance (the kind of object you need to apply the methods in this documentation).
var j=JSONstat( { ... } );
if( j.length ){
...
}else{
window.alert( "Wrong response!" );
}When the string "version" is specified, the JSON-stat Javascript Toolkit version is returned.
var version=JSONstat("version");When a URL is specified, JSONstat returns a promise that in case of fulfillment will resolve to a jsonstat instance.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.length ){
...
}else{
window.alert( "Wrong response!" );
}
});When res is a URL, an options object can be specified containing the settings to apply to the request. See fetch method to know the available properties of init.
var
url="https://pxnet2.stat.fi/PXWeb/api/v1/en/StatFin/tym/tyti/vv/statfin_tyti_pxt_11pl.px",
query={ "query": [ { "code": "Sukupuoli", "selection": { "filter": "item", "values": [ "SSS" ] } } ], "response": { "format": "json-stat2" } },
options={
method: "POST",
redirect: "follow",
body: JSON.stringify(query)
}
;
JSONstat(url, options).then(function( j ) {
var label=j.label;
});Since version 1.4, the JSON-stat Javascript Toolkit supports typed arrays. If an object that uses a typed array for the value property is passed to JSONstat(), it will keep the type once converted into a jsonstat instance.
typedArray is used to store the value property as a typed array of the specified type. It must be a valid TypedArray constructor.
JSONstat( "https://json-stat.org/samples/oecd.json", Float32Array ).then(function(j) {
console.log(j.value);
});The type is kept when a subset is created using Dice() (or Slice()) or when dataset information is exported using toTable() ("objarr" type without by).
It returns a string (version), jsonstat instance or a jsonstat instance promise.
The public properties of the jsonstat instance depend on the value of the class property.
Common properties: class, length, id
Additional properties when class is "collection": label, updated, source, note, href, link, extension
Additional properties when class is "bundle": error
Additional properties when class is "dataset": label, n, size, value, status, updated, source, role, note, href, link, extension
object or array Dataset ( [integer or string dsid] )It can be a positive integer (access by index in the datasets id array) or a string (access by ID).
When a valid dsid is specified, it returns a jsonstat instance. If dsid is not valid, a null is returned. If dsid is not specified, it will return an array of jsonstat instances: one for each dataset.
JSONstat( "https://json-stat.org/samples/oecd-canada.json" ).then(function(j) {
if( j.class==="bundle" ){
var ds1=j.Dataset( 0 );
}
});The Dataset method can also be applied to jsonstat "collection" instances if they have some embedded dataset:
JSONstat( "https://json-stat.org/samples/oecd-canada-col.json" ).then(function(j) {
if( j.class==="collection" ){
var ds1=j.Dataset( 0 );
}
});For generalization's sake, it can also be applied to jsonstat "dataset" instances:
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.class==="dataset" ){
window.alert( j===j.Dataset( 0 ) ); //true
}
});object or array Dimension ( [integer, string or object dimid] [, boolean instance] )It can be a positive integer (access by index in the dimensions id array) or a string (access by ID). If no dimid is specified, it will return information for every dimension.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.class==="dataset" ){
//Label of the first dimension
var label1=j.Dimension( 0 ).label;
}
});It can also be an object in the form { role : string }, where string is "time", "geo", "metric" or "classification". This syntax is used to filter dimensions with a particular role.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Label of the first dimension with role "geo"
var geolabel1=j.Dimension( { role : "geo" } )[0].label;
});This boolean parameter is only available when dimid is specified and alters the return value. By default (true), the return value is a jsonstat instance (object), an array of jsonstat instances or null. When a valid dimid is specified in combination with instance true, the return value is an array of category labels for dimension dimid or, when dimid is an object, an array of arrays (one for each selected dimension) of category labels.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Array of dimension "area" category labels
var arealabels=j.Dimension( "area", false );
//Same as: j.Dimension( "area" ).Category().map( function( e ){ return e.label; } )
});When a valid dimid is specified, it returns a jsonstat instance. If dimid is not valid, a null is returned. If dimid is not specified, it returns an array of jsonstat instances: one for each dimension. If dimid is a valid object, it returns an array of jsonstat instances: one for each dimension with the selected role.
object or array Category ( [integer or string catid] )It can be a positive integer (access by index in the categories id array) or a string (access by ID).
When a valid catid is specified, it returns a jsonstat instance. If catid is not valid, a null is returned. If catid is not specified, it will return an array of jsonstat instances: one for each category.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Label of category "AU" in dimension "area"
var AUlabel=j.Dimension( "area" ).Category( "AU" ).label; //"Australia"
});object, array, integer or string Data ( [integer, array or object dataid, boolean status] )It can be a positive integer (by index in the value array), an array (by dimensions indices) or an object (by dimensions IDs).
This boolean parameter determines whether status information is retrieved or not (default is true).
If no parameter is specified, the result is an array of value-status objects (one object per datum in the dataset).
If status is not specified or is true, the return value can be a value-status object (that is, an object with two properties: value and status), an array of value-status objects or null when dataid is not valid.
If dataid is an integer, the result is a value-status object if dataid is a valid index. Otherwise, a null is returned.
If dataid is an array, the result is a value-status object if dataid has the correct size (number of dimensions) and valid category indices. Otherwise, a null is returned.
If dataid is an object, a dimension is ignored if its ID or the ID of its category is invalid. If all dimensions/categories are correctly specified, the result is a value-status object. Take into account that constant dimensions (that is, single category dimensions) are not required. Therefore, to get a value-status object, you need to validly select a category for all the non-constant dimensions. If you do not validly select a category of a non-constant dimension (from now on, the free dimension), the return value will be an array of value-status objects: one for each category in the free dimension (slice). Objects will be ordered in the free dimension category order. If there is more than one free dimension, a null will be returned.
Since version 1.5, it returns null when the dataset has no values.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Value of the first observation
var data0=j.Data( 0 ).value;
//Same as value with the first category in each dimension
var data000=j.Data( [0, 0, 0] ).value;
//Value with concept "UNR", area "GR" and year "2014"
var unrGR2014=j.Data( { "concept" : "UNR", "area" : "GR", "year" : "2014" } ).value;
});If status is false, value-status objects will be replaced by simple values (usually a number; Data() returns whatever was included in the cell by the provider: number, string, null...). As a consequence, the return value will be a value, an array of values or null when dataid is not valid.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Value of the first observation
var data0=j.Data( 0, false );
//Same as value with the first category in each dimension
var data000=j.Data( [0, 0, 0], false );
//Value with concept "UNR", area "GR" and year "2014"
var unrGR2014=j.Data(
{ "concept" : "UNR", "area" : "GR", "year" : "2014" },
false
);
});It is also possible to use an array of arrays instead of an object.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
var unrGR2014=j.Data(
[
["concept", "UNR"],
["area", "GR"],
["year", "2014"]
]
);
//Same as { "concept" : "UNR", "area" : "GR", "year" : "2014" }
});object or array Item ( [integer or object itemid] )It can be a positive integer (access to item information by index) or an object.
When itemid is an object, it must have a "class" property with a valid class value.
When the "class" property has "dataset" as its value, the object accepts the boolean property "embedded".
When a valid itemid is specified, it returns an item object (an object with the public properties of Item()). If itemid is an integer but out of range, a null is returned.
If itemid has a "class" property, it will return an array of item objects: those that meet the filter conditions; otherwise, a null is returned. When the "class" value is "dataset" and the boolean property "embedded" is specified, it will return an array with the items of class "dataset" that (true) are embedded or that (false) are not ("href", "label" and "extension" are included in the dataset item).
If the value of the "class" property is not a valid class value, an empty array is returned.
When itemid is not specified, it returns an array of item objects: one for each item.
JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
//Get the label of the first item in the collection
var label1=j.Item( 0 ).label;
});JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
//Get the number of items with class "dataset" in the collection
var dsn=j.Item( { class : "dataset" } ).length;
});JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
//Get the number of embedded dataset in the collection (none)
var dsn=j.Item( { class : "dataset" , embedded: true } ).length;
});object or array toTable ( [object opts, function callback] )It is an object with the following optional properties:
- type: String (arrobj, objarr, object, array). Default value is array. It determines the form of the return value.
- status: Boolean. Default value is false. It determines whether the status of each value is included in the return value.
- content: String (id, label). Default value is label. It determines whether categories are identified by label or by ID in the return value.
- field: String (id, label). Default value is label except when type is arrobj or objarr. It determines whether dimensions, value and status are identified by label or by ID in the return value. When a valid by is specified, field is ignored and set to id.
- vlabel: String. Default value is Value. It determines the label of the value field.
- slabel: String. Default value is Status. Only available when status is true. It determines the label of the status field.
- unit: Boolean. Default value is false. Only available when type is arrobj or objarr. It determines whether unit information is included in the output. When true, each object in the array includes a unit property with all the unit information attached to a value by the provider. It is assumed that there is only a dimension with role metric in the dataset (or at least only one with unit information).
- meta: Boolean. Default value is false. Only available when type is arrobj or objarr. It determines the structure of the output. When meta is true, metadata is included in the output, which takes the form of an object with two properties: "meta" and "data". The latter contains the same array of objects that is returned when meta is false.
- by: String. Only available when type is arrobj or objarr. It must be the ID of an existing dimension; otherwise, it will be ignored. When a valid by is specified, a property is created for each category of the by dimension (the "value" property is "transposed" by the by dimension). When a valid by is specified, field, status and unit are ignored.
- bylabel: Boolean. Default is false. Only available when type is arrobj or objarr. When true, the categories of the by dimension are identified, once transposed, by their label instead of their ID.
- prefix: String. Only available when type is arrobj or objarr. When values are transposed using the by option, category IDs end up being used as properties, side by side with dimension IDs. To avoid collision, a prefix can be specified to be added at the beginning of each new property created by the transposition. When no valid by has been specified, the prefix property is ignored.
- drop: Array. Only available when type is arrobj or objarr. This property is used to provide dimension IDs not to be included in the output. Invalid dimension IDs and non single category dimensions are ignored. When no valid by is specified, the drop property is ignored.
- comma: Boolean. Default value is false. Only available when type is arrobj or objarr. When true, values are represented as strings instead of numbers with comma as the decimal mark.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//Column names (first row)
//["country", "year", "age group", "concepts", "sex", "Value"]
var cols=j.toTable( { type : "array" } )[0];
//IDs instead of labels
//["country", "year", "age", "concept", "sex", "value"]
cols=j.toTable( { type : "array", field : "id" } )[0];
//Labels including status
//["country", "year", "age group", "concepts", "sex", "Status", "Value"]
cols=j.toTable( { type : "array", status : true } )[0];
//Same but naming status as "Metadata" and value as "Data"
cols=j.toTable( { type : "array", status : true, vlabel : "Data", slabel: "Metadata" } )[0];
//First data row
//["Canada", "2012", "total", "population", "total", 34880.5]
var row1=j.toTable( {type: "array"} )[1];
//Same including status
//["Canada", "2012", "total", "population", "total", "a", 34880.5]
row1=j.toTable( {type: "array", status: true} )[1];
//Same but IDs instead of labels
//["CA", "2012", "T", "POP", "T", "a", 34880.5]
row1=j.toTable( {type: "array", status: true, content: "id"} )[1];
});It is a function used to transform the return value.
Even though toTable can expose a table using different structures depending on type, it always includes some sort of array for data. callback will be invoked for each element of the data array, passing two parameters: the element and its index. The this keyword in callback is the dataset information as a jsonstat instance.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//Discard data by age in the resulting table
j.toTable(
{ type : "arrobj" },
function( d, i ){
if( d.age==="total" ){
return d;
}
}
);
});Filters and transformations in the callback must be expressed in terms of the form of the data array, which depends on opts. In the previous example, age is filtered using a category label (total) because this is the default value of the content option.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//Discard data by age in the resulting table.
//Using categories ID instead of labels.
j.toTable(
{ type : "arrobj" , content : "id" },
function( d, i ){
if( d.age==="T" ){
return d;
}
}
);
});Take into account that every type returns a different form of data array.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//As previous example but with type "array"
//Age is the third dimension (its index is 2)
j.toTable(
{ type : "array" , content : "id" },
function( d, i ){
if( d[2]==="T" ){
return d;
}
}
);
});JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//As previous example but with type "object"
//Age is the third dimension (its index is 2)
j.toTable(
{ type : "object" , content : "id" },
function( d, i ){
if( d.c[2].v==="T" ){
return d;
}
}
);
});The arrobj / objarr types do not return a table header, but array and object type do: callback cannot act on the header, only on the data array.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//This will not remove the header (row 0 in type "array") but the first data row
j.toTable(
{ type : "array" },
function( d, i ){
if( i ){
return d;
}
}
);
});Because the array / object types include a header in the result, it is not advisable to change the structure of the data array when using these types: the header will be left untouched and incoherent.
If you need to transform the output deeply use the arrobj / objarr type.
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
//Select only the female population by age group
//Get an array of objects with only two properties (age and population)
//Change scale of units
j.toTable(
{ type : "arrobj", content : "id" },
function( d ){
if( d.sex==="F" && d.concept==="POP" ){
return { age : d.age, population : d.value*1000 };
}
}
);
});It depends on the type specified in the opts parameter. Since version 1.5, it returns null when the dataset has no values.
Unless meta is true, it returns an array of objects, where the key is the dimension ID, value or status (columns) and the value can be the category label or ID.
[
{ "age" : "total", "concept" : "population", "country": "Canada", "sex": "total", "value" : 34880.5, "year" : "2012"},
{ "age" : "total", "concept" : "population", "country": "Canada", "sex": "male", "value" : 17309.1, "year" : "2012"},
{ "age" : "total", "concept" : "population", "country": "Canada", "sex": "female", "value" : 17571.3, "year" : "2012"},
...
]When meta is true, it returns an object of objects:
{
"meta": {
"label": "Population by sex and age group. Canada. 2012",
"source": "Statistics Canada, CANSIM, table 051-0001",
"updated": "2012-09-27",
"id": ["country", "year", "age", "concept", "sex"],
"status": false,
"unit": false,
"by": "sex",
"bylabel": false,
"drop": ["year", "country"],
"prefix": "",
"comma": false,
"dimensions": {
"sex": {
"label": "sex",
"role": "classification",
"categories": {
"id": [ "T", "M", "F"],
"label": [ "total", "male", "female" ]
}
},
"age": { ... },
"concept": { ... },
"country": { ... },
"year": { ... }
}
},
"data": [
...
]
}The dimensions included in the "meta.dimensions" property are not affected by the value of the by and drop options.
objarr has the same options of arrobj but, instead of using an array of objects, it expresses data as an object where each property (table column) is an array. This table structure is often known as column-oriented arrays or columnar format.
{
"value": [5.943826289, 5.39663128, 5.044790587, ...],
"status": [null, null, null, ...],
"year": ["2003", "2004", "2005", ...],
"area": ["AU", "AU", "AU", ...],
"concept": ["UNR", "UNR", "UNR", ...]
}It returns an array of arrays. The first element in the array contains the column labels or IDs. The next elements can use category labels or IDs.
[
[ "country", "year", "age group", "concepts", "sex", "Value" ],
[ "Canada", "2012", "total", "population", "total", 34880.5 ],
[ "Canada", "2012", "total", "population", "male", 17309.1 ],
...
]It returns an object of arrays in the Google DataTable format.
{
"cols" : [ ... ],
"rows" : [ ... ]
}Warning: DataTable declares explicitly the type of the values. JSON-stat does not, so this information must be inferred. Generally, it can safely be assumed that values are numbers. Currently, toTable only performs a very naïf test: if the first value is a number (or null), it will assign a type of number; otherwise, it will assign a type of string.
object or string Dice ( [object or array filter, object opts] )This parameter is used to define a subset of the original dataset by keeping only the specified dimension categories. It does not remove any dimension from the original dataset: it only removes categories.
The filter can be specified as an object where properties are dimensions IDs and values are arrays of categories IDs (like in JSON-stat for Eurostat) or as an array of arrays (pairs of dimension ID / category IDs)).
{
"geo": ["AT"],
"time": ["2017", "2018"]
}[
["geo", ["AT"]],
["time", ["2017", "2018"]]
]It is an object with the following optional properties:
Boolean. Default value is false.
The subset is created by modifying the original dataset. This parameter determines whether the original dataset is kept (default is false) or modified. To create a new dataset and keep unchanged the original one, use true.
JSONstat("https://json-stat.org/samples/oecd.json").then(function(j){
j.Dice(
{
"area": ["AT","CA"],
"year": ["2010","2011"]
}
);
//j has been modified
});JSONstat("https://json-stat.org/samples/oecd.json").then(function(j){
var subset=j.Dice(
{
"area": ["AT","CA"],
"year": ["2010","2011"]
},
{
clone: true
}
);
});Boolean. Default value is false.
Filters are positive statements: they state what you want. Sometimes it is shorter to use a negative statement (antifilter). Instead of specifying what you want to keep, an antifilter states what you do not want and shall be dropped.
This boolean parameter determines whether the filter parameter is in fact an antifilter and must be read negatively (default is false). Use true to provide the dimension categories that you want to drop from the dataset instead of those that you want to keep.
var
drop={
//do not keep areas that aren't countries
"area": ["EU15", "OECD"],
//drop 2003-2005
"year": ["2003", "2004", "2005"]
}
;
JSONstat("https://json-stat.org/samples/oecd.json").then(function(j){
j.Dice(
drop,
{
drop: true
}
);
});Boolean. Default value is false.
When true, the Dice method returns a JSON-stat string.
JSONstat("https://json-stat.org/samples/oecd.json").then(function(j){
var str=j.Dice(
{
"area": ["AT","CA"],
"year": ["2010","2011"]
},
{
stringify: true
}
);
});This option can be used to convert JSON-stat<2.0 documents to JSON-stat 2.0.
JSONstat("https://data.ssb.no/api/v0/dataset/1118.json?lang=en").then(function(j){
console.log(JSON.parse(j.Dataset(0).Dice(null, { stringify: true })));
});By default, when stringify is true, the JSON-stat properties value and status (if present) are returned in array form. Options ovalue and ostatus allow you to change this.
Boolean. Default value is false.
When true, the value property is returned as an object instead of an array.
This option is ignored if stringify is false.
Boolean. Default value is false.
When true, the status (if present) property is returned as an object instead of an array.
This option is ignored if stringify is false.
It returns a jsonstat instance or a string when the stringify option is true. Since version 1.5, it returns null when the dataset has no values.
object Slice ( object or array filter] )Deprecated in version 1.1 (use the more powerful Dice() instead).
This parameter is used to define a subset of the original dataset by freezing one or several dimensions by one of its categories. It does not remove any dimension of the original dataset: it only makes the selected dimensions constant (single category dimensions).
The filter can be specified as an object where properties are dimensions IDs and values are categories IDs or as an array of arrays (pairs of dimension ID / category ID)).
JSONstat("https://json-stat.org/samples/galicia.json").then(function(j){
var
subset=j.Slice(
//Flatten dimensions "birth", "age", "time":
//Keep only
//category "T" of dimension "birth"
//category "T" of dimension "age"
//category "2011" of dimension "time"
{ "birth": "T", "age": "T", "time": "2011" }
)
;
});JSONstat("https://json-stat.org/samples/galicia.json").then(function(j){
var
subset=j.Slice(
//Flatten dimensions "birth", "age", "time":
//Keep only
//category "T" of dimension "birth"
//category "T" of dimension "age"
//category "2011" of dimension "time"
[
[ "birth", "T" ],
[ "age", "T" ],
[ "time", "2011" ]
]
)
;
});It returns a jsonstat instance identical to the original one but with some dimensions "flattened". When filter is wrong, null is returned. Since version 1.5, it returns null when the dataset has no values.
Warning: Keep in mind that this is performed by actually modifying the original dataset. If you want to keep it, clone it first.
JSONstat("https://json-stat.org/samples/galicia.json").then(function(j){
var
original=JSON.parse( JSON.stringify( j ) ),
subset=j.Slice(
{ "birth": "T", "age": "T", "time": "2011" }
) //j will be modified
;
//Compare original, subset and j
});Response class. String ("collection", "bundle", "dataset", "dimension").
var
j=JSONstat( { ... } ),
datasets=[]
;
switch( j.class ){
case "collection":
j.Item( { class : "dataset" , embedded: false } ).forEach( function( e ){
datasets.push( JSONstat( e.href ) ); //Async. Deprecated.
});
break;
case "bundle":
datasets=j.Dataset();
break;
case "dataset":
datasets=[j]; //Same as j.Dataset()
break;
}Category coordinates if the category dimension has a geo role. Array of two numbers (longitude, latitude). If no coordinates have been provided, a null is returned.
Optional error information. Object. The properties of this object depend on the provider.
Collection, dataset, dimension or item extended information. Object. The properties of this object depend on the provider.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
var
//This dataset contains extended properties
ext=j.extension,
//Get e-mail of contact
email=ext["contact"]
;
});true if there is information about the relationship between the categories in the dimension. Boolean.
JSONstat( "https://json-stat.org/samples/hierarchy.json" ).then(function(j) {
//First dimension
var dim=j.Dimension( 0 );
if( dim.hierarchy ){
var
//First category ID
id=dim.id[0],
//Array of children's IDs
ids=dim.Category( 0 ).id
;
}
});Collection, bundle, dataset or dimension URL.
JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
//Get the URL of the first item in the collection
var href1=j.Item( 0 ).href;
});Datasets, dimensions, categories, category children or items IDs. Array of strings.
In the case of category children, id is an array when the dimension includes hierarchical information and the selected category has children. Otherwise it is null.
In the case of items, id is an array of URLs.
//This example would work also with https://json-stat.org/samples/oecd.json
JSONstat( "https://json-stat.org/samples/oecd-canada.json" ).then(function(j) {
if( j.class==="bundle" || j.class==="dataset" ){
var
//"OECD" dataset (if class "bundle")
ds=j.Dataset( "oecd" ),
//Dimensions IDs of that dataset
dimids=ds.id,
//"area" dimension in that dataset
dim=ds.Dimension( "area" ),
//Categories IDs of that dimension
catids=dim.id
;
if( dim.hierarchy ){
//Category IDs that belong to OECD
var oecdids=dim.Category( "OECD" ).id;
}
}
});Collection, dataset, dimension, category or item label. String.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Label for "AU" area (Australia)
var label=j.Dataset( "oecd" ).Dimension( "area" ).Category( "AU" ).label;
});Number of datasets, dimensions, categories, category children or items. Integer.
You should always check for length>0 before further processing.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.length ){
...
}else{
window.alert( "Wrong response!" );
}
});Collection, bundle, dataset or dimension links. Object of relation names.
JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
//Get info for IANA link relation "item" in a collection http://www.iana.org/assignments/link-relations/link-relations.xhtml
var items=j.link["item"];
//Same as j.Item().
});Number of values in the dataset. Integer. It is the number of cells in the cube, even if they are empty (missing values).
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
window.alert("This dataset has " + String( j.n ) + " observations.");
});Dataset, dimension, category or collection annotations. Array of strings except category annotations, which are an object of strings.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Display general dataset annotations if available
var note=j.note;
if( note ){
note.forEach( function( e ){
window.alert( e );
});
}
//Display annotations for Germany if available
var denote=j.Dimension( "area" ).Category( "DE" ).note;
if( denote ){
denote.forEach( function( e ){
window.alert( e );
});
}
});Dimensions with role time, geo, metric or with unspecified role (classification). null if role information was not included in the response; otherwise, object with four keys (time, geo, metric and classification). The value of every key is an array of dimensions IDs (or null if no dimension has the specified role).
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Get the name of the first dimension with a "geo" role
var geo1=j.role.geo[0];
});Dimension role. String (time, geo, metric; otherwise, classification) or null (when role information not included in the response).
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Role of the "concept" dimension
var crole=j.Dimension( "concept" ).role;
});Dimensions sizes. Array.
Dataset or collection source. String.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Dataset source
var source=j.source;
});As a property of a dataset, status of its values. Array or null.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.status ){
//Status of the 23rd value
var status23=j.status[22];
}
});As a property of a datum, status of its value. String or null if not provided.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//Status of the 23rd value
var status23=j.Data( 22 ).status;
});Category unit information if the category dimension has a metric role. Object. Except "decimals", "label", "symbol" and "position", the rest of the properties of this object depend on the provider. If no unit information has been provided, a null is returned.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//First category in the first dimension with a "metric" role
var metric1=j.Dimension( { role : "metric" } )[0].Category( 0 );
if( metric1.unit && metric1.unit.hasOwnProperty( "decimals" ) ){
//Decimals of the first category in the first dimension with a "metric" role
var dec=metric1.unit.decimals;
}
});It is the update date of the dataset or collection. String representing a date in an ISO 8601 format recognized by the Javascript Date.parse method.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.updated ){
var
upd=new Date( j.updated ),
timelapse=Date.now()-upd,
days=Math.floor( timelapse / ( 1000*60*60*24 ) )
;
window.alert( "This dataset was updated " + String( days ) + " days ago." );
}
});As a property of a dataset, dataset values. Array.
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
if( j.value ){
//23rd value
var value23=j.value[22];
}
});As a property of a datum, datum value. Usually a number. Data() returns whatever was included in the cell by the provider (number, string, null...).
JSONstat( "https://json-stat.org/samples/oecd.json" ).then(function(j) {
//23rd value
var value23=j.Data( 22 ).value; //Same as j.Data( 22, false )
});