Description

Charts API Endpoints

The Charts module provides a universal chart generation system that converts flexible query parameters into SQL queries and returns data formatted for Nivo charts.

Line Chart

GET /v1/charts/line

Generate line chart data based on flexible query parameters. The system automatically converts the request into appropriate SQL queries and returns data formatted for Nivo line charts.

Core Parameters

Data Control Parameters

Chart Styling Parameters

Filter Parameters

Supported Record Types

Currency Pairs

• Table: currencies.currency_pairs
• X-Field Options: date, base_currency, target_currency, type, source
• Y-Field Options: rate
• Group By Options: base_currency, target_currency, type, source
• Available Fields: date, base_currency, target_currency, type, source, rate

Gap Filling Strategies

The fill_gaps parameter allows you to fill missing time points in your chart data with null values, ensuring a complete timeline for better visualization.

Available Strategies

How It Works

1. Date Range Detection: The system uses search parameters (search.date.gte and search.date.lte) to determine the full date range
2. Gap Identification: Compares existing data points against the complete date range
3. Zero Value Insertion: Inserts data points with y: 0 for missing dates
4. Complete Timeline: Returns a consistent timeline regardless of data availability

Example Scenarios

Daily Gap Filling: When you have data for July 1st, 3rd, and 5th, but want to show all 31 days of July:

• fill_gaps=daily will create 31 data points
• Days 2, 4, 6-30 will have y: 0
• Days 1, 3, 5 will have actual values

Monthly Gap Filling: When you have data for January, March, and December, but want to show all 12 months:

• fill_gaps=monthly will create 12 data points
• February, April-November will have y: null
• January, March, December will have actual values

Chart Features

Multi-Series Support

When using group_by, the API returns multiple series, each with a unique color generated from the base color.

Dynamic Color Generation

Colors are automatically generated for multiple series using HSL color space variations.

Pagination Support

Use limit and offset parameters for handling large datasets.

Usage Examples

Basic Exchange Rate Chart

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&limit=50"

Multi-Currency Chart

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&group_by=base_currency&search.date.gte=2024-01-01T00:00:00Z&search.date.lte=2024-12-31T23:59:59Z"

Filtered Chart with Search Parameters

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&search.type=MID&search.source=SNB&limit=50"

Comprehensive Currency Pair Analysis

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&search.base_currency=USD&search.target_currency=EUR&search.date.gte=2025-07-01&search.date.lte=2025-07-31&search.type=SELL&search.source=SNB&color=hsl(58, 70%, 50%)"

This example demonstrates:

• Specific currency pair: USD to EUR exchange rates
• Date range filtering: July 2025 data
• Transaction type: SELL transactions only
• Data source: SNB (Swiss National Bank)
• Custom styling: Specific HSL color for the chart

Gap Filling Example

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&search.date.gte=2025-07-01&search.date.lte=2025-07-31&fill_gaps=daily"

This example demonstrates:

• Date range filtering: July 2025 data (31 days)
• Daily gap filling: Missing dates will be filled with null values
• Complete timeline: Returns 31 data points, one for each day in the range

Monthly Gap Filling Example

curl -X GET "{{base_url}}/v1/charts/line?rec_type=currency_pairs&x_field=date&y_field=rate&search.date.gte=2025-01-01&search.date.lte=2025-12-31&fill_gaps=monthly"

This example demonstrates:

• Date range filtering: Full year 2025 data
• Monthly gap filling: Missing months will be filled with null values
• Complete timeline: Returns 12 data points, one for each month

Response:

[
  {
    "id": "series",
    "color": "hsl(120, 70%, 50%)",
    "data": [
      {
        "x": "2024-01-01",
        "y": 1.0923
      },
      {
        "x": "2024-01-02",
        "y": 0
      },
      {
        "x": "2024-01-03",
        "y": 1.0931
      },
      {
        "x": "2024-01-04",
        "y": 0
      },
      {
        "x": "2024-01-05",
        "y": 1.0940
      }
    ]
  }
]

Response Format

The API returns an array of chart series in Nivo-compatible format. When no group_by is specified, a single series with id: "series" is returned.

Single Series Response (No Group By)

[
    {
        "id": "series",
        "color": "hsl(58, 70%, 50%)",
        "data": [
            {
                "x": "2025-07-30",
                "y": 1.150009
            },
            {
                "x": "2025-07-31",
                "y": 1.138944
            }
        ]
    }
]

Multi-Series Response (With Group By)

[
    {
        "id": "EUR",
        "color": "hsl(58, 70%, 50%)",
        "data": [
            {
                "x": "2024-01-01",
                "y": 1.0923
            },
            {
                "x": "2024-01-02",
                "y": 1.0931
            }
        ]
    },
    {
        "id": "USD",
        "color": "hsl(118, 70%, 50%)",
        "data": [
            {
                "x": "2024-01-01",
                "y": 0.9155
            },
            {
                "x": "2024-01-02",
                "y": 0.9148
            }
        ]
    }
]

Response Fields

• id: Series identifier (group value when using group_by, otherwise "series")
• color: HSL color value for the series
• data: Array of data points
  • x: X-axis value (formatted as string, dates are simplified to YYYY-MM-DD format)
  • y: Y-axis value (numeric, compatible with Nivo charts)

Error Handling

Best Practices

1. Use appropriate date ranges: Limit date ranges to avoid performance issues
2. Set reasonable limits: Use limit parameter to control data volume (max 1000)
3. Group by meaningful fields: Use group_by to create meaningful chart series
4. Cache results: Consider caching chart data for frequently accessed queries
5. Monitor performance: Large datasets may require pagination or filtering
6. Use specific filters: Combine multiple search parameters for precise data selection
7. Validate date formats: Use RFC3339 format for date filters
8. Consider data sources: Different sources may have varying data quality and availability