Charts API

Get chart-ready financial data for visualization and reporting

The Charts API provides pre-formatted data structures designed for creating financial charts and visualizations.

Overview

Chart endpoints return time-series data optimized for graphing libraries. Data includes:

• Date-indexed values for time-series charts
• Currency information for proper formatting
• Primary currency conversion when enabled
• Period-based grouping (daily, weekly, monthly)

Chart data is returned in a format compatible with popular JavaScript charting libraries like Chart.js and similar frameworks.

Account Charts

Visualize account balances over time.

Base Path

/api/v1/chart/account

Get Account Overview Chart

Retrieve balance data for accounts over a specified period.

Request

curl -X GET "https://your-firefly-instance.com/api/v1/chart/account/overview?start=2024-01-01&end=2024-12-31&accounts=1,2,3" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

start · date · required

Start date in YYYY-MM-DD format

end · date · required

End date in YYYY-MM-DD format

accounts · string · required

Comma-separated list of account IDs

period · string · default: "1D"

Time period for data points. Options: 1D (daily), 1W (weekly), 1M (monthly), 1Y (yearly)

label · string

Account name for the chart legend

currency_id · string

ID of the account’s currency

currency_code · string

Currency code (USD, EUR, etc.)

currency_symbol · string

Currency symbol ($, €, etc.)

currency_decimal_places · integer

Number of decimal places for the currency

type · string

Chart type (typically “line” for account balances)

period · string

Period interval used for data points

entries · object

Object with ISO date strings as keys and balance amounts as values

pc_entries · object

Primary currency converted values (when conversion is enabled)

Balance Charts

Visualize overall financial balance.

Base Path

/api/v1/chart/balance

Get Balance Chart

Retrieve balance data across all asset accounts.

Request

curl -X GET "https://your-firefly-instance.com/api/v1/chart/balance/balance?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

start · date · required

Start date in YYYY-MM-DD format

end · date · required

End date in YYYY-MM-DD format

period · string · default: "1D"

Time period for grouping

Budget Charts

Visualize budget usage and limits.

Base Path

/api/v1/chart/budget

Get Budget Overview Chart

Retrieve spending vs budget data.

Request

curl -X GET "https://your-firefly-instance.com/api/v1/chart/budget/overview?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

start · date · required

Start date in YYYY-MM-DD format

end · date · required

End date in YYYY-MM-DD format

budgets · string

Comma-separated list of budget IDs to include

Category Charts

Visualize spending and income by category.

Base Path

/api/v1/chart/category

Get Category Overview Chart

Retrieve transaction data grouped by category.

Request

curl -X GET "https://your-firefly-instance.com/api/v1/chart/category/overview?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

start · date · required

Start date in YYYY-MM-DD format

end · date · required

End date in YYYY-MM-DD format

categories · string

Comma-separated list of category IDs to include

Period Options

All chart endpoints support period-based data grouping:

Period	Description	Example Use Case
1D	Daily	Detailed daily tracking
1W	Weekly	Weekly spending patterns
1M	Monthly	Monthly budget analysis
3M	Quarterly	Quarterly reports
1Y	Yearly	Annual comparisons

Primary Currency Conversion

When enabled in user preferences, chart data includes primary currency conversion:

With Primary Currency

{
  "label": "Euro Savings",
  "currency_code": "EUR",
  "primary_currency_id": "1",
  "primary_currency_code": "USD",
  "primary_currency_symbol": "$",
  "primary_currency_decimal_places": 2,
  "entries": {
    "2024-01-01T00:00:00+00:00": "1000.00"
  },
  "pc_entries": {
    "2024-01-01T00:00:00+00:00": "1100.00"
  }
}

pc_entries · object

Primary currency converted amounts, using exchange rates from the transaction dates

Chart Data Structure

All chart endpoints return an array of datasets with this structure:

label · string

Dataset label for the chart legend

type · string

Chart type (line, bar, etc.)

yAxisID · integer

Y-axis identifier for multi-axis charts

entries · object

Time-series data with ISO date strings as keys and amounts as string values

currency_* · string

Currency metadata fields for proper formatting

Integration with Chart.js

The data structure is designed for easy integration with Chart.js:

Chart.js Example

fetch('https://your-firefly-instance.com/api/v1/chart/account/overview?start=2024-01-01&end=2024-12-31&accounts=1', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
.then(response => response.json())
.then(chartData => {
  const datasets = chartData.map(dataset => ({
    label: dataset.label,
    data: Object.values(dataset.entries),
    borderColor: 'rgb(75, 192, 192)',
    tension: 0.1
  }));
  
  const labels = Object.keys(chartData[0].entries);
  
  new Chart(ctx, {
    type: 'line',
    data: {
      labels: labels,
      datasets: datasets
    },
    options: {
      responsive: true,
      scales: {
        y: {
          beginAtZero: true
        }
      }
    }
  });
});

Performance Considerations

Chart endpoints may be slow for:

• Large date ranges (> 1 year with daily granularity)
• Many accounts/categories
• Accounts with thousands of transactions

Consider using appropriate period values (1W, 1M) for large date ranges.

Use Cases

Account Balance Tracking

Visualize how your account balances change over time:

Daily Balance

curl -X GET "https://your-firefly-instance.com/api/v1/chart/account/overview?start=2024-01-01&end=2024-01-31&accounts=1&period=1D" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Category Spending Trends

Analyze spending patterns by category over months:

Monthly Categories

curl -X GET "https://your-firefly-instance.com/api/v1/chart/category/overview?start=2024-01-01&end=2024-12-31&period=1M" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Budget Performance

Track budget usage throughout the year:

Budget Tracking

curl -X GET "https://your-firefly-instance.com/api/v1/chart/budget/overview?start=2024-01-01&end=2024-12-31&period=1M" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Date Formatting

All dates in chart data are returned in ISO 8601 format with timezone:

2024-01-01T00:00:00+00:00

Dates are returned at the start of the period (midnight UTC) for daily data, start of week for weekly, etc.

Error Handling

Invalid Date Range

{
  "message": "The given data was invalid.",
  "errors": {
    "start": ["The start date must be before the end date."]
  }
}

Invalid Account IDs

{
  "message": "The given data was invalid.",
  "errors": {
    "accounts": ["One or more account IDs are invalid."]
  }
}

Next Steps

Insights API

Get aggregated financial insights

Search API

Search transactions for detailed analysis