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.
First map in one URL
/v1/map.pngGET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&neighbors=flag+code&w=468&h=280
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 | Your first map as an <img> and as a POST, retina, formats |
| Recipes by use case | Newsroom, booking email, listing, itinerary, AI agent, report, social card, spreadsheet |
| Locator maps | Areas, ids and ambiguity, highlight, subdivisions, sub-areas, presets |
| Points and labels | Coordinates vs place names, markers, custom icons, labels, leader lines |
| Routes | Given lines, straight and geodesic, routed profiles, via points, styling |
| Neighboring countries | Names, codes and flags around the area, fit modes, languages |
| Typography and titles | Fonts, weights, fallback, custom fonts, the title band |
| Errors and limits | problem+json, retries, caching and ETags |
| Fair use | The free hosted service: monthly allowance, routed renders, rate limits, asking for more |
| Authentication | Hosted service: keys, signed <img> URLs, rate limits and quotas, admin CLI |
| TypeScript SDK | @wherebox/sdk: URLs, signing, rendering, typed errors, edge runtimes |
| AI assistants (MCP) | Connect Claude and other MCP clients: hosted endpoint with OAuth, or npx @wherebox/mcp |
| Python SDK | pip install wherebox: signed URLs for Django and Flask, rendering to a file, errors and retries |
| Self-hosting | 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: every
GETparameter, with defaults and ranges - Request body: the JSON body of
POST /v1/map - Errors: every
typethe API returns - Configuration: every environment variable
- Markers: marker presets and role defaults
- Presets: 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.