Wherebox

Use cases

Answer “where is it?” with a map, anywhere an image works

One URL returns a finished locator map image: the area framed and highlighted, points labelled, neighbours marked. It drops into email, PDF, CMS, RSS, chat and print, where interactive maps cannot go. No JavaScript, no GIS skills, no designer in the loop.

  • Email
  • PDF and print
  • CMS and RSS
  • Chat and agents
  • Social cards

Newsrooms and wire desks

A locator map for every story, in seconds

Breaking news happens in places most readers cannot find. The story needs a map before it needs a designer, and the same map has to work in the CMS, the print layout and the newsletter.

Why an image. An image drops into every one of those channels unchanged. Set the house style once in the request and every desk gets the same look.

Replaces: A designer in Illustrator or QGIS, a locator built by hand in a chart tool, or a screenshot of a map.

  • area by name, iso:, osm: or wikidata: id, or your own GeoJSON in a POST body
  • title with position, font and lang for the headline strip
  • poi with marker:triangle and a label for the exact spot
Iceland with a triangle at Grindavík
Iceland highlighted on a relief map, a red triangle at Grindavík and the headline “Eruption near Grindavík”
GET/v1/map.png
GET /v1/map.png?area=Iceland&poi=63.84,-22.43|marker:triangle|label:Grindavík&title=Eruption+near+Grindavík&w=600&h=400

In the docs: Recipes by use case

Transactional email

Show where the order, delivery or booking is

Order, delivery, booking and receipt emails carry an address that people skim past. A small map lets them recognise the place at a glance, and a start and finish makes a journey readable.

Why an image. Email clients strip JavaScript and block iframes, so an interactive map cannot render there. An <img> does.

Replaces: A plain address line, a link out to a map site, or a pre-rendered image kept in your own storage.

  • from and to as coordinates or place: names, with fromlabel and tolabel
  • profile=straight or geodesic draws the line itself; car, bike and foot need a routing engine
  • w and h sized to the email column
A flight route from Lisbon to New York
A great-circle route across the Atlantic from Lisbon (LIS) to New York (JFK)
GET/v1/map.png
GET /v1/map.png?from=38.77,-9.13&to=40.64,-73.78&profile=geodesic&fromlabel=LIS&tolabel=JFK&w=600&h=300

In the docs: Recipes by use case

Listings: real estate, hotels, rentals

A where-is-it image on every listing card

A search page can show hundreds of cards, and each one wants to say where the property is. The brochure and the PDF export want the same picture.

Why an image. Hundreds of interactive maps on one page are slow and heavy. Images load lazily, and responses are cacheable with ETag and Cache-Control.

Replaces: An embedded interactive map per card, or a static map from a hosted maps API with tight usage and display rules.

  • poi up to 50 points, by coordinates or place name, each with a label
  • Marker presets pin, dot, ring, flag, triangle, circle, square, star, diamond, or a custom icon
  • preset=light for a street-level base; labels avoid each other, with leader lines when points are crowded
A hotel in Barcelona with two nearby sights
A street map of Barcelona with a star for the hotel and pins for Sagrada Família and Barceloneta beach
GET/v1/map.png
GET /v1/map.png?poi=41.3917,2.1649|marker:star|label:Hotel&poi=41.378,2.192|label:Barceloneta+beach&poi=41.4036,2.1744|label:Sagrada+Família&preset=light&w=600&h=400

In the docs: Recipes by use case

Travel and reference publishing

Itineraries and profiles in one consistent locator style

Itineraries, country and region profiles and guidebook pages all need maps that look like they belong together: shaded relief, clear labels, the same marker language from page to page.

Why an image. A request is a recipe. Keep the recipe and every new page gets the same look without anyone opening a mapping tool.

Replaces: Maps drawn one at a time in a graphics tool, each slightly different from the last.

  • from, via and to with profile, fromlabel, tolabel and route styling
  • neighbors such as flag or code to mark neighbouring countries
  • projection=globe for intercontinental routes, preset=locator-relief for the Wikipedia-style look
Tokyo, Kyoto and Osaka on a map of Japan
Central Japan with a route from Tokyo via Kyoto to Osaka
GET/v1/map.png
GET /v1/map.png?area=Japan&bounds=131.5,32.8,141.5,37.6&from=35.68,139.76&via=35.01,135.77&to=34.69,135.50&profile=straight&fromlabel=Tokyo&tolabel=Osaka&poi=35.01,135.77|label:Kyoto&w=600&h=400

In the docs: Recipes by use case

AI agents and chatbots

Let an assistant answer “where is it?” with a picture

An assistant that names a place can also show it. The image URL renders in chat and Markdown, and the agent never has to handle a map key or a tile server.

Why an image. A URL is the one output every chat surface understands. When a name is ambiguous the API returns a 409 with candidates, so the agent corrects itself instead of drawing the wrong place.

