# Fair use

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.

You can try the API without signing up: requests without a key get a small demo allowance, enough for the [playground](https://wherebox.dev/playground/) and the examples in these docs. For anything real, [create a free account](https://api.wherebox.dev/login) and use a key.

## The limits

|  | Without a key (demo) | Every account | Raised on request |
|---|---|---|---|
| New renders | 30 per day (UTC) | 10,000 per month (UTC) | 100,000 per month (UTC) |
| of which routed (car, bike, foot) | none | 1,000 | 10,000 |
| Requests per minute | 30 | 60 | 300 |
| Largest image (width × height × scale²) | 1.0 MP (e.g. 1000 × 1000 px) | 4.2 MP (e.g. 2048 × 2048 px) | 16.8 MP (e.g. 4096 × 4096 px) |
| Road routing | not included | included | included |
| `POST /v1/map` | not included | included | included |

Without a key, the limits apply per network (an IPv4 address or an IPv6 /64), and all visitors without a key together get at most 2,000 new renders a day.

Limits apply to the **account**: all of its API keys and connected AI assistants share them. Creating more keys does not raise them. The demo allowance covers `GET` map requests and searches only; `POST /v1/map` and the MCP endpoint always need a key.

## What counts

- **A render** is a map that had to be drawn because no identical image was in the cache. Requesting the same map again (same parameters) is a cache hit and is free, also after you reach the limit.
- **A routed render** is a render with a road route (`profile` `car`, `bike` or `foot`). Road routes come from an external routing service ([openrouteservice](https://openrouteservice.org) by HeiGIT) with a limited daily capacity shared by everyone, so they have their own, smaller allowance inside the monthly one. Straight and geodesic lines (`profile=straight`, `profile=geodesic`) are not counted separately.
- **Requests per minute** count every authenticated request, including searches and cache hits.

The [Usage page](/docs/guides/authentication.md#rate-limits-and-quotas) in your account shows where you stand. Every rendered response also carries [`X-Quota-Remaining`](/docs/reference/http.md#header-x-quota-remaining).

## When you reach a limit

- **Demo allowance (no key):** `429` [`quota-exceeded`](/docs/errors.md#quota-exceeded) until midnight UTC, with a link to sign up. A free key lifts it right away.
- **Monthly allowance:** new renders are refused with `429` [`quota-exceeded`](/docs/errors.md#quota-exceeded) until the 1st of next month (UTC). Maps you have already rendered keep working, because they are served from the cache. If only the routed allowance is used up, maps with straight or geodesic lines still render.
- **Requests per minute:** `429` [`rate-limited`](/docs/errors.md#rate-limited) with `Retry-After`. Wait and retry.
- **Image size:** `403` [`plan-limit`](/docs/errors.md#plan-limit). Ask for a smaller image, or a lower `scale`.

The error's `detail` says which limit was hit and, on the hosted service, where to ask for more.

## Need more?

Higher allowances are free too; they are granted by hand for legitimate projects. Email **[hello@wherebox.dev](mailto:hello@wherebox.dev?subject=Higher%20Wherebox%20limit)** with the subject "Higher Wherebox limit" and tell us:

1. the email address of your Wherebox account,
2. what you are building, with a link if it is public,
3. roughly how many new maps you expect per month, and how many of them with road routes (`car`, `bike`, `foot`),
4. whether you need larger images or more requests per minute.

The **Ask for a higher limit** link on your account's Usage page opens this email with your account details already filled in. We usually answer within a few working days. Meanwhile, keep your URLs stable so repeated views are cache hits, which never count (see [caching](/docs/guides/errors-and-limits.md#caching-and-etags)).

## Attribution and logo

The map data comes from OpenStreetMap and other open sources whose licenses require credit. Every image therefore carries the credits in a corner, and the exact text is also sent in the `X-Attribution` response header (percent-encoded, see [HTTP headers](/docs/reference/http.md)). Move the credits to another corner with `attribution=bottom-left` (or any corner), or leave them off the image with `attribution=none`:

```http
GET /v1/map.png?area=Czechia&attribution=none&w=468&h=280
```

![Czechia without the credits line](/docs/images/examples/attribution-none.png)

With `attribution=none` you must show the credits next to the image yourself, for example in a caption. Use the text from the `X-Attribution` header: it names every source the map used (OpenStreetMap, the basemap and terrain providers, Natural Earth borders, the routing engine). The TypeScript SDK returns it decoded as `attribution`, and `POST /v1/map?response=json` returns it as `attribution`.

A small `wherebox.dev` mark goes in the bottom-left corner by default. Move it with `logo=top-right` (or any corner). When the mark and the credits share a corner, they sit on one line. Hiding the mark requires a logo-removal license; contact us at [hello@wherebox.dev](mailto:hello@wherebox.dev?subject=Wherebox%20logo%20removal). See [`attribution`](/docs/reference/parameters.md#param-attribution) and [`logo`](/docs/reference/parameters.md#param-logo).

## Please don't

- open several accounts to get around the limits (one account per person or organization; a team shares one),
- download or scrape the search endpoints in bulk, or use the service as a bulk tile or image proxy,
- send load that degrades the service for others.

Accounts that break these rules may be throttled, suspended or closed. Usually you hear from us first, with a chance to fix things; we act without notice only to stop harm to the service or to others. If you think we got it wrong, reply to that email or write to [hello@wherebox.dev](mailto:hello@wherebox.dev) and a person will look at it again. The limits may change over time; this page always shows the current numbers.

## Report abuse

Seen Wherebox used for spam, scraping or anything harmful? Email [hello@wherebox.dev](mailto:hello@wherebox.dev?subject=Abuse%20report) with the subject "Abuse report" and include the URLs or request IDs (the `requestId` in error responses, or the `X-Request-Id` header) you saw.