# Bar Chart Generator — image API

Generate a bar chart SVG from a single `GET` request. No API key, no SDK, no client library: describe the chart in the query string and the endpoint renders it. This is the machine-readable twin of https://gui.farm/tools/charts/bar-chart — the interactive editor is omitted on purpose; everything an agent needs is below.

## Endpoint

```
GET https://gui.farm/tools/charts/bar-chart.svg?data=Jan:32,Feb:41,Mar:38&bar=coral
```

Returns `image/svg+xml`. Data is `label:value` pairs, comma-separated (the label is optional, so `data=10,20,30` works too, with an optional `labels=` list). Colors accept a named color (see https://gui.farm/colors) or a hex value. Negative values grow from a zero baseline. The SVG is always transparent — `surface` only chooses label/gridline contrast (light or dark) for wherever you place it; hide both label sets for an edge-to-edge fill. Opening the same URL without `.svg` opens the interactive editor pre-loaded with that chart.

## Parameters

### Data

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `data` | Label:value pairs, comma-separated (label optional) | — | The series to plot. Each item is label:value; value-only items are allowed. Negative values grow from a zero baseline. |
| `labels` | comma-separated text | — | Optional category labels for value-only data. |

### Appearance

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `bar` | a color name (blue, coral, …) or hex | blue | Bar fill color. `color` is an alias. |
| `surface` | light, dark | light | Tone the chart will sit on — sets label and gridline contrast only. The background is never painted; the SVG is transparent. |
| `orient` | vertical, horizontal | vertical | Bar direction. Horizontal reads well for long category names. |
| `radius` | pixels (0–40) | 6 | Corner rounding on the value end of each bar. 0 is square. |

### Elements

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `grid` | show, hide | show | Gridlines along the value axis. |
| `values` | show, hide | hide | Draw each bar’s value at its end. |
| `xlabels` | show, hide | show | X-axis (bottom) labels. Hiding both label sets makes the chart fully edge-to-edge. |
| `ylabels` | show, hide | show | Y-axis (left) labels. |

### Size

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `width` | pixels (50–2000) | 720 | Output width, and the drawing box — the bars reflow to it. |
| `height` | pixels (50–2000) | 440 | Output height, and the drawing box. |

## Examples

- Revenue by month, coral: https://gui.farm/tools/charts/bar-chart.svg?data=Jan:32,Feb:41,Mar:38,Apr:55,May:61,Jun:72&bar=coral
- Horizontal, teal on a dark surface: https://gui.farm/tools/charts/bar-chart.svg?data=North:120,South:150,East:135,West:180&bar=teal&orient=horizontal&surface=dark
- Rounded, with values shown: https://gui.farm/tools/charts/bar-chart.svg?data=Q1:120,Q2:150,Q3:135,Q4:180&bar=violet&radius=12&values=show
- Minimal — no labels, no grid: https://gui.farm/tools/charts/bar-chart.svg?data=10,14,12,20,18,26,24,30&bar=blue&xlabels=hide&ylabels=hide&grid=hide

## Use it inside a .gui file

Because the endpoint is a stable image URL, a `.gui` screen embeds a chart as a plain `<img>` — nothing to download or unzip. The chart stays live text an agent can read and edit.

```xml
<gui version="0.2" name="Monthly revenue">
  <col w="360" p="20" gap="14" fill="#ffffff" radius="24">
    <text value="Monthly revenue" font-size="19" font-weight="700" color="#111827" />
    <img src="https://gui.farm/tools/charts/bar-chart.svg?data=Jan:32,Feb:41,Mar:38,Apr:55,May:61,Jun:72&bar=teal&width=640&height=360" w="320" h="180" radius="16" />
    <text value="Up 18% since January" font-size="14" color="#6b7280" />
  </col>
</gui>
```

---