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
}
PropertyDescriptionType
idthe id of the chartUUIDv4
user_idthe id of the user owning this chartUUIDv4
chart_typethe type of the chart, current used values are line, pie and tablestring
titlethe title of the chartstring
filter_fromthe default value for the from fieldtimestamp?
filter_tothe default value for the to fieldtimestamp?
filter_collectionthe collection to use for this chartstring?
date_periodthe default value for the period field, defines over which period values get grouped togetherstring?
asset_idthe id of the asset that this chart relates toUUIDv4?
budget_idthe id of the budget that this chart relates toUUIDv4?
max_itemsthe maximum number of items, like slices in the pienumber?
date_rangethe default value for the range field, goes from 0 (last 28 days) to 7 (total)number?
only_positiveonly return datasets were the last value is positiveboolean?
only_negativeonly return datasets were the last value is negativeboolean?
top_left_xvalue used for positioning chart on the dashboard gridnumber?
top_left_yvalue used for positioning chart on the dashboard gridnumber?
bottom_right_xvalue used for positioning chart on the dashboard gridnumber?
bottom_right_yvalue used for positioning chart on the dashboard gridnumber?
dashboard_idthe id of the dashboard this chart belongs to, in reality always nullUUIDv4?
start_at_zerofor line charts; if the calculation should only use transactions from the time periodboolean?

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
    }
]
PropertyDescriptionType
idthe id of the chartUUIDv4
user_idthe id of the user owning this chartUUIDv4
chart_typethe type of the chart, current used values are line, pie and tablestring
titlethe title of the chartstring
filter_fromthe default value for the from fieldtimestamp?
filter_tothe default value for the to fieldtimestamp?
filter_collectionthe collection to use for this chartstring?
date_periodthe default value for the period field, defines over which period values get grouped togetherstring?
asset_idthe id of the asset that this chart relates toUUIDv4?
budget_idthe id of the budget that this chart relates toUUIDv4?
max_itemsthe maximum number of items, like slices in the pienumber?
date_rangethe default value for the range field, goes from 0 (last 28 days) to 7 (total)number?
only_positiveonly return datasets were the last value is positiveboolean?
only_negativeonly return datasets were the last value is negativeboolean?
top_left_xvalue used for positioning chart on the dashboard gridnumber?
top_left_yvalue used for positioning chart on the dashboard gridnumber?
bottom_right_xvalue used for positioning chart on the dashboard gridnumber?
bottom_right_yvalue used for positioning chart on the dashboard gridnumber?
dashboard_idthe id of the dashboard this chart belongs to, in reality always nullUUIDv4?
start_at_zerofor line charts; if the calculation should only use transactions from the time periodboolean?

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€"
                }
            ]
        }
    ]
}
PropertyDescriptionType
datasetsarray of datasetsdataset

Dataset:

PropertyDescriptionType
labelthe label of the datasetstring
dataarray of chart datadatapoint

Datapoint:

PropertyDescriptionType
namethe name of the datapointstring
timestampthe timestamp of the datapointtimestamp
valuethe numerical value of the datapointnumber
labelthe label of the datapointlabel

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€"
                }
            ]
        }
    ]
}
PropertyDescriptionType
datasetsarray of datasetsdataset

Dataset:

PropertyDescriptionType
labelthe label of the datasetstring
dataarray of chart datadatapoint

Datapoint:

PropertyDescriptionType
namethe name of the datapointstring
timestampthe timestamp of the datapointtimestamp
valuethe numerical value of the datapointnumber
labelthe label of the datapointstring

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
}
PropertyDescriptionType
chart_typethe type of the chart, current used values are line, pie and tablestring
titlethe title of the chartstring
filter_fromthe default value for the from fieldtimestamp?
filter_tothe default value for the to fieldtimestamp?
filter_collectionthe collection to use for this chartstring?
date_periodthe default value for the period field, defines over which period values get grouped togetherstring?
max_itemsthe maximum number of items, like slices in the pienumber?
date_rangethe default value for the range field, goes from 0 (last 28 days) to 7 (total)number?
only_positiveonly return datasets were the last value is positiveboolean?
only_negativeonly return datasets were the last value is negativeboolean?
top_left_xvalue used for positioning chart on the dashboard gridnumber?
top_left_yvalue used for positioning chart on the dashboard gridnumber?
bottom_right_xvalue used for positioning chart on the dashboard gridnumber?
bottom_right_yvalue used for positioning chart on the dashboard gridnumber?
dashboard_idthe id of the dashboard this chart should be added toUUIDv4?
start_at_zerofor line charts; if the calculation should only use transactions from the time periodboolean?

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
}
PropertyDescriptionType
chart_typethe type of the chart, current used values are line, pie and tablestring
titlethe title of the chartstring
filter_fromthe default value for the from fieldtimestamp?
filter_tothe default value for the to fieldtimestamp?
filter_collectionthe collection to use for this chartstring?
date_periodthe default value for the period field, defines over which period values get grouped togetherstring?
max_itemsthe maximum number of items, like slices in the pienumber?
date_rangethe default value for the range field, goes from 0 (last 28 days) to 7 (total)number?
only_positiveonly return datasets were the last value is positiveboolean?
only_negativeonly return datasets were the last value is negativeboolean?
top_left_xvalue used for positioning chart on the dashboard gridnumber?
top_left_yvalue used for positioning chart on the dashboard gridnumber?
bottom_right_xvalue used for positioning chart on the dashboard gridnumber?
bottom_right_yvalue used for positioning chart on the dashboard gridnumber?
dashboard_idthe id of the dashboard this chart should be added toUUIDv4?
start_at_zerofor line charts; if the calculation should only use transactions from the time periodboolean?

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}