Calendar Heatmap Chart

Calendar Heatmap Chart

What it does

Calendar Heatmap Chart generates a calendar-style heatmap image or a pre-signed download link from dated numeric data. Send a title and an array of {date, value} objects, and get back a chart you can embed in dashboards, reports, or internal tools.

Use the /download endpoint when you want the chart image itself. It accepts a body object with a required title, a required data array, and an optional options object for custom colors. Each data point needs a date in YYYY-MM-DD format and a numeric value. The response is binary image data. Use /link with the same request body when you want a JSON response containing a data field with a pre-signed URL to the generated PNG.

Calendar Heatmap Chart is a good fit for showing daily activity, commits, sign-ins, completed tasks, or any other metric that changes over time. It makes sparse or seasonality-heavy data easy to scan at a glance, especially when you need a compact year view instead of a line chart.

If you need a chart image generated from date/value records and want simple color control through hex values, this API keeps the input shape small and the output straightforward.

curl -X POST "https://api.eu.apyverse.com/apyhub/generate-calendar-heatmap-chart/download" \ -H "apy-token: $APY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Daily User Activity", "data": [ { "date": "2026-06-01", "value": 3 } ] }'

About this endpoint

What it does

Generates a calendar heatmap chart image from a chart title and an array of dated numeric values, then returns the rendered image as binary data.

Request Body

Parameter	Type	Mandatory	Description
title	String	Yes	Chart title.
data	Object Array	Yes	Array of date/value points used to build the heatmap. Each item requires `date` and `value`.
data[].date	String	Yes	Date in `YYYY-MM-DD` format.
data[].value	Number	Yes	Numeric value for the date.
options	Object	No	Optional chart styling options.
options.color_low	String	No	6-character hex color without the leading `#` symbol.
options.color_med	String	No	6-character hex color without the leading `#` symbol.
options.color_high	String	No	6-character hex color without the leading `#` symbol.
options.color_empty	String	No	6-character hex color without the leading `#` symbol.
options.color_med_low	String	No	6-character hex color without the leading `#` symbol.

Response

Returns a binary response body containing the generated chart image. The output schema is a string with contentEncoding: binary, so the success response is the image file itself rather than a JSON object.

curl -X POST "https://api.eu.apyverse.com/apyhub/generate-calendar-heatmap-chart/link" \ -H "apy-token: $APY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Daily User Activity", "data": [ { "date": "2026-06-01", "value": 3 } ] }'

About this endpoint

What it does

Generates a calendar heatmap chart link from a chart title, a non-empty series of dated values, and optional color customization options. The endpoint returns a JSON object containing a pre-signed URL for the generated chart image.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Chart identifier returned by the endpoint, as a query parameter. Example: `daily-user-activity-heatmap-chart`.

Request Body

Parameter	Type	Mandatory	Description
title	String	Yes	Chart title. Must be at least 1 character long.
data	Object Array	Yes	Non-empty list of dated values (`minItems: 1`). Each item must include `date` and `value`.
data[].date	String	Yes	Date in `YYYY-MM-DD` format. Schema format: `date`.
data[].value	Number	Yes	Numeric value for the given date.
options	Object	No	Optional chart color settings. Only the listed fields are allowed.
options.color_low	String	No	6-character hex color without the leading `#` symbol.
options.color_med	String	No	6-character hex color without the leading `#` symbol.
options.color_high	String	No	6-character hex color without the leading `#` symbol.
options.color_empty	String	No	6-character hex color without the leading `#` symbol.
options.color_med_low	String	No	6-character hex color without the leading `#` symbol.

Response

Returns a JSON object with a data string field containing a URI. The data value is a pre-signed URL for the generated chart image.

Parameter	Type	Mandatory	Description
data	String	Yes	Pre-signed URL for the generated chart image.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

—

What it does

QUICKSTART

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Query parameters

Body

QUICKSTART

Quickstart

What you'll get back

About this endpoint

What it does

Query Parameter(s)

Request Body

Response

Query parameters

Body

Errors any endpoint can return