# Wherebox documentation

Wherebox turns a request into a locator map image. Name an area, add points or a route, and you get a PNG, JPEG or WebP back: the area is framed and highlighted, the surroundings fade out, and points get markers and labels. It is a plain HTTP API, so an `<img>` tag is a valid client.

```http
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&neighbors=flag+code&w=468&h=280
```

![Czechia with Chřiby and neighboring countries](/docs/images/examples/home-locator.png)

Every request example in these docs is parsed by the test suite, and every non-routed example is rendered into the image next to it by `pnpm docs:examples`. If a parameter changes, the docs break loudly instead of silently going stale.

## Guides

Start with Getting started, then pick what you need.

| Guide | What it covers |
|---|---|
| [Getting started](/docs/guides/getting-started.md) | Your first map as an `<img>` and as a POST, retina, formats |
| [Recipes by use case](/docs/guides/use-cases.md) | Newsroom, booking email, listing, itinerary, AI agent, report, social card, spreadsheet |
| [Locator maps](/docs/guides/locator-maps.md) | Areas, ids and ambiguity, highlight, subdivisions, sub-areas, presets |
| [Points and labels](/docs/guides/points-and-labels.md) | Coordinates vs place names, markers, custom icons, labels, leader lines |
| [Routes](/docs/guides/routes.md) | Given lines, straight and geodesic, routed profiles, via points, styling |
| [Neighboring countries](/docs/guides/neighbors.md) | Names, codes and flags around the area, fit modes, languages |
| [Typography and titles](/docs/guides/typography-and-titles.md) | Fonts, weights, fallback, custom fonts, the title band |
| [Errors and limits](/docs/guides/errors-and-limits.md) | `problem+json`, retries, caching and ETags |
| [Fair use](/docs/guides/fair-use.md) | The free hosted service: monthly allowance, routed renders, rate limits, asking for more |
| [Authentication](/docs/guides/authentication.md) | Hosted service: keys, signed `<img>` URLs, rate limits and quotas, admin CLI |
| [TypeScript SDK](/docs/guides/sdk-typescript.md) | `@wherebox/sdk`: URLs, signing, rendering, typed errors, edge runtimes |
| [AI assistants (MCP)](/docs/guides/mcp.md) | Connect Claude and other MCP clients: hosted endpoint with OAuth, or `npx @wherebox/mcp` |
| [Python SDK](/docs/guides/sdk-python.md) | `pip install wherebox`: signed URLs for Django and Flask, rendering to a file, errors and retries |
| [Self-hosting](/docs/guides/self-hosting.md) | Install, import data, configure, Docker, routing engine |

## Reference (generated from code)

The guides explain how to do things. They deliberately do not repeat defaults, ranges or lists of values; those live in the reference, which is generated from the same source the API validates against.

- [Query parameters](/docs/reference/parameters.md): every `GET` parameter, with defaults and ranges
- [Request body](/docs/reference/request-body.md): the JSON body of `POST /v1/map`
- [Errors](/docs/errors.md): every `type` the API returns
- [Configuration](/docs/reference/configuration.md): every environment variable
- [Markers](/docs/reference/markers.md): marker presets and role defaults
- [Presets](/docs/reference/presets.md): built-in basemaps and their highlight defaults

The running server also serves an OpenAPI document at `/openapi.json` and an interactive URL builder at `/playground`.