> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeur.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and topics

> Find markets by what they are about, in plain language.

## Search never comes back empty

`GET /v1/search` finds events for free text and labels every result with how it was found, strongest first:

| `match`    | Meaning                                                                                                                                                                                                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `match`    | Every word matched a title, outcome or category (shorthand such as *dems*, *gop*, *btc*, *fed* included, and the last word as a prefix so results follow typing), or the query names a person, team, place or subject the market is about, however its title is worded. |
| `similar`  | Some words matched, a title is close in spelling, or the market means nearly the same thing.                                                                                                                                                                            |
| `related`  | Trending in the category the query is about, named in `related_category`.                                                                                                                                                                                               |
| `trending` | Trending anywhere.                                                                                                                                                                                                                                                      |

Misspellings are replaced by the closest word listings use and reported in `corrected_query`. An empty `q` lists what is trending.

```bash theme={null}
curl "https://api.routeur.app/v1/search?q=chiefs" -H "X-API-Key: $ROUTEUR_API_KEY"
```

"Chiefs" finds *Indianapolis vs Kansas City*: markets are labeled with the teams, people and places they are about, so a nickname finds a title that never uses it.

## Plain-language filters

Words that describe a filter are read as one, and removed from what is searched:

```bash theme={null}
curl -G "https://api.routeur.app/v1/search" \
  --data-urlencode "q=dem senate races closing this month under 30c" \
  -H "X-API-Key: $ROUTEUR_API_KEY"
```

searches for *dem senate races*, keeps markets closing within a month whose leading outcome costs under 30¢, and returns what it understood:

```json theme={null}
{
  "query": "dem senate races",
  "filters": [
    { "kind": "closing", "label": "Closing this month", "value": "30" },
    { "kind": "price", "label": "Under 30¢", "value": "0-30" }
  ]
}
```

Also understood: a venue name, *on both venues*, *longshots*, *coin flips*, *favorites*, *movers*, *closing today / this week / this month*, and amounts such as *over \$50k traded*. The same filters can be set as parameters (`venue`, `category`, `cross_venue`, `closing`, `price_min`, `price_max`, `min_volume`, `moved`), and parameters win over words. With filters on, results can be empty: they are what you asked for.

## Topics

Every listed event is labeled with the people, teams, places and subjects it is about. `GET /v1/topics` lists the most common, with their category, what they traded today and their leading event; `GET /v1/topics/{slug}` returns the events about one, most traded first, with the topics that appear beside it.

```bash theme={null}
curl "https://api.routeur.app/v1/topics/politics" -H "X-API-Key: $ROUTEUR_API_KEY"
```

<Note>
  `GET /v1/markets?q=` is a different tool: it searches market titles by spelling similarity and pages by cursor, for when you need individual markets rather than events.
</Note>