# chart

A **`chart`** shape is used to render data in a graphical form. All chart types provided by PowerPoint are supported.

<table><thead><tr><th width="155">Parameter</th><th width="98">Type</th><th width="124">Input</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>String</td><td></td><td><mark style="color:red;">[required if <code>shapeId</code> not provided]</mark> Name of shape to update/manipulate. Find shape names <a href="https://docs.powerpointgeneratorapi.com/knowledge-base/finding-shape-names">here</a>.</td></tr><tr><td>shapeId</td><td>Integer</td><td></td><td><mark style="color:red;">[required if <code>name</code> not provided]</mark> A unique identifier of a given shape. This ID is not displayed in the document, it's hidden in the xml. </td></tr><tr><td>data</td><td><mark style="color:blue;">Object</mark></td><td></td><td><mark style="color:yellow;">[optional]</mark> Data to populate a chart's cellrange. See <a href="#data-object"><mark style="color:blue;"><strong>data object</strong></mark></a> for more information. </td></tr><tr><td>additional_data</td><td><mark style="color:blue;">Object</mark></td><td></td><td><mark style="color:yellow;">[optional]</mark> Data to populate specific cells, inside or outside a chart's cellrange. See <a href="#additional_data-object"><strong>additional_data object</strong></a> for more information. </td></tr><tr><td>overlays</td><td><mark style="color:blue;">Object</mark></td><td></td><td><mark style="color:yellow;">[optional]</mark> Enrich data labels on a chart by adding custom strings alongside the original label value. See <a href="#overlays-object"><strong>overlays object</strong></a> for more information. </td></tr><tr><td>settings</td><td><mark style="color:blue;">Object</mark></td><td></td><td><mark style="color:yellow;">[optional]</mark> An array of shape-level settings. See <a href="#settings-object"><mark style="color:blue;"><strong>settings object</strong></mark></a> for more information. </td></tr><tr><td>is_hidden</td><td>Boolean</td><td>true; false</td><td><mark style="color:yellow;">[optional]</mark> Hide shape</td></tr><tr><td>remove</td><td>Boolean</td><td>true; false</td><td><mark style="color:yellow;">[optional]</mark> Delete shape </td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"shapes": [
  {
    "name": "string",
    "data": [],
    "additional_data": [],
    "overlays": [],
    "settings": [],
    "is_hidden": boolean,
    "remove": boolean
   },
  {
    "name": "string",
    "data": [],
    "additional_data": [],
    "overlays": [],
    "settings": [],
    "is_hidden": boolean,
    "remove": boolean
   } 
]
```

{% endcode %}

***

## Data Object

The **`data`** object is used to populate a chart' cellrange - a specific contiguous cell range which acts as the chart's data source.&#x20;

<figure><img src="https://1155212587-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgoqdluo05I2RXHZpTr-887967055%2Fuploads%2FIxcfrdGyuRbPyWfxfTPC%2FChart%20CellRange.png?alt=media&#x26;token=d865a985-4881-4837-b034-735174b36308" alt="" width="349"><figcaption></figcaption></figure>

The data is organized as an array of arrays, where each inner array represents a different dimension of the data.

In the example payload below, the matrix would be of size 4x2, where there are 4 columns (series) and 2 rows (categories). The first column of the matrix would contain the values for the "series 1", the second column would contain the values for the "series 2", and so on. Similarly, the first row of the matrix would contain the values for the "category 1", the second row would contain the values for the "category 2".

JSON payload&#x20;

```json
"data": [
   [
      "series 1",
      "series 2",
      "series 3",
      "series 4"
   ],
   [
      "category 1",
      "category 2"
   ],
   [
      1,
      2,
      3,
      4
   ],
   [
      5,
      6,
      7,
      8
   ]
]
```

***

## Additional\_data Object

The `additional_data` parameter allows you to provide **extra sets of data for specific locations (cells) in a shape**, separate from the main `data` array.&#x20;

<figure><img src="https://1155212587-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgoqdluo05I2RXHZpTr-887967055%2Fuploads%2FbrL5RZEN5gboTpebBRxZ%2FChart%20Additional%20Data.png?alt=media&#x26;token=e31471ae-2cba-4586-84df-9f49cf95dcd6" alt="" width="331"><figcaption></figcaption></figure>

It’s useful when you want to:

* Fill in **specific parts of a chart or table** without changing the entire dataset.
* Inject **supplementary information**, like labels, notes, or reference values, that the main `data` array doesn’t cover.
* Target **exact cells** in a PowerPoint shape for fine-grained control.

Think of it as a “data override” or “cell-level customization” mechanism.

JSON payload

```json
"additional_data": [
  {
    "cell_target": "G1",
    "data": [
      ["Sum"],
      [8.7],
      [8.9],
      [8.3],
      [12.3]
    ]
  }
]
```

***

## Overlays Object

The `overlays` property lets you add custom symbols or text to existing chart labels, useful for highlighting specific points (e.g., arrows, icons, or annotations) without changing the actual data.

It’s organized as an array of arrays: each inner array represents a **series**, and each element inside corresponds to a **data point** within that series.

For example, if your data grid is **5×5** (5 categories × 5 series), your `overlays` must also contain **10 arrays** (one per data point), even if most are empty.

Each overlay can define properties like color, font size, or position. In the example below, a magenta “▲” symbol appears to the right of the first data point in the first series.

JSON payload&#x20;

```json
"overlays": [
  [
    {
      "value": "▲",
      "color": "magenta",
      "font_bold": true,
      "font_italic": true,
      "font_size": 5,
      "position": "right"
    }
  ],
  [],
  [],
  [],
  [],
  [],
  [],
  [],
  [],
  []
]
```

***

## Settings Object

The **`settings`** parameters below are specific to chart shapes only. Chart shape consists of several different elements, like plot area, legend and so on, we have grouped the settings to match these elements below.&#x20;

### Chart Area

<table><thead><tr><th width="157">Parameter</th><th width="93">Type</th><th width="148">Input</th><th>Description </th></tr></thead><tbody><tr><td>title</td><td>String</td><td></td><td><mark style="color:yellow;">[optional]</mark> Shorthand way of adding text to a chart's title</td></tr><tr><td>chartFont</td><td>String</td><td>MS supported <a href="https://learn.microsoft.com/en-us/typography/font-list/#a">font names</a></td><td><mark style="color:yellow;">[optional]</mark> The text font applies to all text in the chart shape</td></tr><tr><td>chartFontSize </td><td>Integer</td><td>1 to 4000</td><td><mark style="color:yellow;">[optional]</mark> The text font size applies to all text in the chart shape</td></tr><tr><td>fill_color</td><td>String</td><td><p><a href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0#properties">Color name</a>,</p><p>RGB(0,0,0),</p><p><a href="https://www.color-hex.com/">Hex</a></p></td><td><mark style="color:yellow;">[optional]</mark> Chart background fill color</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
    "title": "string",
    "chartFont": "string",
    "chartFontSize": numeric,
    "fill_color": "string"
}
```

