Skip to content

Commit 85d0f49

Browse files
badosabadosa
authored
Update README.md
1 parent 8895a8e commit 85d0f49

File tree

1 file changed

+1
-169
lines changed

1 file changed

+1
-169
lines changed

‎euro/README.md‎

Lines changed: 1 addition & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -1,171 +1,3 @@
11
# JSON-stat for Eurostat
22

3-
**This package is experimental**. Please, wait till v.1 and till there's a proper API documentation to use this package.
4-
5-
JSON-stat for Eurostat (**Euro**JSON**stat**, for short) is a JavaScript library to deal with Eurostat's [JSON-stat](https://json-stat.org/format/) API (requests and responses). **Euro**JSON**stat** is part of the [JSON-stat Toolkit](https://json-stat.com). It is meant to complement, not replace, Eurostat's own set of libraries ([eurostat.js](https://github.com/eurostat/eurostat.js)). While the latter addresses many issues, **Euro**JSON**stat** library is focused on JSON-stat-related ones.
6-
7-
For instance, Eurostat does not include roles in its datasets. **Euro**JSON**stat** offers a method to retrieve role-enriched datasets (*fetchDataset*) or allows you to add role information to an already retrieved Eurostat dataset (*setRole*). This is possible because Eurostat uses standardized dimension names.
8-
9-
JSON-stat does not provide a single way to describe status symbols. Instead, if offers the [extension](https://json-stat.org/format/#extension) property to allow providers to customize their JSON-stat responses to their needs. Eurostat uses a standardized way to attach a label to each status symbol. **Euro**JSON**stat** offers a method to retrieve such information (*getStatusLabel*).
10-
11-
A design principle of the JSON-stat format is the strict separation of data and metadata in order to allow the use of exactly the same structure for full (data and metadata) responses, data-only responses and metadata-only responses. Unfortunately, Eurostat does not support metadata-only responses (responses without *value* and *status*). **Euro**JSON**stat** offers ways to *try* to avoid this limitation (*fetchFullQuery*). It also includes a function to convert a full explicit query (see later) into a metadata-only dataset instance (*getEmptyDataset*).
12-
13-
* [Queries](#queries)
14-
* [Filters](#filters)
15-
* [Sample code](#sample-code)
16-
* [Resources](#resources)
17-
18-
## Queries
19-
20-
Queries are a special kind of object used in many **Euro**JSON**stat** functions as an argument (input query) but also as a return value (output query).
21-
22-
A query must contain a dataset property with a valid Eurostat dataset code:
23-
24-
```js
25-
{
26-
"dataset": "une_rt_a"
27-
}
28-
```
29-
30-
A query can optionally request information on one of the Eurostat-supported languages (default is English). A specific Eurostat API version can also be requested (default is 2.1):
31-
32-
```js
33-
{
34-
"dataset": "une_rt_a",
35-
"lang": "fr",
36-
"version": "2.1"
37-
}
38-
```
39-
40-
Queries can filter data in datasets. For instance, dataset *une_rt_a* for Austria in years 2017-2018 would require this query:
41-
42-
```js
43-
{
44-
"dataset": "une_rt_a",
45-
"filter": {
46-
"geo": ["AT"],
47-
"time": ["2017", "2018"]
48-
}
49-
}
50-
```
51-
52-
**Euro**JSON**stat** functions that return queries always include a *class* property with value "query" and can include label information. For instance, the previous **implicit query** (an input query that relies on some default parameters and values) can be tried to be translated into an **explicit query** (an equivalent query that includes all values requested explicitly or implicitly) using the *fetchQuery* function:
53-
54-
```js
55-
EuroJSONstat.fetchQuery(iq, false).then(eq=>{
56-
if(eq.class!=="error"){
57-
console.log(eq);
58-
}
59-
});
60-
```
61-
62-
*fetchQuery* returns metadata-enriched queries:
63-
64-
```js
65-
{
66-
"class": "query",
67-
"dataset": "une_rt_a",
68-
"filter": {
69-
"age": ["TOTAL", "Y25-74", "Y_LT25"],
70-
"unit": ["PC_ACT", "PC_POP", "THS_PER"],
71-
"sex": ["F", "M", "T"],
72-
"geo": ["AT"],
73-
"time": ["2017", "2018"]
74-
},
75-
"label": {
76-
"dataset": "Unemployment by sex and age - annual average",
77-
"dimension": {
78-
"age": "age",
79-
"unit": "unit",
80-
"sex": "sex",
81-
"geo": "geo",
82-
"time": "time"
83-
},
84-
"category": {
85-
"age": ["Total", "From 25 to 74 years", "Less than 25 years"],
86-
"unit": ["Percentage of active population", "Percentage of total population", "Thousand persons"],
87-
"sex": ["Females", "Males", "Total"],
88-
"geo": ["Austria"],
89-
"time": ["2018"]
90-
}
91-
},
92-
"lang": "en",
93-
"version": "2.1"
94-
}
95-
```
96-
97-
A **full explicit query** is a query that exposes all the dimensions and categories of a non-filtered dataset.
98-
99-
## Filters
100-
101-
Another special kind of object are filters. The "filter" property of queries are filters. They are made of parameters (properties of the filter object), usually dimension names, and a list of valid values (array), usually category names. For example:
102-
103-
```js
104-
{
105-
"geo": ["AT"],
106-
"time": ["2017", "2018"]
107-
}
108-
```
109-
110-
Some **Euro**JSON**stat** functions accept filters as arguments. For example, the *addParamQuery* can create a new query from a query and a filter:
111-
112-
```js
113-
EuroJSONstat.addParamQuery(
114-
//query
115-
{
116-
"dataset": "une_rt_a",
117-
"filter": {
118-
"geo": ["AT"],
119-
"time": ["2017", "2018"]
120-
}
121-
},
122-
//filter
123-
{
124-
"age": ["TOTAL"]
125-
}
126-
);
127-
```
128-
129-
## Sample code
130-
131-
```js
132-
//A query
133-
const query={
134-
dataset: "une_rt_a"
135-
};
136-
137-
//Queries can be modified easily
138-
139-
//Add filter (Austria 2018) to previous query
140-
const fquery=EuroJSONstat.addParamQuery(query, { geo: ["AT"], time: ["2018"] });
141-
console.log(fquery);
142-
143-
//Translate query into Eurostat end-point
144-
const url=EuroJSONstat.getURL(fquery);
145-
console.log(url);
146-
147-
//Remove time and geo from previous filtered query
148-
const uquery=EuroJSONstat.removeParamQuery(fquery, ["time", "geo"]);
149-
console.log(uquery);
150-
//To remove time, removeTimeQuery() is more powerful than generic removeParamQuery()
151-
152-
//Retrieve a Eurostat standardized JSON-stat dataset using a query
153-
EuroJSONstat.fetchDataset(uquery).then(ds=>{
154-
if(ds.class==="dataset"){
155-
console.log(`"${query.dataset}" dataset has label "${ds.label}".`);
156-
157-
const status=ds.Data(0).status;
158-
159-
//Eurostat status meaning is easily retrieved
160-
console.log(`Status symbol of first observation is "${status}" which means "${EuroJSONstat.getStatusLabel(ds, status)}".`);
161-
162-
//When standardized, Eurostat's datasets are enriched with roles
163-
console.log(`Classification dimensions: ${ds.role.classification}`);
164-
}
165-
});
166-
```
167-
168-
## Resources
169-
170-
* [Installation](https://github.com/badosa/JSON-stat/blob/master/euro/docs/install.md)
171-
* [API Reference](https://github.com/badosa/JSON-stat/blob/master/euro/docs/api.md)
3+
This is the repository of the experimental release (version 0) of *JSON-stat for Eurostat* (**Euro**JSON**stat**, for short). This version has been superseded by **version 1**, which is available at **new repository** ([github.com/jsonstat/euro](https://github.com/jsonstat/euro)).

0 commit comments

Comments
 (0)