Replaces: A text-only answer, or a screenshot tool bolted onto the agent.

  • area by name or iso: code, with neighbors=flag+name so the answer shows what is around it
  • Unknown parameters are a 400 with a “did you mean” hint, never a silently different map
  • Integrations for agents: an MCP server, the Claude Code plugin, llms.txt, Markdown for every docs page and /openapi.json
Bhutan and its neighbors on a dark map
Bhutan outlined on a dark map between China and India, both labelled with flags
GET/v1/map.png
GET /v1/map.png?area=Bhutan&bounds=84,22.5,97,31&neighbors=flag+name&lang=en&preset=dark&w=600&h=400

In the docs: Recipes by use case

Reports and PDFs: NGOs, public sector, insurance, due diligence

One map per record, from the same template

Situation reports, case files and risk summaries run to hundreds of generated pages. Each needs a map of its district, in the same style, without anyone laying it out.

Why an image. A PDF generator takes an image from a URL and nothing else. Borders can follow the reader: a worldview draws disputed ones the way a chosen country sees them.

Replaces: Maps pasted in by hand, or one generic overview map reused for every record.

  • poi for each office or site, title for the page heading
  • worldview selects how disputed borders are drawn
  • fade, outline and tint keep the highlight consistent
Kenya with three field offices
Kenya highlighted with labelled pins at Nairobi, Mombasa and Kisumu under the title “Field offices”
GET/v1/map.png
GET /v1/map.png?area=Kenya&poi=-1.286,36.817|label:Nairobi&poi=-4.043,39.668|label:Mombasa&poi=-0.092,34.768|label:Kisumu&title=Field+offices&w=600&h=450

In the docs: Recipes by use case

Newsletters and social share cards

Headers and share cards that match the brand

A newsletter header or an Open Graph image is one picture at a known size. Pick a light or dark base, add a pin and a title, and the card is done.

Why an image. Social and mail platforms fetch a plain image URL. No script runs, so there is nothing to wait for.

Replaces: A template in a design tool that someone has to open for every issue.

  • w and h from 64 to 2048 pixels, scale 1 to 3 for retina screens
  • format png, jpeg or webp
  • preset light or dark; highlight and labels follow the theme
A social card for a weekend in Lisbon
A 1200×630 dark card of Portugal with a star on Lisbon and the title “A weekend in Lisbon”
GET/v1/map.png
GET /v1/map.png?area=Portugal&bounds=-10.5,36.8,-5.5,42.3&poi=38.72,-9.14|marker:star|label:Lisbon&title=A+weekend+in+Lisbon&preset=dark&w=1200&h=630

In the docs: Recipes by use case

Spreadsheets and no-code automation

A column of place names becomes a column of maps

Write the URL once as a template with a cell reference in it, and every row gets its own map. In Google Sheets that is one formula, and in Airtable, Zapier or Make it is a formula field or an HTTP step.

Why an image. These tools can show an image from a URL, and that is all they need. The responses carry an ETag, so repeat views are cheap.

Replaces: Exporting names to a GIS tool, or pasting screenshots next to every row.

  • Template: =IMAGE("https://YOUR-HOST/v1/map.png?area="&ENCODEURL(A2)&"&w=468&h=280")
  • area takes a name, an iso:, osm: or wikidata: id from the cell
  • Add neighbors=name for context, or a poi column for a marker
Canada with neighbor names, the output for the row "Canada"
Canada highlighted, with the United States labelled
GET/v1/map.png
GET /v1/map.png?area=Canada&bounds=-141,41.5,-52,76&neighbors=name&w=600&h=400

In the docs: Recipes by use case

Questions people ask

Why not embed an interactive map?

Where JavaScript runs and a visitor can pan, an interactive map is the right tool. Email clients, PDF generators, RSS readers, chat apps and print do not run it, and a page with many maps pays for each one. An image works in all of them.

Why not take a screenshot of a map?

It is a manual step, the framing differs every time, and map licences and attribution rules are restrictive and easy to break. Here the attribution is drawn into the image, and the same request always gives the same map.

Do I need GIS skills or a designer?

No. You name an area, add points or a route, and pick a preset. The framing, highlight, label placement and fonts are handled for you. Area and place names are looked up, so you do not need coordinates or boundary files, although you can send your own GeoJSON.

Will my API key be exposed on a public page?

Not if you use a publishable pk_ key. Your server signs the image URL with an HMAC signature and an expiry (sig and exp), so a copied URL cannot be reused for other maps or after it expires. Your secret key stays on the server.

Can it match our house style?

Mostly yes. There are three presets (shaded relief, light and dark), and you control highlight and outline colours, fade, tint, fonts, titles, marker presets and custom icons. For a fully custom basemap, point style at your own MapLibre style.

Make your first map

A URL in an image tag is the whole integration. The quick start takes you from nothing to a rendered map.

Getting startedOpen the playground