{% endcode %}

### Legend

<table><thead><tr><th width="224">Parameter</th><th width="95">Type</th><th width="153">Input</th><th>Description</th></tr></thead><tbody><tr><td>chartShowLegend</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/disable legend </td></tr><tr><td>chartLegendPosition</td><td>String<br>(Enum)</td><td><p><code>Left</code>,</p><p><code>Right</code>,</p><p><code>Bottom</code>,</p><p><code>Top</code>,</p><p><code>Topright</code>,</p><p><code>None</code></p></td><td><mark style="color:yellow;">[optional]</mark> Set Chart series label / legend display position, if visible</td></tr><tr><td>chartLegendFontColor</td><td>String</td><td><p><a href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0#properties">Color name</a>, RGB(0,0,0),</p><p><a href="https://www.color-hex.com/">Hex</a></p></td><td><mark style="color:yellow;">[optional]</mark> Set chart legend color – applies  all legend items i.e. not individual series, if visible</td></tr><tr><td>isChartLegendBold</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/disable chart legend text bold, if visible</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
    "chartShowLegend": boolean,
    "chartLegendPosition": "string",				   
    "chartLegendColor": "string",
    "isChartLegendBold": boolean
}
```

{% endcode %}

### Data labels

<table><thead><tr><th>Parameter</th><th width="103">Type</th><th width="149">Input</th><th>Description</th></tr></thead><tbody><tr><td>isChartLabelValueVisible</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable data label </td></tr><tr><td>chartDataLabelPosition</td><td>String<br>(Enum)</td><td><p><code>Left</code>,</p><p><code>Right</code>,</p><p><code>Top</code>,</p><p><code>Bottom</code>,</p><p><code>Center</code>,</p><p><code>InsideBase</code>,</p><p><code>InsideEnd</code>,</p><p><code>OutsideEnd</code>,</p><p><code>BestFit</code></p></td><td><mark style="color:yellow;">[optional]</mark> Set data label position, if enabled</td></tr><tr><td>chartDataLabelFontSize</td><td>Integer</td><td>1 to 4000</td><td><mark style="color:yellow;">[optional]</mark> Set data label's font size, if data label visible</td></tr><tr><td>chartDataLabelFont</td><td>String</td><td>MS supported <a href="https://learn.microsoft.com/en-us/typography/font-list/#a">font names</a></td><td><mark style="color:yellow;">[optional]</mark> Set data label's font, if data label visible</td></tr><tr><td>isDataLabelBold</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable chart data value label bold, if data label visible</td></tr><tr><td>chartDataLabelColor</td><td>String</td><td><p><a href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0#properties">Color name</a>, RGB(0,0,0),</p><p><a href="https://www.color-hex.com/">Hex</a></p></td><td><mark style="color:yellow;">[optional]</mark> Chart data value label color, if data label visible</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
    "isChartLabelValueVisible": boolean,			
    "chartDataLabelPosition": "string",
    "chartDataLabelFontSize": numeric,
    "chartDataLabelFont": "string",
    "isDataLabelBold": boolean,
    "chartDataLabelColor": "string"
}
```

