Wherebox

Get a map with locations from a single URL request

Wherebox turns a request into a locator map image. Name an area, add points or a route, and get a ready-to-use image with the area framed, surroundings faded, and points labelled. It’s a plain HTTP API, so an <img> tag is a valid client.

Documentation
Locator map of Spain on the shaded relief basemap, neighboring countries labeled with flag and code, Barcelona marked
The map this tag renders
Basemap
Show
<img src="https://api.wherebox.dev/v1/map.png?area=Spain&center=39.8,-3.6&zoom=4.4&neighbors=flag+code&neighborfit=shrink&poi=41.3874,2.1686|label:Barcelona&w=560&h=360&scale=2">

See all options in a full playground

Also POST JSON for complex maps and signed URLs for public pages: Getting started, Authentication.

The hosted Wherebox service is free for everyone. To keep it that way, each account gets a monthly allowance and a few limits that protect the service for all users. Most sites and apps never come close: a locator map is rendered once and then served from the cache, and cached maps never count. Fair use.

SDKs

Typed clients that build and sign URLs, render to bytes, and turn every error into one class.

The snippets are the SDK READMEs' own examples, compiled (TypeScript) and run (Python) by the test suite.

TypeScript

npm install @wherebox/sdk
import { createClient } from '@wherebox/sdk';

const wherebox = createClient({ baseUrl: 'https://maps.example.com' });

const src = await wherebox.url(
  { area: 'Czechia', pois: [{ place: 'Chřiby', marker: { shape: 'triangle' } }], width: 468, height: 280 },
  { format: 'webp' },
);
// https://maps.example.com/v1/map.webp?area=Czechia&w=468&h=280&poi=place%3ACh%C5%99iby%7Cmarker%3Atriangle
console.log(`<img src="${src}" width="468" height="280" alt="Czechia, Chřiby highlighted">`);

TypeScript SDK guide

Python

pip install wherebox
from wherebox import Client

client = Client("https://maps.example.com", publishable_key="pk_…", signing_secret="<hex signing secret>")
src = client.url({"area": "Czechia", "pois": [{"place": "Chřiby"}], "width": 468, "height": 280}, expires_in=3600)
# <img src="{{ src }}">

Python SDK guide

Built for agents

Coding agents that add maps to an app, and assistants that need a map for an answer, can install the plugin, read the OpenAPI document, or call the HTTP API directly.

Quickstart prompt

Paste it into Claude Code, Codex, Cursor or any other coding agent. It points the agent at the docs, the SDKs and the key rules, then has it add a map to your project.

  • Claude Code
  • Codex
  • Cursor

Claude Code plugin

Teaches Claude Code to add Wherebox static locator-map images to apps: GET <img> URLs vs POST specs, signed URLs with publishable keys, the TypeScript and Python SDKs, and ambiguous-name handling.

claude plugin marketplace add wherebox/claude-plugin
claude plugin install wherebox@wherebox

Public repository: github.com/wherebox/claude-plugin. Other agents that read the Agent Skills format can use its skills/wherebox folder.

MCP server

An assistant such as Claude can render a map, look at it, refine it until it is right, and hand back a permanent image URL. Connect the hosted server and approve it once in your browser, or run it locally.

claude mcp add --transport http wherebox https://api.wherebox.dev/mcp

AI assistants (MCP)

OpenAPI

Every endpoint, parameter and response as an OpenAPI document, generated from the same schema the server validates against.

/openapi.json · API explorer

Self-hostable

Run the whole service on your own server. Wherebox is one Node 22 API process that reads its map data from an atlas: three files built from Overture Maps (OpenStreetMap boundaries and places) and Natural Earth.

Self-hosting guideOpen the playground