# Markers API overview

Search and look up artworks, legal walls and the other places on the Street Art Cities map.

Everything on the Street Art Cities map is a **marker**. Most markers are artworks, but there are also legal walls, halls of fame, can shops, galleries and more. The Markers API lets your app search them and look them up.

**Base link:** `https://streetartcities.com/api/markers`

**API reference:** [open in Swagger UI](https://petstore3.swagger.io/?url=https://streetartcities.com/api/markers/openapi), or grab the [OpenAPI spec](https://streetartcities.com/api/markers/openapi) directly.

<Admonition kind="info" title="Want to change a marker?">
  The Markers API is read-only. To add artworks or fix mistakes, [suggest a
  change](/edits-api/suggesting-changes/) with the Edits API.
</Admonition>

## Endpoints

| Endpoint                       | Scope          | What it does                                                                    |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------- |
| `GET /api/markers/search`      | `markers:read` | [Search markers](/markers-api/reference/search-markers/)                        |
| `GET /api/markers/:id`         | `markers:read` | [Everything about one marker](/markers-api/reference/get-a-marker/)             |
| `GET /api/markers/:id/history` | None           | [Who added and changed a marker](/markers-api/reference/get-a-markers-history/) |

Search and getting a marker need an access token with the `markers:read` scope, even though the markers themselves are public. The history doesn't need a token.

## A marker

```json
{
  "@type": "Marker",
  "id": "108322",
  "href": "https://streetartcities.com/cities/amsterdam/markers/108322",
  "city": { "id": "amsterdam", "title": "Amsterdam" },
  "country": "NL",
  "countryName": "Netherlands",
  "lat": 52.3731,
  "lng": 4.8922,
  "address": "Dam 1, Amsterdam",
  "type": "artwork",
  "title": "Big cat",
  "status": "active",
  "description": "A very big cat.",
  "artists": [{ "id": "someone", "title": "Someone", "href": "https://…" }],
  "artistsString": "Someone, Someone else",
  "tags": ["cats"],
  "thumbnail": "https://streetartcities.com/media/markers/…/thumbnail.jpg",
  "likes": 3,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "updatedAt": "2026-02-01T08:30:00.000Z",
  "images": [
    { "id": "…", "url": "https://…", "sizes": { "small": "https://…" } }
  ],
  "attributes": { "date_created": "2024" }
}
```

`GET /api/markers/:id` gives you all of this, straight from our database, so it's always up to date. Search results have the same fields, except `images` and `attributes`. Get the marker itself when you need those.

`city` is missing for markers that aren't in a city. `description` can contain simple HTML, like links and line breaks.

The field names are the same ones you use to [suggest a change](/edits-api/suggesting-changes/) with the Edits API, so you can send back a field you got here, with a new value.

`status` is `active` for markers you can go and see, `inProgress` for artworks that are still being painted, and `removed` for artworks that are gone.

## Errors

Errors look like this:

```json
{ "error": { "message": "Marker not found." } }
```

You get a `404` when a marker doesn't exist. That includes markers that were merged into another one, when two people added the same artwork.