{% endcode %}

### Category axis

<table><thead><tr><th width="255">Parameter</th><th width="97">Type</th><th width="144">Input</th><th>Description</th></tr></thead><tbody><tr><td>categoryTitle</td><td>String</td><td></td><td><mark style="color:yellow;">[optional]</mark> Shorthand way of adding text to a chart's category axis title</td></tr><tr><td>chartCategoryAxisFont</td><td>String</td><td>MS supported <a href="https://learn.microsoft.com/en-us/typography/font-list/#a">font names</a></td><td><mark style="color:yellow;">[optional]</mark> Set axis font type</td></tr><tr><td>chartCategoryAxisFontSize</td><td>Integer</td><td>1 to 4000</td><td><mark style="color:yellow;">[optional]</mark> Set axis font size</td></tr><tr><td>isCategoryAxisBold</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable  bold </td></tr><tr><td>chartCategoryAxisColor</td><td>String</td><td><p><a href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0#properties">Color name</a>, RGB(0,0,0),</p><p><a href="https://www.color-hex.com/">Hex</a></p></td><td><mark style="color:yellow;">[optional]</mark> Set axis text color</td></tr><tr><td>chartCategoryAxisPosition</td><td>String<br>(Enum)</td><td><p><code>nextToAxis</code>,</p><p><code>high</code>,</p><p><code>low</code>,</p><p><code>none</code></p></td><td><mark style="color:yellow;">[optional]</mark> Set axis position</td></tr><tr><td>chartCategoryAxisMax</td><td>String</td><td> </td><td><mark style="color:yellow;">[optional]</mark> Set axis maximum value</td></tr><tr><td>chartCategoryAxisMin</td><td>String</td><td> </td><td><mark style="color:yellow;">[optional]</mark> Set axis maximum value</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {  
    "categoryTitle": "string",
    "chartCategoryAxisMax": "numeric",
    "chartCategoryAxisMin": "numeric",
    "chartCategoryAxisPosition": "string",
    "chartCategoryAxisFontSize": numeric,
    "chartCategoryAxisFont": "string",
    "isCategoryAxisBold": boolean,
    "chartCategoryAxisColor": "string"
}
```

{% endcode %}

### Value axis

<table><thead><tr><th width="228">Parameter</th><th width="98">Type</th><th width="160">Input</th><th>Description</th></tr></thead><tbody><tr><td>valueTitle</td><td>String</td><td></td><td><mark style="color:yellow;">[optional]</mark> Shorthand way of adding text to a chart's value axis title</td></tr><tr><td>chartValueAxisFont</td><td>String</td><td>MS supported <a href="https://learn.microsoft.com/en-us/typography/font-list/#a">font names</a></td><td><mark style="color:yellow;">[optional]</mark> Set axis font type</td></tr><tr><td>chartValueAxisFontSize</td><td>Integer</td><td>1 to 4000</td><td><mark style="color:yellow;">[optional]</mark> Set axis font size</td></tr><tr><td>isValueAxisBold</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ Disable bold</td></tr><tr><td>chartValueAxisColor</td><td>String</td><td><p><a href="https://learn.microsoft.com/en-us/dotnet/api/system.windows.media.colors?view=windowsdesktop-7.0#properties">Color name</a>, RGB(0,0,0),</p><p><a href="https://www.color-hex.com/">Hex</a></p></td><td><mark style="color:yellow;">[optional]</mark> Set axis font color</td></tr><tr><td>chartValueAxisPosition</td><td>String<br>(Enum)</td><td><p><code>nextToAxis</code>,</p><p><code>high</code>,</p><p><code>low</code>,</p><p><code>none</code></p></td><td><mark style="color:yellow;">[optional]</mark> Set axis position</td></tr><tr><td>chartValueAxisMax</td><td>String</td><td></td><td><mark style="color:yellow;">[optional]</mark> Set axis maximum value</td></tr><tr><td>chartValueAxisMin</td><td>String</td><td></td><td><mark style="color:yellow;">[optional]</mark> Set axis minimum value</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
    "valueTitle": "string",
    "chartValueAxisPosition": "string",
    "chartValueAxisFont": "string",
    "chartValueAxisFontSize": numeric,		 
    "isValueAxisBold": boolean,		 
    "chartValueAxisColor": "string",
    "chartValueAxisMin": "numeric",
    "chartValueAxisMax": "numeric"
}
```

