Skip to content

API Reference

Jump to bottom
Xavier Badosa edited this page Aug 12, 2015 · 75 revisions

Wiki ▸ API Reference

Methods

By type

By hierarchy

		<li>
			Dataset responses: <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#class">class</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#length">length</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#id">id</a>,
			<a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#label">label</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#n">n</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#value">value</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#status">status</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#updated">updated</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#source">source</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#role">role</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#note">note</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#href">href</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#link">link</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#extension">extension</a>
			<ul>
				<li><strong><a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#dimension">Dimension()</a></strong>: <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#class">class</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#length">length</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#id">id</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#label">label</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#role">role</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#hierarchy">hierarchy</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#note">note</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#href">href</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#link">link</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#extension">extension</a>
					<ul>
						<li><strong><a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#category">Category()</a></strong>: <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#length">length</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#id">id</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#label">label</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#coordinates">coordinates</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#unit">unit</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#note">note</a></li>
					</ul>
				</li>
				<li><strong><a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#data">Data()</a></strong>: <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#value">value</a>, <a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#status">status</a></li>
				<li><strong><a href="https://github.com/badosa/JSON-stat/wiki/API-Reference#totable">toTable()</a></strong>
			</ul>
		</li>
	</ul>
</li>

Public Properties

class, coordinates, error, extension, hierarchy, href, id, label, length, link, n, note, role, source, status, unit, updated, value, version

Reading

JSONstat()

Parent: none
Description: Creates an internal jsonstat object from an external input in the JSON-stat format
Public Properties: class, length, id, error, label, n, value, status, updated, source, role, note, href, link, extension
Summary: object JSONstat ( object or string resp [, function callback] )
***

Parameters

resp (required)

It can be an object in the JSON-stat format or a string representing a URL.

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 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 no callback is specified (deprecated), the connection will be synchronous.

callback

It is a function.

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 object of class jsonstat is assigned to the this keyword.

JSONstat( "http://json-stat.org/samples/oecd-ds.json" ,
   function() {
      console.log( this.length );
   }
)

If resp is an object, callback is ignored.

Returned Value

It returns a jsonstat object. When callback is specified, the object returned by JSONstat will be empty (the actual object is only accessible inside the callback function, in the this keyword).

The public properties of this object 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, value, status, updated, source, role, note, href, link, extension

Traversing

Dataset()

Parent: JSONstat
Description: Gets dataset information from an internal jsonstat object with class "bundle" (for generalization's sake, it can also be applied to objects with class "dataset")
Public Properties: class, length, id, label, n, value, status, updated, source, role, note, href, link, extension
Summary: object or array Dataset ( [integer or string dsid] )
***

Parameters

dsid

It can be a positive integer (access by index in the datasets id array) or a string (access by ID).

Returned Value

When a valid dsid is specified, it returns a jsonstat object. If dsid is not valid, a null is returned. If dsid is not specified, it will return an array of jsonstat objects: one for each dataset.

Dimension()

Parent: Dataset
Description: Gets dimension information from an internal jsonstat object
Public Properties: class, length, id, label, role, hierarchy, note, href, link, extension
Summary: object or array Dimension ( [integer, string or object dimid] )
***

Parameters

dimid

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.

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.

Returned Value

When a valid dimid is specified, it returns a jsonstat object. If dimid is not valid, a null is returned. If dimid is not specified, it returns an array of jsonstat objects: one for each dimension. If dimid is a valid object, it returns an array of jsonstat objects: one for each dimension with the selected role.

Category()

Parent: Dimension
Description: Gets category information from an internal jsonstat object
Public Properties: length, id, label, coordinates, unit, note
Summary: object or array Dimension ( [integer or string catid] )
***

Parameters

catid

It can be a positive integer (access by index in the categories id array) or a string (access by ID).

Returned Value

When a valid catid is specified, it returns a jsonstat object. If catid is not valid, a null is returned. If catid is not specified, it will return an array of jsonstat objects: one for each category.

Data()

Parent: Dataset
Description: Gets data information from an internal jsonstat object
Public Properties: value, status
Summary: object or array Data ( [integer, array or object dataid] )
***

Parameters

dataid

It can be a positive integer (by cell index in the value array), an array (by dimensions indices) or an object (by dimensions IDs).

Examples:

j.Data ( 10 )
j.Data ( [ 0, 3, 5 ] )
j.Data ( { "concept" : "UNR", "area" : "GR", "year" : "2014" } )

Returned Value

The returned 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 not specified, the result is an array of value-status objects (one object per cell in the dataset).

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

Transforming

toTable()

Parent: Dataset
Description: Converts information from an internal jsonstat object into tabular form
Public Properties: —
Summary: object or array toTable ( [object opts, function callback] )
***

Parameters

opts

It is an object with the following optional properties:

  • type: String (arrobj, object, array). Default value is array. It determines the form of the returned value.
  • status: Boolean. Default value is false. It determines whether the status of each value is included in the returned value.
  • content: String (id, label). Default value is label. It determines whether categories are identified in the returned value by label or by ID.
  • field: String (id, label). Default value is label. Only available when type is object or array. It determines whether dimensions, value and status are identified in the returned value by label or by ID.
  • vlabel: String. Default value is Value. Only available when type is object or array. It determines the label of the value field.
  • slabel: String. Default value is Status. Only available when type is object or array and status is true. It determines the label of the status field.

Examples:

j.toTable( {type: "array"} )[0]
// ["Country", "Year", "Age group", "Population and %", "Sex", "Value"]

j.toTable( {type: "array", field: "id"} )[0]
// ["country", "year", "age", "concept", "sex", "value"]

j.toTable( {type: "array", status: true} )[0]
// ["Country", "Year", "Age group", "Population and %", "Sex", "Status", "Value"]

j.toTable( {type: "array", status: true, vlabel: "Data", slabel: "Metadata"} )[0]
// ["Country", "Year", "Age group", "Population and %", "Sex", "Metadata", "Data"]

j.toTable( {type: "array"} )[1]
// ["Canada", "2012", "Total", "Persons (thousands)", "Total", 34880.5]

j.toTable( {type: "array", status: true} )[1]
// ["Canada", "2012", "Total", "Persons (thousands)", "Total", "a", 34880.5]

j.toTable( {type: "array", status: true, content: "id"} )[1]
// ["CA", "2012", "T", "POP", "T", "a", 34880.5]
callback

It is a function used to transform the returned value.

Even though toTable can expose a table using different structures depending on type, it always includes some sort of array for cells. callback will be invoked for each element of the cells array, passing two parameters: the element and its index. The this keyword in callback is the dataset information as a jsonstat object.

Example:

// 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 cells 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.

// 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 cells array.

// 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;
      }
   }
)
// 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 type does not return a table header, but array and object type do: callback cannot act on the header, only on the cells array.

