# Wherebox

> 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.

Wherebox is an HTTP API: `GET /v1/map.png?…` returns an image, so a URL in an `<img>` tag is a complete client; `POST /v1/map` takes the same spec as JSON. Every docs page below is Markdown; each also has an HTML version under `/docs/`. Errors are `application/problem+json` whose `type` is a docs URL (`/docs/errors#<code>`); a name that matches several areas returns candidates to choose from.

## Docs

- [Wherebox documentation](/docs/index.md): Wherebox turns a request into a locator map image.

## Guides

- [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 (hosted service)](/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

- [API reference](/docs/reference.md): Generated from the code: edit the registries in `packages/spec`, not these pages.
- [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`
- [HTTP: auth parameters and headers](/docs/reference/http.md): 3 auth parameters and 19 request/response headers
- [Metrics](/docs/reference/metrics.md): 13 Prometheus metrics at /metrics
- [MCP server](/docs/reference/mcp.md): 4 tools, the docs as resources, 2 prompts
- [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
- [Basemap presets](/docs/reference/presets.md): Built-in basemaps and their highlight defaults

## API

- [OpenAPI document](/openapi.json): Every endpoint, parameter and response, generated from the schema the server validates against.
- [Playground](/playground): Interactive URL builder on the running server.

## Agent tools

- [Claude Code plugin](https://github.com/wherebox/claude-plugin): Install with `claude plugin marketplace add wherebox/claude-plugin` then `claude plugin install wherebox@wherebox`.

## Optional

- [Full documentation](/llms-full.txt): All of the pages above concatenated into one Markdown file.