# Searching markers

Find artworks by keyword, country, city, type or tag, or near a spot on the map.

## Search

```bash
curl "https://streetartcities.com/api/markers/search?q=cat&country=NL" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

```json
{
  "items": [
    { "@type": "Marker", "id": "108322", "title": "Big cat", "…": "…" }
  ],
  "page": 1,
  "perPage": 20,
  "total": 42
}
```

Every item looks like [a marker](/markers-api/overview/#a-marker), without `images` and `attributes`.

## Filters

All of these are optional, and you can combine them:

| Parameter      | What it does                                                               |
| -------------- | -------------------------------------------------------------------------- |
| `q`            | Words to look for in the title, artists, address and tags                  |
| `country`      | Two-letter country code, like `NL`                                         |
| `city`         | City ID, like `amsterdam`. It's the `city.id` of a marker                  |
| `type`         | [Marker type](/markers-api/marker-types/), like `artwork` or `legal_wall`  |
| `tag`          | Only markers with this tag                                                 |
| `artist`       | Only markers by this artist, like `someone`                                |
| `status`       | `active` (the default), `inProgress`, `removed`, or `all` for everything   |
| `lat`          | With `lng`: only markers near this spot                                    |
| `lng`          | With `lat`: only markers near this spot                                    |
| `radius`       | How far from `lat` and `lng` to look, in km. 5 by default, and at most 100 |
| `updatedSince` | Only markers that changed since this time, like `2026-09-01T00:00:00Z`     |

## Near a spot

Pass `lat` and `lng` to find markers around a spot, like where someone is standing:

```bash
curl "https://streetartcities.com/api/markers/search?lat=52.3731&lng=4.8922&radius=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

Results come closest first, and every item has a `distance`, in meters.

## Sorting

`sort` can be:

| Value       | Order                            |
| ----------- | -------------------------------- |
| `relevance` | Best match for `q` first         |
| `distance`  | Closest to `lat` and `lng` first |
| `newest`    | Most recently added first        |
| `oldest`    | First added first                |

Without `sort`, you get `distance` when you pass `lat` and `lng`, `relevance` when you pass `q`, and `newest` otherwise.

## Pages

Use `page` (starting at 1) and `perPage` (20 by default, at most 100). `total` tells you how many markers match over all pages.

## Keeping a copy in sync

To get every marker in a country, or on the whole map, go through all the pages with `sort=oldest`. That order doesn't change when markers are edited, so nothing moves between pages while you're going through them:

```bash
curl "https://streetartcities.com/api/markers/search?country=NL&status=all&sort=oldest&perPage=100&page=1" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

Write down when you started. Next time, do the same with `updatedSince` set to that time, to only get what changed since.

Use `status=all`, so you also hear about artworks that were removed. Markers that were merged into another one or deleted disappear, so check the ones you haven't seen in a while with [Get a marker](/markers-api/reference/get-a-marker/).

## Showing markers on a map

Add `format=geojson` to get a [GeoJSON](https://geojson.org) FeatureCollection instead. Most map libraries, like Leaflet, MapLibre and Mapbox, can show it straight away:

```bash
curl "https://streetartcities.com/api/markers/search?city=amsterdam&format=geojson&perPage=100" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "108322",
      "geometry": { "type": "Point", "coordinates": [4.8922, 52.3731] },
      "properties": {
        "@type": "Marker",
        "id": "108322",
        "title": "Big cat",
        "…": "…"
      }
    }
  ],
  "page": 1,
  "perPage": 100,
  "total": 1234
}
```

Just like everywhere in GeoJSON, coordinates are longitude first, then latitude.