# Search markers

`GET` `https://streetartcities.com/api/markers/search`

Find artworks and other places by keyword, country, city, type or tag, or near a spot on the map. Results are a lighter version of what [Get a marker](/markers-api/reference/get-a-marker/) gives you, without images, attributes and artist details.

## Query parameters

- **q** `string` · max length: 200
  Words to look for in the title, artists, address and tags
- **country** `string` · pattern: ^[A-Za-z]{2}$
  Two-letter country code, like `NL`
- **city** `string` · pattern: ^[\w-]+$
  City ID, like `amsterdam`
- **type** `string` · pattern: ^[\w-]+$
  Marker type, like `artwork` or `legal_wall`
- **status** `string` · default: active
  `active` by default. Use `removed` for artworks that are gone, or `all` for everything
  Allowed values: `active`, `inProgress`, `removed`, `all`
- **tag** `string` · max length: 100
  Only markers with this tag
- **artist** `string` · pattern: ^[\w-]+$
  Only markers by this artist, like `banksy`
- **lat** `number` · >= -90 · <= 90
  Latitude, to find markers near a spot (use with `lng`)
- **lng** `number` · >= -180 · <= 180
  Longitude, to find markers near a spot (use with `lat`)
- **radius** `number` · > 0 · <= 100 · default: 5
  How far from `lat` and `lng` to look, in km (5 by default)
- **sort** `string`
  `distance` when you pass `lat` and `lng`, otherwise `relevance` when you pass `q`, and `newest` when you don't
  Allowed values: `relevance`, `distance`, `newest`, `oldest`
- **format** `string` · default: json
  `geojson` gives a GeoJSON FeatureCollection instead
  Allowed values: `json`, `geojson`
- **updatedSince** `string` · date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  Only what changed since this time, like `2026-09-01T00:00:00Z`
- **page** `integer` · >= 1 · <= 9007199254740991 · default: 1
  Which page of results, starting at 1
- **perPage** `integer` · >= 1 · <= 100 · default: 20
  How many results per page (20 by default, at most 100)

## Requirements

Needs an [access token](/authentication/tokens/). When using OAuth, the token needs the [`markers:read`](/authentication/scopes/) scope.

## Responses

### `200` The markers that match

- **items** `array Marker[]` — required
  - _Array of Marker_
    - **@type** `string` · const: Marker — required
    - **id** `string` — required
    - **href** `string` — required
      Link to the marker on Street Art Cities
    - **city** `object`
      The city it's in. Missing when it isn't in a city
      - **id** `string` — required
      - **title** `string`
    - **country** `string`
      Two-letter country code, like `NL`
    - **countryName** `string`
    - **lat** `number` — required
    - **lng** `number` — required
    - **address** `string`
    - **type** `string` — required
      Marker type, like `artwork` or `legal_wall`
    - **title** `string`
    - **status** `string`
      `active`, `inProgress` or `removed`
    - **description** `string`
      Can contain simple HTML, like links and line breaks
    - **artists** `array object[]` — required
      The artists who made it
      - _Array of object_
        - **id** `string` — required
        - **title** `string` — required
        - **href** `string` — required
    - **artistsString** `string` — required
      Names of the artists, comma separated
    - **tags** `array string[]` — required
    - **thumbnail** `string`
      Link to a small image
    - **likes** `number` — required
    - **createdAt** `string`
    - **updatedAt** `string`
    - **images** `array object[]`
      Pictures, the first one is the main one. Not in search results
      - _Array of object_
        - **id** `string`
        - **url** `string` — required
    - **attributes** `object`
      Extra details, like the year it was made. Not in search results
      - ***** `any`
    - **distance** `number`
      Meters from `lat` and `lng`, when searching by distance. Only in search results
- **page** `number` — required
- **perPage** `number` — required
- **total** `number` — required
  How many markers match, over all pages

### `400` Invalid request

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`

### `401` Not logged in

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`

### `403` The app doesn't have the markers:read scope

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`