// This will not remove the header (row 0 in type "array") but the first cell value
j.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 cells 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.

// 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 };
      }
   }
)

Returned Value

It depends on the type specified in the opts parameter.

arrobj type

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.

[
   { "area" : "Australia", "year" : "2003", "concept" : "Unemployment rate", "value" : 5.943826289 },
   { "area" : "Australia", "year" : "2004", "concept" : "Unemployment rate", "value" : 5.39663128 },
   ...
]
array type

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.

[
   [ "Area", "Year", "Concept", "Value" ],
   [ "Australia", "2003", "Unemployment rate", 5.943826289 ],
  2 ...
]
object type

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.

Item()

Parent: JSONstat
Description: Gets item information from an internal jsonstat object with class "collection"
Public Properties: class, href, label, extension
Summary: object or array Item ( [integer itemid] )
***

Parameters

itemid

It is a positive integer (access to item information by index).

Returned Value

When a valid itemid is specified, it returns a jsonstat object. If itemid is an integer but out of range, a null is returned. If itemid is not specified or is not an integer, it will return an array of jsonstat objects: one for each item.

Public Properties

class

Response class. String ("collection", "bundle", "dataset", "dimension").

coordinates

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.

error

Optional error information. Object. The properties of this object depend on the provider.

extension

Collection, dataset, dimension or item extended information. Object. The properties of this object depend on the provider.

hierarchy

True if there is information about the relationship between the categories in the dimension. Boolean.

href

Collection, bundle, dataset or dimension URL.

id

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.

j.id
j.Dataset(0).id
j.Dataset(0).Dimension(0).id
j.Dataset(0).Dimension(0).Category(0).id

label

Collection, dataset, dimension, category or item label. String.

j.label //class "dataset" or "collection"
j.Dataset(0).label
j.Item(0).label
j.Dataset(0).Dimension(0).label
j.Dataset(0).Dimension(0).Category(0).label

length

Number of datasets, dimensions, categories, category children or items. Integer.

j.length
j.Dataset(0).length
j.Dataset(0).Dimension(0).length
j.Dataset(0).Dimension(0).Category(0).length

You should always check for length>0 before further processing.

link

Collection, bundle, dataset or dimension links. Object of relation names.

n

Number of values in the dataset. Integer. It is the number of cells in the cube, even if they are empty (missing values).

note

Dataset, dimension, category or collection annotations. Array of strings except category annotations, which are an object of strings.

role

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

Dimension role. String (time, geo, metric; otherwise, classification) or null (when role information not included in the response).

source

Dataset or collection source. String.

status

As a property of a dataset, status of its values. Array or null.

As a property of a datum, status of its value. String or null if not provided.

unit

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.

updated

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.

value

As a property of a dataset, dataset values. Array.

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

version

Version of the JSON-stat Javascript Toolkit. String.

JSONstat.version

Clone this wiki locally