Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
---
layout: page
title: Input/Output
permalink: /io
---
Depending on the requested data type the API offers some Input/Output processing.
In case of `quantity` datasets a client might request a rendered chart instead
of raw data.
The following sections list currently supported I/O operations.
- TOC
{:toc}
## Chart Rendering
{:.n52-callout .n52-callout-info}
Chart rendering is only supported for `quantity` types.
The following diagram types are available and can be set via style options:
* line charts
* bar charts
Styles can be used whereever a chart is rendered. It does not matter if you request
an image or a report (which embeds the chart).
### Line Charts
The following style properties can be set.
{:.table}
Property | Description
-----------|------------
`lineType` | The line style. Possible values are `solid`, `dotted` or `dashed`
`width` | The thickness of a line as integer, dash gap, point size (dependend on the chart type to be rendered)
`color` | A 6-digit hex color value, e.g. `#5f5f5f`
**Example**
### Bar Charts
The following style properties can be set.
{:.table}
Property | Description
-----------|------------
`interval` | The time period a bar shall represent. Possible values are `byDay`, `byWeek`, `byMonth`.
`width` | Value between `0` and `1`, which defines the bar width in percent (`width=1` means maximum width, i.e. bar next to bar).
`color` | A 6-digit hex color value, e.g. `#5f5f5f`
**Example**
If you are interested in the PNG output you can either parse it from your
favorite programming language. For a quick review you can use Curl from command line
(adapt parameters as needed, e.g. if you want a PDF report instead):
```
curl -X POST -d 'PASTE IN HERE YOUR POST REQUEST' \
-H "content-type:application/json" -H "accept:image/png" \
http://localhost:8080/api/v1/timeseries/getData > img.png
```
## Generalizing Raw Data
{: .n52-callout .n52-callout-info}
Chart rendering is only supported for `quantity` types.
Depending on sampling resolution and timespan timeseries data can be huge. Generalizing data can make
sense in more than just a low bandwidth use case (e.g. smoothing the curve).
Generalization can be enabled by `generalize=true` query parameter. By default generalization behaviour
is set to `false`. The API currently supports two generalization algorithms.
### Largest-Triangle-Three Bucket Downsampling (default)
Downsamples to a fix amount of output values
([Details](http://skemman.is/stream/get/1946/15343/37285/3/SS_MSthesis.pdf)). This is the default
algorithm chosen, when `generalizing_algorithm` parameter is missing.
Parameters
* `generalize=true`
* `generalizing_algorithm=lttb`
* `threshold={int-value}` (default is `200`)
### Douglas-Peucker Downsampling
Downsamples timeseries values by using a threshold value
([Details](http://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm)).
Parameters
* `generalize=true`
* `generalizing_algorithm=dp`
* `tolerance_value={double-value}` (default is 0.1)
## Formatting Raw Data
{:.n52-callout .n52-callout-info}
Chart rendering is only supported for `quantity` types.
Raw data can be requested in a specific format. This can be useful if you work with a specific chart API
and want to avoid to convert data outout from one format to another. Possible formats are:
* `tvp` (the default)
* `highchart`
To retrieve extra reference values (if available for that timeseries) valid for the requested timespan just
add `expand=true`.
{:.n52-callout .n52-callout-info}
Serving arbitrary formats is limited. Most probably you have to combine timeseries metadata and the actual
data differently within the used API. Please refer to the actual data output so that it can be used as
intended by the 3rd party API.
### TVP Format (default)
The format returns timeseries data as time-value tuples.
**Example (single dataset)**
```
{
"values": [
{
"timestamp": 1376524800000,
"value": 433.0
},
{
"timestamp": 1376524860000,
"value": 432.4
},
{
"timestamp": 1376524920000,
"value": 432.0
},
{
"timestamp": 1376524980000,
"value": 431.1
}
]
}
```
**Example (multiple datasets)**
```
{
"ts_ad3edeff973ab62e39f76c14f95d1e82": {
"values": []
},
"ts_c8ed5ddbb89c19b2e385de23eecbde98": {
"values": [
{
"timestamp": 1376589600000,
"value": 546
},
{
"timestamp": 1376589660000,
"value": 546.6
},
{
"timestamp": 1376589720000,
"value": 547
}
]
}
}
```
{:.n52-callout .n52-callout-info}
Please note that when adding expanded=true, reference values will be added as
a dataset on their own. You can track reference values with the corresponding identifiers
available from the dataset metadata.
### Highchart Format
The format returns timeseries data in [Highcharts series format](http://api.highcharts.com/highcharts#series).
To add metadata or a readable dataset name you will have to replace the `datasetId` with a
readable label taken from the Dataset metadata.
**Example (single dataset)**
```{
"name": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
"data": [
[
1376524800000,
433.3
],
[
1376524860000,
432.4
],
[
1376524920000,
432.1
]
]
}
```
**Example (multiple datasets)**
```
[
{
"name": "ts_ad3edeff973ab62e39f76c14f95d1e82",
"data": []
},
{
"name": "ts_c8ed5ddbb89c19b2e385de23eecbde98",
"data": [
[
1376589600000,
546
],
[
1376589660000,
546.6
],
[
1376589720000,
547
],
[
1376589780000,
548
]
]
}
]
```
