Wiki ▸ API Reference
This is the documentation of JSON-stat Javascript Toolkit version 0. Version 1 has a slightly different API and is documented elsewhere.
class, coordinates, error, extension, hierarchy, href, id, label, length, link, n, size, note, role, size, source, status, unit, updated, value, version
Parent: none
Description: Creates a
jsonstatinstance from an external input in the
JSON-stat format Public Properties:
class,
length,
id,
error,
label,
n,
size,
value,
status,
updated,
source,
role,
note,
href,
link,
extensionSummary: object JSONstat ( object or string resp [, function callback] [, boolean instance] )
It can be an object in the JSON-stat format or a string representing a URL.
var j=JSONstat( { ... } ); if( j.length ){ ... }else{ window.alert( "Wrong response!" ); } } );
Warning: Using a string representing a URL in this manner is deprecated and will be probably removed in version 1 (when JSONstat is expected to support XHR using promises).
When a URL is specified, JSONstat will try to connect to it to retrieve an object in the JSON-stat format. The JSONstat connection capabilities are not available in the modules versions (Node.js and ECMAScript) (Node.js already comes with a built-in http module and many third-party modules already try to simplify such task, like request or got) and are limited to modern browsers. If you need to support very old browsers, use an object in the JSON-stat format instead of a URL string.
When the URL is absolute, JSONstat will attempt a cross-domain http request. This requires CORS support on the provider’s server. To avoid possible connection issues in older browsers, use a relative URL whenever possible.
If resp is a string and no callback is specified (deprecated), the connection will be synchronous.
var j=JSONstat( "https://json-stat.org/samples/oecd.json" ); if( j.length ){ ... }else{ window.alert( "Wrong response!" ); }
If resp is an object, callback and instance are ignored.
It is a function. Deprecated (it will be probably removed in version 1, when JSONstat is expected to support XHR using promises).
When callback is specified and resp is not an object, the connection is asynchronous. callback is executed after the connection has successfully finished and the resulting jsonstat instance is assigned to the this keyword.
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { if( this.length ){ ... }else{ window.alert( "Wrong response!" ); } } );
This boolean parameter (introduced in version 0.10.2) is only available when a callback is specified (asynchronous connection) and alters the content of the this keyword. By default (true), the this keyword contains a jsonstat instance. When instance is false and the connection successful, JSONstat() simply performs a GET XMLHttpRequest and converts the resulting JSON text into an object in the JSON-stat format but it does not perform the default last step: it does not process this object to build a jsonstat instance (the kind of object you need to apply the methods in this documentation, which means that, in a typical situation, you will need to run JSONstat() twice.
JSONstat( "https://json-stat.org/samples/oecd.json", function(){ var label=JSONstat( this ).label; }, false );
This parameter may be useful in scenarios where cloning a jsonstat instance is necessary.
JSONstat( "https://json-stat.org/samples/oecd.json", function(){ var orig=JSONstat( this ), copy=JSONstat( JSON.parse( JSON.stringify( this ) ) ) ; //Now you can safely manipulate the copy object: //the orig object will remain unaffected }, false );
It returns a jsonstat instance. When callback is specified, the jsonstat instance returned by JSONstat will be empty: the actual instance (or a JSON-stat object if instance is false) will only be accessible inside the callback function, in the this keyword.
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
Description: Gets dataset information from a jsonstat ("bundle", "collection", "dataset") instance
Public Properties:
class,
length,
id,
label,
n,
size,
value,
status,
updated,
source,
role,
note,
href,
link,
extensionSummary: 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" , function() { if( this.class==="bundle" ){ var ds1=this.Dataset( 0 ); } } );
The Dataset method can also be applied to json-stat "collection" instances if they have some embedded dataset:
JSONstat( "https://json-stat.org/samples/oecd-canada-col.json" , function() { if( this.class==="collection" ){ var ds1=this.Dataset( 0 ); } } );
For generalization's sake, it can also be applied to json-stat "dataset" instances:
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { if( this.class==="dataset" ){ window.alert( this===this.Dataset( 0 ) ); //true } } );
Description: Gets dimension information from a jsonstat instance
Summary: 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" , function() { if( this.class==="dataset" ){ //Label of the first dimension var label1=this.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" , function() { //Label of the first dimension with role "geo" var geolabel1=this.Dimension( { role : "geo" } )[0].label; } );
This boolean parameter (introduced in version 0.12.2) 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" , function() { //Array of dimension "area" category labels var arealabels=this.Dimension( "area", false ); //Same as: this.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.
Description: Gets category information from a jsonstat instance
Summary: 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" , function() { //Label of category "AU" in dimension "area" var AUlabel=this.Dimension( "area" ).Category( "AU" ).label; //"Australia" } );
Description: Gets data information from a jsonstat instance
Summary: 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 (available since version 0.10.1) 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.
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { //Value of the first observation var data0=this.Data( 0 ).value; //Same as value with the first category in each dimension var data000=this.Data( [0, 0, 0] ).value; //Value with concept "UNR", area "GR" and year "2014" var unrGR2014=this.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" , function() { //Value of the first observation var data0=this.Data( 0, false ); //Same as value with the first category in each dimension var data000=this.Data( [0, 0, 0], false ); //Value with concept "UNR", area "GR" and year "2014" var unrGR2014=this.Data( { "concept" : "UNR", "area" : "GR", "year" : "2014" }, false ); } );
Since version 0.10.3, it is possible to use an array of arrays instead of an object.
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { var unrGR2014=this.Data( [ ["concept", "UNR"], ["area", "GR"], ["year", "2014"] ] ); //Same as { "concept" : "UNR", "area" : "GR", "year" : "2014" } } );
Description: Gets item information from a jsonstat instance with class "collection"
Summary: 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" , function() { //Get the label of the first item in the collection var label1=this.Item( 0 ).label; } );
JSONstat( "https://json-stat.org/samples/collection.json" , function() { //Get the number of items with class "dataset" in the collection var dsn=this.Item( { class : "dataset" } ).length; } );
JSONstat( "https://json-stat.org/samples/collection.json" , function() { //Get the number of embedded dataset in the collection (none) var dsn=this.Item( { class : "dataset" , embedded: true } ).length; } );
Description: Converts information from a jsonstat instance into tabular form
Public Properties: —
Summary: object or array toTable ( [object opts, function callback] )
It is an object with the following optional properties:
JSONstat( "https://json-stat.org/samples/canada.json" , function() { //Column names (first row) //["country", "year", "age group", "concepts", "sex", "Value"] var cols=this.toTable( { type : "array" } )[0]; //IDs instead of labels //["country", "year", "age", "concept", "sex", "value"] cols=this.toTable( { type : "array", field : "id" } )[0]; //Labels including status //["country", "year", "age group", "concepts", "sex", "Status", "Value"] cols=this.toTable( { type : "array", status : true } )[0]; //Same but naming status as "Metadata" and value as "Data" cols=this.toTable( { type : "array", status : true, vlabel : "Data", slabel: "Metadata" } )[0]; //First data row //["Canada", "2012", "total", "population", "total", 34880.5] var row1=this.toTable( {type: "array"} )[1]; //Same including status //["Canada", "2012", "total", "population", "total", "a", 34880.5] row1=this.toTable( {type: "array", status: true} )[1]; //Same but IDs instead of labels //["CA", "2012", "T", "POP", "T", "a", 34880.5] row1=this.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" , function() { //Discard data by age in the resulting table this.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" , function() { //Discard data by age in the resulting table. //Using categories ID instead of labels. this.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" , function() { //As previous example but with type "array" //Age is the third dimension (its index is 2) this.toTable( { type : "array" , content : "id" }, function( d, i ){ if( d[2]==="T" ){ return d; } } ); } );
JSONstat( "https://json-stat.org/samples/canada.json" , function() { //As previous example but with type "object" //Age is the third dimension (its index is 2) this.toTable( { type : "object" , content : "id" }, function( d, i ){ if( d.c[2].v==="T" ){ return d; } } ); } );
The arrobj type does 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" , function() { //This will not remove the header (row 0 in type "array") but the first data row this.toTable( { type : "array" }, function( d, i ){ if( i ){ return d; } } ); } );
Because array and object type includes 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 type.
JSONstat( "https://json-stat.org/samples/canada.json" , function() { //Select only the female population by age group //Get an array of objects with only two properties (age and population) //Change scale of units this.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.
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.
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.
Description: (Available since version 0.11.0) Modifies a jsonstat instance of class "dataset" applying a filter (creates a subset)
Public Properties:
class,
length,
id,
label,
n,
size,
value,
status,
updated,
source,
role,
note,
href,
link,
extensionSummary: object Slice ( object or array filter] )
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 a an array of arrays (pairs of dimension ID / category ID)).
JSONstat("https://json-stat.org/samples/galicia.json", function(){ var subset=JSONstat( this ).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", function(){ var subset=JSONstat( this ).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.
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", function(){ var original=JSONstat( JSON.parse( JSON.stringify( this ) ) ), subset=JSONstat( this ).Slice( { "birth": "T", "age": "T", "time": "2011" } ) //*this* will be modified ; //Compare original, subset and *this* }, false //To be able to clone the original dataset );
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" , function() { var //This dataset contains extended properties ext=this.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" , function() { //First dimension var dim=this.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" , function() { //Get the URL of the first item in the collection var href1=this.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" , function() { if( this.class==="bundle" || this.class==="dataset" ){ var //"OECD" dataset (if class "bundle") ds=this.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" , function() { //Label for "AU" area (Australia) var label=this.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" , function() { if( this.length ){ ... }else{ window.alert( "Wrong response!" ); } } );
Collection, bundle, dataset or dimension links. Object of relation names.
JSONstat( "https://json-stat.org/samples/collection.json" , function() { //Get info for IANA link relation "item" in a collection http://www.iana.org/assignments/link-relations/link-relations.xhtml var items=this.link["item"]; //Same as this.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" , function() { window.alert("This dataset has " + String( this.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" , function() { //Display general dataset annotations if available var note=this.note; if( note ){ note.forEach( function( e ){ window.alert( e ); } ); } //Display annotations for Germany if available var denote=this.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" , function() { //Get the name of the first dimension with a "geo" role var geo1=this.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" , function() { //Role of the "concept" dimension var crole=this.Dimension( "concept" ).role; } );
Dimensions sizes. Array. Available since version 0.10.
Dataset or collection source. String.
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { //Dataset source var source=this.source; } );
As a property of a dataset, status of its values. Array or null.
JSONstat( "https://json-stat.org/samples/oecd.json" , function() { if( this.status ){ //Status of the 23rd value var status23=this.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" , function() { //Status of the 23rd value var status23=this.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" , function() { //First category in the first dimension with a "metric" role var metric1=this.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" , function() { if( this.updated ){ var upd=new Date( this.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" , function() { if( this.value ){ //23rd value var value23=this.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" , function() { //23rd value var value23=this.Data( 22 ).value; //Same as this.Data( 22, false ) } );
Version of the JSON-stat Javascript Toolkit. String.
var ver=JSONstat.version;
This property is not available in the ECMAScript module. If for some reason you need to check the JJT version, you can import it from export.js:
import { JSONstat, version as JSONstatVersion} from "/your-js-dir/export.js";
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4