# DoMaps

> DoMaps adds a map to any website: paste one `<iframe>` (or a `<div>` plus one script tag). The map is styled from the website's own colors and pins the business's places from their addresses. No account, no API key, no setup step: the code works right away.

This file is the complete documentation for AI agents and developers. The same content for people: https://domaps.app/docs

AI agents adding a map to a site: follow "For AI agents" below.

- Script: `https://domaps.app/embed.js`
- Map frame: `https://map.domaps.app/map?...` (settings embeds) and `https://map.domaps.app/m/MAP_ID` (maps made in the DoMaps editor or with `POST https://api.domaps.app/maps`, and saved maps)
- A new map works without an account for up to 1,000 views a month. The count resets each month.

## Quick start (iframe, no script)

Put this where the map should appear, for example a "Find us" / "Visit us" section. Nothing else is needed: no account, no API key, no setup step. The map shows as soon as the page loads.

```html
<iframe
  src="https://map.domaps.app/map?address=Carrer%20de%20Verdi%2032%2C%20Barcelona&name=Caf%C3%A9%20Example&primary=6f4e37&background=faf6f0&text=2b1d14&icon=coffee"
  title="Map: Café Example"
  loading="lazy"
  style="width: 100%; height: 420px; border: 0; border-radius: 16px;"></iframe>
```

- Settings are URL parameters; URL-encode the values (spaces → `%20`, commas → `%2C`, `&` → `%26`).
- Colors are hex without the `#` in URLs (`6f4e37`).
- Works everywhere an iframe works: normal websites, site builders (WordPress, Wix, Squarespace), and pages opened directly as a file.
- Step-by-step guides for each site builder: https://domaps.app/guides
- Short answers to general questions about maps on websites: https://domaps.app/learn

## Alternative (div + script)

Same result, with settings as readable HTML attributes. The script turns each `div` into the iframe above:

```html
<div data-domaps
     data-address="Carrer de Verdi 32, Barcelona"
     data-name="Café Example"
     data-primary="#6f4e37" data-background="#faf6f0" data-text="#2b1d14"
     data-icon="coffee"
     style="height: 420px; border-radius: 16px; overflow: hidden;"></div>
<script type="module" src="https://domaps.app/embed.js"></script>
```

## For AI agents

