# Map Generator — image API

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

## Endpoint

```
GET https://gui.farm/tools/map-generator.png?place=Kyoto&mode=dark&color=teal
```

Returns `image/png`. Locations accept a place name (geocoded via OpenStreetMap) or a raw `lat,lng` pair. Colors accept a named color (see https://gui.farm/colors) or a hex value. Providing both `from` and `to` draws a server-resolved route instead of a single pin. Encode spaces in place names as `+` or `%20` (e.g. `place=Eiffel+Tower`). `spec` is only for state that cannot fit readable params, such as uploaded custom pin images.

## Parameters

### Location & framing

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `place` | a place name, or "lat,lng" | — | Center the map and drop a pin. Place names are geocoded; coordinates work too. |
| `zoom` | 1–20 | auto (13 pin · 12 route) | Zoom level. Omit to let the tool frame it. |
| `ratio` | 1:1, 4:5, 9:16, 4:3, 3:2, 16:9 — or square, portrait, story, standard, photo, wide | 1:1 | Output shape. Height follows from the width and ratio. |
| `width` | pixels (100–2400) | 1200 | Output width. Height is derived from the ratio. |
| `spec` | base64url-encoded MapSpec JSON | — | Escape hatch for exact state that cannot be expressed readably, such as uploaded custom pin images. |

### Appearance

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `mode` | light, dark | light | Map theme. |
| `color` | a color name (blue, coral, …) or hex (#2563eb) | blue | Accent color for the pin and route. |
| `pin` | classic, dot, ring | classic | Pin style (single-pin mode). |
| `labels` | show, hide | show | Show or hide place-name text labels on the map. |
| `label` | free text | — | Caption shown on the pin. |

### Route (from + to)

| Param | Accepts | Default | Notes |
| --- | --- | --- | --- |
| `from` | a place name, or "lat,lng" | — | Route start. Providing both from and to draws a route instead of a pin. |
| `to` | a place name, or "lat,lng" | — | Route end. |
| `thickness` | 1–12 | 5 | Route line thickness. |
| `line` | solid, dotted | solid | Route line style. |
| `pins` | both, hide | both | Show or hide the endpoint pins on a route. |

## Examples

- Landmark pin, dark: https://gui.farm/tools/map-generator.png?place=Eiffel+Tower&zoom=16&mode=dark&color=coral
- Dotted route between two places: https://gui.farm/tools/map-generator.png?from=Eiffel+Tower&to=Arc+de+Triomphe&zoom=13&line=dotted&color=blue
- Ring pin by coordinates: https://gui.farm/tools/map-generator.png?place=41.8902,12.4922&zoom=16&pin=ring
- Teal accent, place name: https://gui.farm/tools/map-generator.png?place=Kyoto&zoom=15&color=teal

## Use it inside a .gui file

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

```xml
<gui version="0.2" name="Meeting point">
  <col w="360" p="20" gap="14" fill="#ffffff" radius="24">
    <text value="Where to meet" font-size="19" font-weight="700" color="#111827" />
    <img src="https://gui.farm/tools/map-generator.png?place=Kyoto&color=teal&ratio=3:2" w="320" h="213" radius="16" />
    <text value="Kyoto, Japan · 10:00 AM" font-size="14" color="#6b7280" />
  </col>
</gui>
```

## Attribution

Every rendered image has "© OpenStreetMap contributors" burned into the bottom-left corner. Please keep it — it satisfies the OpenStreetMap (ODbL) attribution requirement for produced works, including exported images.

## Other tools

- [Line Chart Generator](https://gui.farm/tools/charts/line-chart.md) — Paste your data, pick a color and mode, toggle grid and area — export a clean SVG line chart.
- [Bar Chart Generator](https://gui.farm/tools/charts/bar-chart.md) — Paste your data, go vertical or horizontal, round the bars and show values — export a clean SVG bar chart.
- [Area Chart Generator](https://gui.farm/tools/charts/area-chart.md) — Paste your data, choose a gradient or solid fill and a smooth curve — export a clean SVG area chart.
- [Pie Chart Generator](https://gui.farm/tools/charts/pie-chart.md) — Paste your data, pick a palette or mono scheme, toggle the legend — export a clean SVG pie chart.
- [Donut Chart Generator](https://gui.farm/tools/charts/donut-chart.md) — Paste your data, set the ring thickness and scheme, print the total — export a clean SVG donut chart.

---

Machine-readable index: https://gui.farm/llms.txt · Agent guide: https://gui.farm/agents.md