# us.off-the-clock.searchRecords

> Published by [off-the-clock.us](https://lexicon.garden/identity/did:plc:tevv7zpavtjtsvqrrwwipobt)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:tevv7zpavtjtsvqrrwwipobt/us.off-the-clock.searchRecords)
- [Documentation](https://lexicon.garden/lexicon/did:plc:tevv7zpavtjtsvqrrwwipobt/us.off-the-clock.searchRecords/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:tevv7zpavtjtsvqrrwwipobt/us.off-the-clock.searchRecords/examples)

## Definitions

### `us.off-the-clock.searchRecords#hit`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `distanceKm` | `string` | No | For near: the distance in kilometres from the point to the record's nearest place, a decimal. |
| `record` | `union` | Yes |  |
| `score` | `string` | Yes | The mode's own number as a decimal: BM25 made positive for keyword and text, cosine similarity for semantic, 0 for a search by place alone. Lexicons carry no floats. |
| `snippet` | `string` | No | The matched text with each match between [ and ]. |

### `us.off-the-clock.searchRecords`

**Type**: `query`

Posts, events, bookmarks and polls of one content space the viewer reads, matching every condition given: words (keyword), a full-text query (text) or a meaning (semantic), an H3 cell, a radius around a point, a bookmark's domain and a tag. Only records the viewer may see are answered, never another space's. SearchUnavailable is answered for mode=semantic before any other parameter is read, so a call without q tells a client whether meaning search is on.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `collection` | `string` (nsid) | No | Posts, events, bookmarks or polls; all four when absent. |
| `cursor` | `string` | No |  |
| `domain` | `string` | No | Bookmarks whose subject's host is this domain or a subdomain of it, case-insensitive. |
| `from` | `string` (datetime) | No | Records sorted at or after this time. |
| `h3` | `string` | No | An H3 cell index in hexadecimal, at resolution 4 to 10. |
| `limit` | `integer` | No |  |
| `mode` | `string` | No |  |
| `near` | `string` | No | A point as decimal degrees, latitude,longitude. |
| `q` | `string` | No | Required unless h3, near, domain or tag is given. |
| `space` | `string` (tid) | Yes | The pair's TID. |
| `tag` | `string` | No | Bookmarks carrying this tag, case-insensitive. |
| `until` | `string` (datetime) | No | Records sorted before this time. |
| `within` | `string` | No | The radius around near in kilometres, a decimal from 0.1 to 100; 5 by default. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cursor` | `string` | No |  |
| `hits` | `array` | Yes |  |
| `mapUrl` | `string` (uri) | No | For a search by place: a signed map of this page's first ten hits, numbered in order (IMG-14), when a map provider is configured. |
| `noPlaces` | `boolean` | No | True on a search by place that found nothing in a space where no record has a place yet. |

#### Errors

- **InvalidRequest**
- **NotSpaceMember**
- **SearchUnavailable**: mode=semantic on a site with no embeddings endpoint.

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "hit": {
      "properties": {
        "distanceKm": {
          "description": "For near: the distance in kilometres from the point to the record's nearest place, a decimal.",
          "maxLength": 16,
          "type": "string"
        },
        "record": {
          "refs": [
            "us.off-the-clock.defs#postView",
            "us.off-the-clock.defs#eventView",
            "us.off-the-clock.defs#bookmarkView",
            "us.off-the-clock.polls.pollView"
          ],
          "type": "union"
        },
        "score": {
          "description": "The mode's own number as a decimal: BM25 made positive for keyword and text, cosine similarity for semantic, 0 for a search by place alone. Lexicons carry no floats.",
          "maxLength": 32,
          "type": "string"
        },
        "snippet": {
          "description": "The matched text with each match between [ and ].",
          "maxLength": 2000,
          "type": "string"
        }
      },
      "required": [
        "record",
        "score"
      ],
      "type": "object"
    },
    "main": {
      "description": "Posts, events, bookmarks and polls of one content space the viewer reads, matching every condition given: words (keyword), a full-text query (text) or a meaning (semantic), an H3 cell, a radius around a point, a bookmark's domain and a tag. Only records the viewer may see are answered, never another space's. SearchUnavailable is answered for mode=semantic before any other parameter is read, so a call without q tells a client whether meaning search is on.",
      "errors": [
        {
          "name": "InvalidRequest"
        },
        {
          "name": "NotSpaceMember"
        },
        {
          "description": "mode=semantic on a site with no embeddings endpoint.",
          "name": "SearchUnavailable"
        }
      ],
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "cursor": {
              "type": "string"
            },
            "hits": {
              "items": {
                "ref": "#hit",
                "type": "ref"
              },
              "type": "array"
            },
            "mapUrl": {
              "description": "For a search by place: a signed map of this page's first ten hits, numbered in order (IMG-14), when a map provider is configured.",
              "format": "uri",
              "type": "string"
            },
            "noPlaces": {
              "description": "True on a search by place that found nothing in a space where no record has a place yet.",
              "type": "boolean"
            }
          },
          "required": [
            "hits"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "collection": {
            "description": "Posts, events, bookmarks or polls; all four when absent.",
            "format": "nsid",
            "knownValues": [
              "app.bsky.feed.post",
              "community.lexicon.calendar.event",
              "community.lexicon.bookmarks.bookmark",
              "us.off-the-clock.polls.poll"
            ],
            "type": "string"
          },
          "cursor": {
            "type": "string"
          },
          "domain": {
            "description": "Bookmarks whose subject's host is this domain or a subdomain of it, case-insensitive.",
            "maxLength": 253,
            "type": "string"
          },
          "from": {
            "description": "Records sorted at or after this time.",
            "format": "datetime",
            "type": "string"
          },
          "h3": {
            "description": "An H3 cell index in hexadecimal, at resolution 4 to 10.",
            "maxLength": 16,
            "type": "string"
          },
          "limit": {
            "default": 25,
            "maximum": 50,
            "minimum": 1,
            "type": "integer"
          },
          "mode": {
            "default": "keyword",
            "knownValues": [
              "keyword",
              "text",
              "semantic"
            ],
            "maxLength": 16,
            "type": "string"
          },
          "near": {
            "description": "A point as decimal degrees, latitude,longitude.",
            "maxLength": 64,
            "type": "string"
          },
          "q": {
            "description": "Required unless h3, near, domain or tag is given.",
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "space": {
            "description": "The pair's TID.",
            "format": "tid",
            "type": "string"
          },
          "tag": {
            "description": "Bookmarks carrying this tag, case-insensitive.",
            "maxLength": 64,
            "type": "string"
          },
          "until": {
            "description": "Records sorted before this time.",
            "format": "datetime",
            "type": "string"
          },
          "within": {
            "description": "The radius around near in kilometres, a decimal from 0.1 to 100; 5 by default.",
            "maxLength": 16,
            "type": "string"
          }
        },
        "required": [
          "space"
        ],
        "type": "params"
      },
      "type": "query"
    }
  },
  "id": "us.off-the-clock.searchRecords",
  "lexicon": 1
}
```