Making a map through the API means the person you work for accepts the DoMaps Terms (https://domaps.app/terms): business use only, and only read sites they own or may use. Privacy: https://domaps.app/privacy.

There are two ways to add the map. Use path 1 if you can make HTTP requests (curl, fetch). Use path 2 only if you can't.

Before either path, read from the site: the business name, the address (street, number, city) and the colors from its CSS (`primary`: buttons and links, `background`: the page background, `text`: the main text color).

### Path 1 (recommended): create the map with one request

This makes a map with its own id and a private save link for the owner. No account and no API key are needed.

1. Create the map:

```sh
curl -s -X POST https://api.domaps.app/maps \
  -H "Content-Type: application/json" \
  -d '{"settings":{"name":"Café Example","address":"Carrer de Verdi 32, Barcelona","primary":"#6f4e37","background":"#faf6f0","text":"#2b1d14","icon":"coffee"}}'
```

`settings` takes the keys from the Settings table below. Colors work with or without the `#`. For several places, send `places` as a JSON list: `"places":[{"name":"Sol","address":"Calle Mayor 12, Madrid"},{"name":"Malasaña","address":"Calle del Espíritu Santo 8, Madrid"}]`. A map shows up to 3 places on the Free plan.

The response:

```json
{
  "id": "k3Jx9QpL2a",
  "saveKey": "SAVE_KEY",
  "iframe": "<iframe src=\"https://map.domaps.app/m/k3Jx9QpL2a\" title=\"Map: Café Example\" loading=\"lazy\" allow=\"geolocation\" style=\"width: 100%; height: 420px; border: 0; border-radius: 16px;\"></iframe>",
  "saveUrl": "https://map.domaps.app/save/k3Jx9QpL2a#SAVE_KEY",
  "warnings": []
}
```

2. If `warnings` is not empty, for example `"No address found for: Carrer Verdi, Barcelona"`, the map can't find that address. Fix it (street, number and city) and create the map again.
3. Put `iframe` on the page exactly as returned, where the map should go, at full width of its container. Don't change it or write your own.
4. Never put `saveUrl` or `saveKey` on the website, in the code, in comments or in commit messages. Only the owner gets them, in your final message.
5. One map per site. Don't create maps in a loop, per page or per test run. If the owner wants a different map before saving, create a new one and replace the iframe.
6. If the site has a Content Security Policy, allow `frame-src https://map.domaps.app`.
7. While the map isn't saved, a one-line reminder shows under it for its first 24 hours or 100 views. That is expected. Don't close it or hide it: saving is the owner's choice.
8. Your final message to the owner must include the `saveUrl`. It is the only way to save this map. When you are done, before the site is published, tell the owner this, with the `saveUrl`:

```text
Save the map before you publish the site. The map is hosted by DoMaps, and an unsaved map can't be edited later: any change means making a new map. Saving needs only your email. A saved map can be changed from your DoMaps dashboard without touching the website, and gets 10,000 views a month instead of 1,000. To save it:
1. Open this link: SAVE_URL
2. Enter your email.
3. Open the login link from the email.
You can also save it later with the same link.
```

Errors come back as JSON with the reasons in `message`, for example `{"message":["address or places is required, e.g. {\"settings\":{\"address\":\"Street 1, City\"}}"],"error":"Bad Request","statusCode":400}`. Fix what it says and send again. More places than the plan shows answers status 400 with `{"message":"This map can show up to 3 places on the Free plan.","error":"Bad Request","statusCode":400}`; send 3 places or fewer. One IP can create 10 maps a minute and 60 an hour (status 429 past that). When too many new maps are being made across DoMaps, it answers status 503 with "Too many new maps right now. Try again in a few minutes."; wait a few minutes and send the same request again.

### Path 2: you can't make HTTP requests

1. Use the settings embed from the Quick start: `https://map.domaps.app/map?` plus the settings as URL parameters.
2. When you are done, before the site is published, give the owner the editor link: `https://map.domaps.app/?` plus the same URL parameters as the embed. Tell them:

```text
Decide about saving the map before you publish the site. The map is hosted by DoMaps, and an unsaved map can't be edited later: any change means making a new map. Saving needs only your email. A saved map can be changed from your DoMaps dashboard without touching the website, and gets 10,000 views a month instead of 1,000. To save it, open this link: EDITOR_LINK
It opens the map in the DoMaps editor. Step 3 there saves it and gives you a prompt. Send me the prompt and I'll swap the map code on the site.
```

## Saving your map

A new map works without an account, for up to 1,000 views a month. The count resets each month. An unsaved map can't be edited later: any change means making a new map. So decide about saving before the site is published. Saving needs only the owner's email; there is no password, they log in with a link sent by email.

- Saving needs the owner's email, so leave it to the owner.
- A map made in the DoMaps editor, or by an AI agent with `POST https://api.domaps.app/maps` (path 1 above), comes with a private save link. Step 3 of the editor also saves it with an email, or with one click when logged in.
- The save banner: an unsaved map shows one line under the map for its first 24 hours or 100 views, whichever comes first: "Unsaved map. Owner: open the map's save link to save it." The map can't be saved from the banner, only with its save link. "Close" hides the banner for everyone.
- A map saved with its save link is final.
- A settings embed (`/map?...`) can't be saved as it is. Its banner points to the editor instead: the owner opens the editor with the same settings (`https://map.domaps.app/?` plus the embed's URL parameters).
- The editor makes a new map with a new embed code. The new code replaces the old one on the site, and the owner saves the new map in step 3. Until the code is replaced, the old embed keeps working as before.
- A saved map gets 10,000 views a month on the free plan.
- Changes the owner makes in their dashboard (My maps) show on the site on the next page view.
- A save link without its key, or with a wrong one, only offers **Duplicate it**: the editor with the map's settings. Do not put a save link on the website or in the code.
- A saved map embeds by its id:

```html
<iframe src="https://map.domaps.app/m/MAP_ID" title="Map: Café Example" loading="lazy" allow="geolocation"
        style="width: 100%; height: 420px; border: 0; border-radius: 16px;"></iframe>
```

- Div form of a saved map: `<div data-domaps data-map="MAP_ID"></div>` plus the script.

## Settings

