Purpose
The charts route contains all endpoints related to the management of charts. They also allow you to retrieve chart data.
get by id
This endpoint is used to retrieve the configuration of a single chart by its id. You need to specify the id of the chart you want to retrieve in the request path.
Request:GET /api/v1/charts/{chart_id}
Response:
{
"id": "a6a49dc0-9118-41f4-bf47-f12a83b0f91a",
"user_id": "6b875d6c-7d4e-4ae3-931f-270604df1d7f",
"chart_type": "line",
"title": "My very fun chart",
"filter_from": "2023-01-01T10:10:00Z",
"filter_to": "2023-02-01T10:10:00Z",
"filter_collection": "get_per_recipient_over_time",
"date_period": "monthly",
"asset_id": null,
"budget_id": null,
"max_items": 10,
"date_range": null,
"only_positive": false,
"only_negative": false,
"top_left_x": 2,
"top_left_y": 2,
"bottom_right_x": 4,
"bottom_right_y": 6,
"dashboard_id": null,
"start_at_zero": false
}
| Property | Description | Type |
|---|---|---|
| id | the id of the chart | UUIDv4 |
| user_id | the id of the user owning this chart | UUIDv4 |
| chart_type | the type of the chart, current used values are line, pie and table | string |
| title | the title of the chart | string |
| filter_from | the default value for the from field | timestamp? |
| filter_to | the default value for the to field | timestamp? |
| filter_collection | the collection to use for this chart | string? |
| date_period | the default value for the period field, defines over which period values get grouped together | string? |
| asset_id | the id of the asset that this chart relates to | UUIDv4? |
| budget_id | the id of the budget that this chart relates to | UUIDv4? |
| max_items | the maximum number of items, like slices in the pie | number? |
| date_range | the default value for the range field, goes from 0 (last 28 days) to 7 (total) | number? |
| only_positive | only return datasets were the last value is positive | boolean? |
| only_negative | only return datasets were the last value is negative | boolean? |
| top_left_x | value used for positioning chart on the dashboard grid | number? |
| top_left_y | value used for positioning chart on the dashboard grid | number? |
| bottom_right_x | value used for positioning chart on the dashboard grid | number? |
| bottom_right_y | value used for positioning chart on the dashboard grid | number? |
| dashboard_id | the id of the dashboard this chart belongs to, in reality always null | UUIDv4? |
| start_at_zero | for line charts; if the calculation should only use transactions from the time period | boolean? |
get all charts in dashboard
This endpoint is used to retrieve the configuration of all charts that are part of a particular dashboard. You need to specify the id of the dashboard you want to retrieve the charts of in the request path.
Request:GET /api/v1/dashboards/{dashboard_id}/charts
Response:
[
{
"id": "a6a49dc0-9118-41f4-bf47-f12a83b0f91a",
"user_id": "6b875d6c-7d4e-4ae3-931f-270604df1d7f",
"chart_type": "line",
"title": "My very fun chart",
"filter_from": "2023-01-01T10:10:00Z",
"filter_to": "2023-02-01T10:10:00Z",
"filter_collection": "get_per_recipient_over_time",
"date_period": "monthly",
"asset_id": null,
"budget_id": null,
"max_items": 10,
"date_range": null,
"only_positive": false,
"only_negative": false,
"top_left_x": 2,
"top_left_y": 2,
"bottom_right_x": 4,
"bottom_right_y": 6,
"dashboard_id": null,
"start_at_zero": false
}
]
| Property | Description | Type |
|---|---|---|
| id | the id of the chart | UUIDv4 |
| user_id | the id of the user owning this chart | UUIDv4 |
| chart_type | the type of the chart, current used values are line, pie and table | string |
| title | the title of the chart | string |
| filter_from | the default value for the from field | timestamp? |
| filter_to | the default value for the to field | timestamp? |
| filter_collection | the collection to use for this chart | string? |
| date_period | the default value for the period field, defines over which period values get grouped together | string? |
| asset_id | the id of the asset that this chart relates to | UUIDv4? |
| budget_id | the id of the budget that this chart relates to | UUIDv4? |
| max_items | the maximum number of items, like slices in the pie | number? |
| date_range | the default value for the range field, goes from 0 (last 28 days) to 7 (total) | number? |
| only_positive | only return datasets were the last value is positive | boolean? |
| only_negative | only return datasets were the last value is negative | boolean? |
| top_left_x | value used for positioning chart on the dashboard grid | number? |
| top_left_y | value used for positioning chart on the dashboard grid | number? |
| bottom_right_x | value used for positioning chart on the dashboard grid | number? |
| bottom_right_y | value used for positioning chart on the dashboard grid | number? |
| dashboard_id | the id of the dashboard this chart belongs to, in reality always null | UUIDv4? |
| start_at_zero | for line charts; if the calculation should only use transactions from the time period | boolean? |
get data of chart by id
This endpoint is used to retrieve the data of a chart that has been created previously. You need to specify the id of the chart you want to retrieve the data of in the request path. You can use request parameters to override the default parameters of the charts configuration. Possible properties are: from_date, to_date, date_period, asset_id, budget_id, max_items, date_range, only_positive, only_negative, filter_collection.
Request:GET /api/v1/charts/{chart_id}/data
Response:
{
"datasets": [
{
"label": "My Dataset label",
"data": [
{
"name": null,
"timestamp": "2024-01-01",
"value": -12.34,
"label": "-12.34€"
}
]
}
]
}
| Property | Description | Type |
|---|---|---|
| datasets | array of datasets | dataset |
Dataset:
| Property | Description | Type |
|---|---|---|
| label | the label of the dataset | string |
| data | array of chart data | datapoint |
Datapoint:
| Property | Description | Type |
|---|---|---|
| name | the name of the datapoint | string |
| timestamp | the timestamp of the datapoint | timestamp |
| value | the numerical value of the datapoint | number |
| label | the label of the datapoint | label |
get data of chart by filter collection
This endpoint is used to retrieve the data for a chart on demand, without having to first create a chart. You need to specify the filter collection of the chart you want to retrieve the data of in the request path. You can use request parameters to override the default parameters. Possible properties are: from_date, to_date, date_period, asset_id, budget_id, max_items, date_range, only_positive, only_negative, filter_collection.
Request:GET /api/v1/charts/by_collection/{filter_collection}
Response:
{
"datasets": [
{
"label": "My Dataset label",
"data": [
{
"name": null,
"timestamp": "2024-01-01",
"value": -12.34,
"label": "-12.34€"
}
]
}
]
}
| Property | Description | Type |
|---|---|---|
| datasets | array of datasets | dataset |
Dataset:
| Property | Description | Type |
|---|---|---|
| label | the label of the dataset | string |
| data | array of chart data | datapoint |
Datapoint:
| Property | Description | Type |
|---|---|---|
| name | the name of the datapoint | string |
| timestamp | the timestamp of the datapoint | timestamp |
| value | the numerical value of the datapoint | number |
| label | the label of the datapoint | string |
create chart
This endpoint is used to create new charts.
Request:POST /api/v1/charts
{
"chart_type": "line",
"title": "My very fun chart",
"filter_from": "2023-01-01T10:10:00Z",
"filter_to": "2023-02-01T10:10:00Z",
"filter_collection": "get_per_recipient_over_time",
"date_period": "monthly",
"max_items": 10,
"date_range": null,
"only_positive": false,
"only_negative": false,
"top_left_x": 2,
"top_left_y": 2,
"bottom_right_x": 4,
"bottom_right_y": 6,
"dashboard_id": null,
"start_at_zero": false
}
| Property | Description | Type |
|---|---|---|
| chart_type | the type of the chart, current used values are line, pie and table | string |
| title | the title of the chart | string |
| filter_from | the default value for the from field | timestamp? |
| filter_to | the default value for the to field | timestamp? |
| filter_collection | the collection to use for this chart | string? |
| date_period | the default value for the period field, defines over which period values get grouped together | string? |
| max_items | the maximum number of items, like slices in the pie | number? |
| date_range | the default value for the range field, goes from 0 (last 28 days) to 7 (total) | number? |
| only_positive | only return datasets were the last value is positive | boolean? |
| only_negative | only return datasets were the last value is negative | boolean? |
| top_left_x | value used for positioning chart on the dashboard grid | number? |
| top_left_y | value used for positioning chart on the dashboard grid | number? |
| bottom_right_x | value used for positioning chart on the dashboard grid | number? |
| bottom_right_y | value used for positioning chart on the dashboard grid | number? |
| dashboard_id | the id of the dashboard this chart should be added to | UUIDv4? |
| start_at_zero | for line charts; if the calculation should only use transactions from the time period | boolean? |
Response:
{
"id": "a6a49dc0-9118-41f4-bf47-f12a83b0f91a"
}
modify chart
This endpoint is used to modify an existing chart.
You need to specify the id of the chart you want to modify in the request path.
Request:PUT /api/v1/charts
{
"chart_type": "line",
"title": "My very fun chart",
"filter_from": "2023-01-01T10:10:00Z",
"filter_to": "2023-02-01T10:10:00Z",
"filter_collection": "get_per_recipient_over_time",
"date_period": "monthly",
"max_items": 10,
"date_range": null,
"only_positive": false,
"only_negative": false,
"top_left_x": 2,
"top_left_y": 2,
"bottom_right_x": 4,
"bottom_right_y": 6,
"dashboard_id": null,
"start_at_zero": false
}
| Property | Description | Type |
|---|---|---|
| chart_type | the type of the chart, current used values are line, pie and table | string |
| title | the title of the chart | string |
| filter_from | the default value for the from field | timestamp? |
| filter_to | the default value for the to field | timestamp? |
| filter_collection | the collection to use for this chart | string? |
| date_period | the default value for the period field, defines over which period values get grouped together | string? |
| max_items | the maximum number of items, like slices in the pie | number? |
| date_range | the default value for the range field, goes from 0 (last 28 days) to 7 (total) | number? |
| only_positive | only return datasets were the last value is positive | boolean? |
| only_negative | only return datasets were the last value is negative | boolean? |
| top_left_x | value used for positioning chart on the dashboard grid | number? |
| top_left_y | value used for positioning chart on the dashboard grid | number? |
| bottom_right_x | value used for positioning chart on the dashboard grid | number? |
| bottom_right_y | value used for positioning chart on the dashboard grid | number? |
| dashboard_id | the id of the dashboard this chart should be added to | UUIDv4? |
| start_at_zero | for line charts; if the calculation should only use transactions from the time period | boolean? |
delete chart
This endpoint is used to delete an existing chart. You need to specify the id of the chart you want to delete in the request path.
Request:DELETE /api/v1/charts/{budget_id}