# Fields

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

Lists every field a [find](https://westkite.com/docs/api/find.md) `where` clause takes, per record type: type, unit, operators, values, whether it sorts, source and coverage. Free.

```endpoint
GET /v1/fields
```

## Parameters

| Name | Type | Description |
|---|---|---|
| `type` | string | One find type, such as `properties` or `cmbs_loans`. Default: every type. |
| `county` | string | Coverage for one county: a five-digit FIPS code, `county:<FIPS>`, or a name with its state, such as `Travis County, TX`. Default: every county West Kite serves. |

## Request

```curl
curl --get "https://api.westkite.com/v1/fields" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "type=properties" \
  --data-urlencode "county=Travis County, TX"
```

```typescript
const params = new URLSearchParams({ type: "properties", county: "Travis County, TX" });
const res = await fetch(`https://api.westkite.com/v1/fields?${params}`, {
  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/fields",
    params={"type": "properties", "county": "Travis County, TX"},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
types = res.json()["data"]["types"]
```

## Response

```json 200
{
  "data": {
    "types": [
      {
        "type": "properties",
        "summary": "Properties (parcels and buildings) by location, type, size, sale, value, zoning, owner and site facts.",
        "source": "County assessor rolls and recorder records as each county publishes them; site facts measured by West Kite over the parcel outline.",
        "sort": ["updated_at", "held_years", "market_value", "assessed_value", "last_sale_price", "building_sqft", "lot_sqft", "year_built", "last_sale_date"],
        "fields": [
          {
            "name": "building_sqft",
            "type": "number",
            "unit": "sqft",
            "operators": ["=", "~", ">=", "<=", "between", "is known", "is unknown"],
            "values": null,
            "sortable": true,
            "description": ">=, <=, =, between, ~, is known",
            "source": "County assessor rolls and recorder records as each county publishes them.",
            "coverage": 0.912
          },
          {
            "name": "owner_type",
            "type": "enum",
            "unit": null,
            "operators": ["=", "!="],
            "values": ["government", "nonprofit", "llc", "corporation", "trust", "estate", "individual"],
            "sortable": false,
            "description": "= or != (leaves one class out; repeat for several): government, nonprofit, llc, corporation, trust, estate, individual",
            "source": "County assessor rolls and recorder records as each county publishes them.",
            "coverage": null
          }
        ]
      }
    ],
    "operators": ["=", "!=", "~", ">=", "<=", "between", "in", "is known", "is unknown"],
    "grammar": "Each where clause is \"field op value\": …",
    "coverage_scope": "county:48453"
  },
  "missing": [],
  "billing": { "operation_id": "op_4b1d…", "operation": "coverage", "charged_usd": 0, "balance_usd": 9.98 },
  "request_id": "req_4b1d…"
}
```

The example is trimmed to two fields.

## Reading a field

| Field | Meaning |
|---|---|
| `name` | The field as a `where` clause names it |
| `type` | `string`, `number`, `integer`, `boolean`, `date` (`YYYY-MM-DD`) or `enum` |
| `unit` | `usd`, `sqft`, `acres`, `ft`, `percent`, `ratio`, `year`, `years`, `units`, `stories` and so on; `null` for text and codes |
| `operators` | The operators find applies to this field. See [the where grammar](https://westkite.com/docs/api/find.md#the-where-grammar). |
| `values` | The values it takes, when it takes a fixed list |
| `sortable` | Whether `sort` takes it |
| `description` | What it is and how its operators behave, as find describes it. Some operators apply in one mode only, such as `<=` on a sale date with `in`. |
| `coverage` | Properties only: the share of served records in scope that carry the field, 0 to 1. `null` for other types, for fields West Kite doesn't measure, and when shares couldn't be read (then `missing` says so). |

The catalog is read from the same definitions find checks a clause against, so a field it doesn't list is refused, and every operator it lists is one find applies to that field. A low `coverage` means a filter on that field only reaches the records that carry it: a missing value is never zero.

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | A `type` find doesn't take, or a `county` that isn't a FIPS code or a county name with its state. |