| URL parameter | `div` attribute | Value | Notes |
|---|---|---|---|
| `address` | `data-address` | `Street 12, City` | One place. Include street, number and city |
| `name` | `data-name` | text | Name shown in the pin popup |
| `places` | `data-places` | JSON list | Several places: `[{"name":"Shop","address":"Street 1, City"}]`. A place may use `"lat"` and `"lng"` (numbers) instead of `"address"`. Up to 3 places on the Free plan, more on paid plans. Past the limit the API refuses the map, and a settings embed shows the first 3 with a `DoMaps:` console warning. An address is looked up once, when the map is saved, and stored as coordinates; one that isn't found is left out (POST /maps lists it in `warnings`). Up to 25 addresses without `lat` and `lng` per save |
| `primary` | `data-primary` | hex color | The site's brand/accent color (buttons, links). Used for pins and highlights |
| `background` | `data-background` | hex color | The page background around the map |
| `text` | `data-text` | hex color | The site's main text color |
| `icon` | `data-icon` | words or `pack:name` | Pin icon. Words are matched automatically (`coffee` → cafe icon) or exact (`maki:cafe`, `phosphor:coffee`). Default: classic pin |
| `match` | `data-match` | `accent` / `harmonized` / `monolith` | How strongly the map takes the site's colors. Default `harmonized` (natural colors tinted to the brand). `monolith`: the map blends into the page. `accent`: neutral map, brand color only on pins |
| `contrast` | `data-contrast` | `0` … `1` | `0` soft, `1` bold. Default `0.45` |
| `theme` | `data-theme` | `site` / `light` / `dark` / `system` | Default `site` (follows the given background). `system` follows the visitor's dark mode |
| `view` | `data-view` | `flat` / `tilted` / `3d` | How the map opens: flat (2D), tilted (default) or 3d. One place opens at zoom 15.5; several places are fitted to the pins |
| `camera` | `data-camera` | `lng,lat,zoom,pitch,bearing` | An exact starting view, saved with "Start from here" in the editor, e.g. `-9.1455,38.7134,16.2,52,-18`. Overrides `view` and the fit. Five plain numbers, comma-separated, no spaces, at most 5 decimals. Ranges: lng -180 to 180, lat -85 to 85, zoom 1 to 20, pitch 0 to 70, bearing -180 to 180 |
| `show-businesses` | `data-show-businesses` | `true` | Show other shops' names on the map (hidden by default) |
| (path `/m/MAP_ID`) | `data-map` | map id | A saved map; all other settings are ignored |

One of `address` or `places` is required. Without colors the map uses a neutral default look. An invalid `view` or `camera` is ignored (with a `DoMaps:` console warning) and the map fits the pins instead.

## Examples

Several locations (div form):

```html
<div data-domaps data-primary="#b5522b" data-background="#fbf6ef" data-text="#3a2a20" data-icon="bakery"
     data-places='[{"name":"Sol","address":"Calle Mayor 12, Madrid"},{"name":"Malasaña","address":"Calle del Espíritu Santo 8, Madrid"}]'
     style="height: 460px;"></div>
<script type="module" src="https://domaps.app/embed.js"></script>
```

Dark website, flat map (iframe form):

```html
<iframe src="https://map.domaps.app/map?address=Oranienstra%C3%9Fe%2040%2C%20Berlin&primary=7c74ff&background=0f1117&text=e6e8ef&view=flat"
        title="Map" loading="lazy" style="width: 100%; height: 420px; border: 0;"></iframe>
```

## Implementation notes

- Pass the site's actual colors. Don't try to restyle the map's internals; they are generated from those colors.
- Full width and 360–480px tall works well. Rounded corners like the site's cards look best.
- Each pin popup already contains the name, the address and a "Get directions" link (Apple Maps on Apple devices, Google Maps elsewhere). No separate directions feature is needed.
- With the div form, load `embed.js` once per page with `type="module"`. Several maps on one page are fine.
- A small "DoMaps" wordmark appears on the map on the free plan. Its menu has one link, "Made with DoMaps". An unsaved map also shows a one-line save reminder under it for its first 24 hours or 100 views. Nothing else is added to the map.

## Usage limits

