# Search

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

Resolves an address, APN, building, owner or company name, or a point, to West Kite property IDs. Free.

```endpoint
GET /v1/search
```

## Parameters

| Name | Type | Description |
|---|---|---|
| `q` | string | An address, APN, building, owner or company name, such as `550 Madison Ave, New York` or `Prologis`. Up to 200 characters. |
| `in` | string | With `q`: a place to prefer, such as `San Francisco, CA`. |
| `lat`, `lng` | number | A point in decimal degrees. Alone, the parcel there; with `q`, options near it come first. |
| `limit` | integer | How many results for `q`. Default 20, up to 50. |

## Request

```curl
curl --get "https://api.westkite.com/v1/search" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "q=550 Madison Ave, New York"
```

```typescript
const res = await fetch(
  "https://api.westkite.com/v1/search?" + new URLSearchParams({ q: "550 Madison Ave, New York" }),
  { headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` } },
);
const { data } = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.westkite.com/v1/search",
    params={"q": "550 Madison Ave, New York"},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
data = res.json()["data"]
```

## Response

```json 200
{
  "data": {
    "results": [
      {
        "id": "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0",
        "title": "550 Madison Avenue · Manhattan · APN 6201001012910010",
        "match": "address",
        "reason": "exact",
        "exact": true,
        "city": "Manhattan",
        "state": "NY",
        "url": "https://app.westkite.com/properties/08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"
      }
    ],
    "places": []
  },
  "missing": [],
  "billing": { "operation_id": "op_1a4c…", "operation": "search", "charged_usd": 0, "balance_usd": 9.99 },
  "request_id": "req_6e0b…"
}
```

Each option says why it matched in `match`: `address`, `apn`, `owner` or `name`. Text with no house number that names an owner lists that owner's properties first. Places the text names come back in `places`; pass one's `in` to narrow the search.

When nothing matches exactly, you get the closest records West Kite holds with `"exact": false`, and `corrected_query` says what they were read as. You never get an empty guess.

Pass an `id` to [properties](https://westkite.com/docs/api/properties.md). To filter by type, size, sale or value, use [find](https://westkite.com/docs/api/find.md).

## Search by point

`lat` and `lng` return the parcels whose outline contains the point. Where parcels are stacked, such as condominiums, you get all of them. Where no outline contains the point, you get the nearest property within about 500 meters, marked `"nearest": true` with its `distance_m`, so you can tell a match from a guess. With nothing that close, `results` is empty and `missing` says `not_covered`.

```curl
curl "https://api.westkite.com/v1/search?lat=37.7880&lng=-122.3953" \
  -H "Authorization: Bearer $WESTKITE_API_KEY"
```

```json 200
{
  "data": {
    "results": [
      { "id": "property:8a41d0c2-…", "title": "88 Example St, San Francisco · Retail", "nearest": true, "distance_m": 42 }
    ]
  },
  "missing": [],
  "billing": { "operation_id": "op_9b1e…", "operation": "search", "charged_usd": 0, "balance_usd": 9.99 },
  "request_id": "req_9b1e…"
}
```

A text search that finds nothing returns empty `results` with `not_found` in `missing`.

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | Neither `q` nor both `lat` and `lng`, both at once, or a value out of range. |
| [`rate_limited`](https://westkite.com/docs/api/errors.md#rate_limited) | Too many requests this minute. Search is free but still counts. |
