# Search API

Search discovers canonical STAP records by query, place, radius, and optional
filters. It searches canonical entities, listings, and requests rather than raw
space-time entries.

## GET /api/v1/search

Authentication: none.

Query parameters:

| Parameter                          | Type    | Required | Meaning                                               |
| ---------------------------------- | ------- | -------- | ----------------------------------------------------- |
| `query`                            | string  | Yes      | Search text; must be at least one character.          |
| `latitude`                         | float   | Yes      | Search origin latitude.                               |
| `longitude`                        | float   | Yes      | Search origin longitude.                              |
| `radius_meters`                    | integer | Yes      | Search radius from `1` to `100000`.                   |
| `canonical_type`                   | string  | No       | `entity`, `listing`, `request`, or `mixed`.           |
| `filters`                          | string  | No       | Free-form filter text for the search service.         |
| `response_must_include_dimensions` | string  | No       | Dimensions the response should try to include.        |
| `max_results`                      | integer | No       | Number of results from `1` to `50`; defaults to `10`. |

Example:

```http
GET /api/v1/search?query=window%20suppliers&latitude=44.4949&longitude=11.3426&radius_meters=25000&canonical_type=entity&max_results=10
```

The endpoint returns `422` when `latitude`, `longitude`, or `radius_meters` is
missing.

Response fields:

| Field            | Meaning                      |
| ---------------- | ---------------------------- |
| `query`          | Echoed query.                |
| `canonical_type` | Effective result type scope. |
| `origin`         | Search origin details.       |
| `radius_meters`  | Search radius.               |
| `max_results`    | Result limit.                |
| `results`        | Ranked canonical results.    |

Each result includes `target_canonical_table`, `target_canonical_id`,
`result_type`, `primary_display_name`, `primary_features`, `context`,
`location`, `matched_fields`, `requested_dimensions`, `scores`,
`progressive_disclosure`, and optional `provenance`.