# Getting started

A map is one URL. No account, no SDK.

## The first map: GET in an `<img>`

```http
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=468&h=280
```

![Czechia with a marker on Chřiby](/docs/images/examples/czechia-locator.png)

Put that URL (with your host in front) into an image tag:

```html
<img src="https://YOUR-HOST/v1/map.png?…the query above…" width="468" height="280" alt="Czechia, Chřiby highlighted">
```

What happened: `area` was looked up by name and framed, everything outside it faded, inner borders were drawn, and `poi` put a labeled marker on a named place. `w` and `h` are the size in CSS pixels. Commas, pipes and non-ASCII characters can stay as they are in a browser; use `+` or `%20` for spaces and `%23` for `#`.

Every parameter is listed in the [query parameter reference](/docs/reference/parameters.md). The area, `poi` and `w`/`h` parameters used above are [`area`](/docs/reference/parameters.md#param-area), [`poi`](/docs/reference/parameters.md#param-poi), [`w`](/docs/reference/parameters.md#param-w) and [`h`](/docs/reference/parameters.md#param-h).

## The same map as a POST

GET is convenient and cacheable, but URLs are limited in length and cannot carry some things (custom fonts, GeoJSON areas, more than one route, labels containing `|`). For those, send the same description as JSON to `POST /v1/map` with `Content-Type: application/json`:

```json
{
  "area": "Czechia",
  "pois": [{ "place": "Chřiby", "marker": { "shape": "triangle" } }],
  "width": 468,
  "height": 280
}
```

The response is the image itself. Add `?response=json` to the POST URL to get `{url, key, meta, …}` instead, where `url` points at the cached image (`/v1/images/{key}`, immutable, safe to store). The body fields are listed in the [request body reference](/docs/reference/request-body.md).

GET and POST describe the same thing; every example in these guides is labeled with the method it uses, and the GET ones can be turned into JSON and back.

## Retina

`scale` multiplies the pixel density without changing the layout: the image is `w × scale` pixels wide, and markers, labels and line widths grow with it.

```http
GET /v1/map.png?area=Czechia&poi=place:Chřiby|marker:triangle&w=360&h=220&scale=2
```

![A 360 by 220 map rendered at 2x](/docs/images/examples/retina-2x.png)

Use it with an `<img>` that has `width="360"` and let the browser downscale. See [`scale`](/docs/reference/parameters.md#param-scale).

## Formats

Pick the format with the path extension (`.png`, `.jpg`, `.webp`) or with the `format` parameter. PNG is lossless and the default; JPEG and WebP take a `quality`.

```http
GET /v1/map.webp?area=Czechia&w=468&h=280&quality=85
```

See [`format`](/docs/reference/parameters.md#param-format) and [`quality`](/docs/reference/parameters.md#param-quality).

## What to read next

- Frame a country or region: [Locator maps](/docs/guides/locator-maps.md)
- Add points: [Points and labels](/docs/guides/points-and-labels.md)
- Draw a route: [Routes](/docs/guides/routes.md)
- Something returned an error: [Errors and limits](/docs/guides/errors-and-limits.md)