- One view is one time a page with the map opens. Views are counted per calendar month (UTC).
- A map that isn't saved: up to 1,000 views a month. A saved map: its plan's monthly limit (10,000 on the free plan).
- There are no extra charges for exceeding the view limit. An email is sent when 80% of the limit is reached.
- The first time the monthly limit is exceeded, the maps continue to work until the end of the month, up to twice the monthly limit. This is available once per year.
- After that, maps that reach their limit show the address and a "Get directions" link instead of the map until the next month or an upgrade.
- Unsaved maps are limited to 1,000 views per month.
- A paused map shows its places in place of the map: up to 5 names and addresses with "Get directions" links, in the map's colors, and one line at the bottom. A saved map: "This map is paused. It reached its monthly views limit." A map that isn't saved gets no extra month and pauses at 1,000 views: "This map is paused until next month." and one line for the owner: "Owner: open the map's save link to save it." (a settings embed: "Owner: make a new map in the DoMaps editor.").
- There is never a charge for usage past the limit.
- Localhost, local network addresses and preview links (Lovable, Vercel, Netlify and similar) always show the map and never count.
- A page opened as a local file counts in some browsers. So does a page the map can't identify, for example an iframe with `referrerpolicy="no-referrer"` in Firefox.
- A saved map can count views only from its own website: the owner adds the domain under Your website in the editor.
- Once a saved map has its website set, other websites stop showing it after 1,000 views a day ("This map is set up for another website."). The owner's own site keeps working.
- Every map has a daily safety limit: 1,000 counted views a day for a saved map, 500 for one that isn't saved. Past it the map shows "This map is paused until tomorrow."
- Plans and limits: https://domaps.app/pricing (paid plans are not available yet).

## Check that it works

- The map shows the pin(s) in the `primary` color; clicking a pin shows the name, address and "Get directions".
- Problems are reported in the browser console (map frame) with a `DoMaps:` prefix, for example an address that wasn't found or a color that isn't hex.

## Troubleshooting

| Symptom | Fix |
|---|---|
| "No address found for this map" | Add street number and city to the address, or use `lat`/`lng` in `places` |
| Nothing appears (div form) | Load `embed.js` with `type="module"`; give the div a height |
| Wrong colors | Use hex values from the site's CSS (`6f4e37` in URLs, `#6f4e37` in attributes) |
| "This map is paused until next month." | The map isn't saved and reached 1,000 views this month. It works again next month. Or the owner saves it with its save link. A settings embed has none: the owner makes a new map in the editor (`https://map.domaps.app/?` plus the embed's URL parameters) and puts the new code on the site |
| "This map is paused. It reached its monthly views limit." | The owner's saved maps used up their plan's views this month. They work again next month or when the plan is upgraded |
| "This map is set up for another website." | The map is saved for another site, and views from other sites, previews and localhost used up today's share. It works again tomorrow. On the owner's site, add the domain under Your website in the editor |
| "This map is paused until tomorrow." | The map reached its daily safety limit. It works again when the next day starts (UTC) |
| "Map not found" | The map id in `/m/MAP_ID` or `data-map` is wrong |

## Data and credits

Map data © OpenStreetMap contributors. Tiles: OpenFreeMap / OpenMapTiles. Terrain: Mapterhorn and its data sources (https://mapterhorn.com/attribution). Address search: powered by Geoapify (https://www.geoapify.com/). Icons: Maki, Temaki (CC0), Phosphor (MIT). Attribution is shown on the map automatically.

## More pages

Guides for adding the map to a site builder:

- Lovable: https://domaps.app/guides/lovable
- Wix: https://domaps.app/guides/wix
- WordPress: https://domaps.app/guides/wordpress
- Framer: https://domaps.app/guides/framer
- Webflow: https://domaps.app/guides/webflow
- Squarespace: https://domaps.app/guides/squarespace
- Plain HTML: https://domaps.app/guides/html

Comparisons with other map services (setup, API keys, cookies, styling, limits):

- Google Maps: https://domaps.app/compare/google-maps
- Mapbox: https://domaps.app/compare/mapbox
- MapTiler: https://domaps.app/compare/maptiler
- Storemapper: https://domaps.app/compare/storemapper

Cookies and what the map connects to: https://domaps.app/google-maps-without-cookies

Short answers to common questions:

- How to add a map to your website: https://domaps.app/learn/how-to-add-a-map-to-your-website
- How to show several locations on one map: https://domaps.app/learn/multiple-locations-on-one-map
- A free map for a business website without an API key: https://domaps.app/learn/free-map-without-api-key
- OpenStreetMap embed for a business website: https://domaps.app/learn/openstreetmap-embed-for-business
- How to make a map match your brand colors: https://domaps.app/learn/map-in-your-brand-colors