{% endcode %}

### Plot area

<table><thead><tr><th width="284">Name</th><th width="95">Type</th><th width="130">Input</th><th>Description</th></tr></thead><tbody><tr><td>isLabelValueVisible</td><td>Boolean</td><td> true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable data labels</td></tr><tr><td>showChartVerticalGridLines</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable vertical grid lines</td></tr><tr><td>showChartHorizantalGridLines</td><td>Boolean</td><td>true, false</td><td><mark style="color:yellow;">[optional]</mark> Enable/ disable horizontal grid lines</td></tr><tr><td>chartOverlap</td><td>Integer</td><td>-100 to 100</td><td><mark style="color:yellow;">[optional]</mark> Set series overlap</td></tr><tr><td>chartGapWidth</td><td>Integer</td><td>0 to 500</td><td><mark style="color:yellow;">[optional]</mark> Set series gap width</td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
    "isLabelValueVisible": boolean,
    "showChartVerticalGridLines": boolean,
    "showChartHorizantalGridLines": boolean,
    "chartOverlap": numeric,
    "chartGapWidth": numeric
}
```

{% endcode %}

### Size & Position

<table><thead><tr><th width="130">Parameter</th><th width="109">Type</th><th width="243">Input</th><th>Description</th></tr></thead><tbody><tr><td>width</td><td><p>Integer,</p><p>Float</p></td><td><p>0 to 5963.92</p><p> </p></td><td><mark style="color:yellow;">[optional]</mark> Set shape width</td></tr><tr><td>height</td><td><p>Integer,</p><p>Float</p></td><td>0 to 5963.92</td><td><mark style="color:yellow;">[optional]</mark> Set shape height</td></tr><tr><td>left</td><td><p>Integer,</p><p>Float</p></td><td>-5963.92 to 5963.92</td><td><mark style="color:yellow;">[optional]</mark> Set left position</td></tr><tr><td>top</td><td><p>Integer,</p><p>Float</p></td><td>-5963.92 to 5963.92</td><td><mark style="color:yellow;">[optional]</mark> Set top position</td></tr><tr><td>unit</td><td>String<br>(Enum)</td><td><p><code>cm</code>,</p><p><code>pt</code>,</p><p><code>points</code> (default value if ‘unit’ field is not specified)</p></td><td><mark style="color:yellow;">[optional]</mark> Set unit of measurement for shape <code>width</code>, <code>height</code>, <code>left</code>, <code>top</code></td></tr></tbody></table>

JSON payload

{% code lineNumbers="true" %}

```json
"settings": {
  "height": numeric,
  "width": numeric,
  "top": numeric,
  "left": numeric,
  "unit": "string"
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.powerpointgeneratorapi.com/json-template-syntax/shapes/chart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.