# Find

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

List one type of record, such as properties, sales, permits or loans, filtered with `where` clauses, inside a place or around a point. Rows cost $1 per 1,000. A count is free.

```endpoint
GET /v1/find/{type}
POST /v1/find/{type}
```

## Parameters

| Name | Type | Description |
|---|---|---|
| `type` | path | What to list: `properties`, `sales`, `permits`, `tax_notices`, `distress_filings`, `recorded_loans`, `cmbs_loans`, `reit_properties`, `sba_loans`, `sba_lenders`, `warn_notices`, `listings`, `facilities`, `establishments`, `government_comps`. See [types and fields](#types-and-fields). |
| `where` | string, repeats | One clause, such as `building_sqft >= 50000`. Repeat it for more; all must match. Up to 20. See [the where grammar](#the-where-grammar). |
| `in` | string | A place: a city (`Oakland, CA`), a county (`Maricopa County, AZ`), a ZIP code (`60614`), or a neighborhood of New York City or San Francisco (`Upper West Side`). Neighborhood names don't resolve elsewhere: send a ZIP code, `lat` and `lng` with `radius_m`, or `within`. |
| `near` | string | A property ID, or `longitude,latitude` (longitude first). |
| `lat` | number | Latitude of a point, -90 to 90. Send with `lng` instead of `near`. |
| `lng` | number | Longitude of a point, -180 to 180. Send with `lat` instead of `near`. |
| `radius_m` | number | Meters around `near` or `lat` and `lng`, from 50 to 50,000. Default one mile (1,609). |
| `sort` | string | A sort the type takes, listed under each [type](#types-and-fields). A leading `-` means largest or newest first. Field names differ by type: `properties` take `-last_sale_date`, `sales` take `-sale_date`, and `permits` take no sort. |
| `limit` | integer | Rows per page, up to 100. Default 25. |
| `cursor` | string | `next_cursor` from the previous page. |
| `count` | boolean | `properties` and `sales`: the number of matches instead of rows, free. Other types don't count: page their rows with `cursor` until `has_more` is `false`. |
| `stats` | string | With `count`: the field to summarize with a median and quartiles. Default `building_sqft`. |
| `group_by` | string | `properties` only. `owner` ranks owners by how much they hold, with affiliates combined. |
| `max_cost_usd` | number | Refuse the call if a full page could cost more on your plan. |

`POST` takes the same names as a JSON body, with `where` as an array and `lat` and `lng` as numbers, plus `within` for properties: a GeoJSON `Polygon` or `MultiPolygon` (or a `Feature` holding one) to search inside instead of `in` or `near`. Up to 8 polygons of up to 40 vertices each, outer rings only, longitude first. A `within` page's `next_cursor` goes back with the same `within`.

To search around a point, send `lat` and `lng` with `radius_m`, such as `lat=37.8044&lng=-122.2712&radius_m=800`. It's the same as `near=-122.2712,37.8044`; send one or the other, not both. Sales near something are comparables, so `sales` takes a property ID in `near`, not a point.

## Request

```curl
curl --get "https://api.westkite.com/v1/find/properties" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "in=Austin, TX" \
  --data-urlencode "where=property_type = office" \
  --data-urlencode "where=building_sqft >= 50000" \
  --data-urlencode "where=held_years >= 15" \
  --data-urlencode "sort=-building_sqft"
```

```typescript
const params = new URLSearchParams({ in: "Austin, TX", sort: "-building_sqft" });
for (const clause of ["property_type = office", "building_sqft >= 50000", "held_years >= 15"]) {
  params.append("where", clause);
}
const res = await fetch(`https://api.westkite.com/v1/find/properties?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` },
});
const { data, billing } = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.westkite.com/v1/find/properties",
    params=[
        ("in", "Austin, TX"),
        ("where", "property_type = office"),
        ("where", "building_sqft >= 50000"),
        ("where", "held_years >= 15"),
        ("sort", "-building_sqft"),
    ],
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
body = res.json()
```

## Response

```json 200
{
  "data": {
    "type": "properties",
    "properties": [
      {
        "id": "property:3f2b9c1e-…",
        "address": "6836 Austin Center Blvd, Austin, TX 78731",
        "property_type": "Office",
        "building_sqft": 150220,
        "year_built": 1984,
        "held_years": 18
      }
    ],
    "next_cursor": "cur_41b0…"
  },
  "missing": [],
  "billing": {
    "operation_id": "op_7c20…",
    "operation": "find",
    "charged_usd": 0.001,
    "balance_usd": 9.96
  },
  "request_id": "req_2a9f…"
}
```

The charge is per row returned: a full page of 25 rows is $0.025. Pages come back whole, so an answer can hold a few rows more than `limit`, but a call never costs more than `limit` rows. To size a market before you pay for rows, ask for a count:

```curl
curl --get "https://api.westkite.com/v1/find/properties" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "in=Oakland, CA" \
  --data-urlencode "where=property_type = office" \
  --data-urlencode "count=true" \
  --data-urlencode "stats=last_sale_price"
```

For a whole market, use an [export](https://westkite.com/docs/api/exports.md) instead of paging: it returns one file with an exact total.

## The where grammar

Each clause is one string: `field op value`. It reads the same in a query string, a JSON array or the CLI's `--where`.

| Operator | Means | Example |
|---|---|---|
| `=` | Equals | `zoning = C-2` |
| `!=` | Leaves one out. `property_type` and `owner_type` only. | `owner_type != government` |
| `~` | Contains | `owner ~ Prologis` |
| `>=` | At least | `last_sale_price >= 1000000` |
| `<=` | At most | `year_built <= 1960` |
| `between` | Inclusive range | `units between 2 and 10` |
| `in` | Any of | `property_type in office,retail` |
| `is known` | Has a value | `flood_zone is known` |
| `is unknown` | Has no published value | `last_sale_date is unknown` |

- Bounds are inclusive. `>` and `<` are refused rather than guessed, so a strict bound is never widened without you knowing.
- Numbers may carry commas: `1,000,000`. `true` and `false` are typed. Quotes around a value are optional.
- Dates are `YYYY-MM-DD`. A bare year means its first day in a lower bound and its last day in an upper one, so `last_sale_date between 2024 and 2025` covers both years.
- Field names are snake case, as results name them. Camel case, like `lastSalePrice`, is read the same.
- A field the type doesn't have is refused with the list of fields it does have.

## Types and fields

A field a type doesn't take is refused with [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) and the list of fields it does take, so an agent can correct itself. [Fields](https://westkite.com/docs/api/fields.md) lists every field below as data, with its type, unit, operators, values and how much of the data carries it. The [API reference](https://westkite.com/docs/api/reference.md#find-types-and-fields) lists them all, generated from the API itself.

### properties

Parcels and buildings. Takes `in`, `near`, `radius_m`, `sort`, `cursor`, `count` with `stats`, and `group_by=owner`.

| Field | Operators | Notes |
|---|---|---|
| `property_type` | `=`, `in`, `!=` | `Office`, `Industrial`, `Retail`, `Multifamily`, `Land`, `Residential`, `Hospitality`, `Mixed use`, `Civic / institutional`. `!=` leaves one type out. |
| `owner` | `~`, `=` | `~` matches the owner of record. `=` is a company with its affiliates, such as `owner = Blackstone`, and needs `in`. |
| `last_sale_date` | `>=`, `<=`, `=`, `between`, `is known` | `YYYY-MM-DD` |
| `last_sale_price` | `>=`, `<=`, `=`, `between`, `is known` | Dollars |
| `building_sqft`, `lot_sqft` | `>=`, `<=`, `=`, `between`, `is known` | Square feet |
| `year_built`, `stories`, `units` | `>=`, `<=`, `=`, `between`, `is known` | |
| `bedrooms`, `bathrooms` | `>=`, `<=`, `=`, `between`, `is known` | |
| `held_years` | `>=`, `<=`, `=`, `between`, `is known` | Years since the owner of record took title |
| `market_value`, `assessed_value`, `tax_amount` | `>=`, `<=`, `=`, `between`, `is known` | From the assessor. Market value is the assessor's, not an appraisal. |
| `zoning`, `flood_zone`, `subtype` | `=`, `~`, `is known` | As the publisher writes them |
| `street` | `=` | The street the property's address is on, such as `Willis Ave` |
| `zoning_class` | `=` | `commercial`, `industrial`, `residential`, `mixed use`. Read from the zoning code's opening letters: a reading, not a legal finding. |
| `owner_type` | `=`, `!=` | `government`, `nonprofit`, `llc`, `corporation`, `trust`, `estate`, `individual`. Read from the owner name. `!=` leaves one class out; repeat it for more. |
| `owner_occupied` | `=` | `yes`: the owner runs a business registered at the address |
| `signal` | `=` | Long-held, Underbuilt, Recent permit, Tenant change |
| `building_to_lot_ratio` | `<=` | Building area over lot area, for underbuilt sites. 0.5 is a common screen. |
| `buildable_sqft`, `unused_buildable_sqft` | `>=`, `<=`, `between` | New York City estimates from lot area and zoning |
| `wetland_pct`, `floodplain_pct` | `>=`, `<=`, `=`, `between`, `is known`, `is unknown` | Percent of the parcel, 0 to 100: mapped wetland, and the 100-year floodplain. `flood_sfha_pct`, the record's name, reads the same as `floodplain_pct`. |
| `upland_acres`, `largest_upland_acres` | `>=`, `<=`, `=`, `between`, `is known`, `is unknown` | Acres outside the floodplain, wetlands and water, and the largest contiguous piece of it |
| `road_frontage_ft`, `water_frontage_ft` | `>=`, `<=`, `=`, `between`, `is known`, `is unknown` | Feet of parcel edge along public roads, or along water |
| `site_access` | `=` | `landlocked` (no public road within 20 m) or `road access`. `landlocked = true` and `landlocked = false` read the same. |
| `waterfront` | `=` | `any`, or one of `bay`, `canal`, `coast`, `lake`, `pond`, `river`, `stream`, `swamp`. `waterfront_type`, the record's name, reads the same. |
| `aerial_land` | `=` | built, cleared, wooded, wet, mixed. Read from the newest public aerial photo. |
| `aerial_parking_spaces`, `aerial_loading_docks` | `>=`, `<=`, `between` | Counted from the air |
| `aerial_building_pct`, `aerial_vegetation_pct` | `>=`, `<=`, `between` | Share of the lot |
| `aerial_roof` | `=` | good, fair, poor |
| `aerial_feature` | `=` | construction, pool, solar |

Site facts and aerial readings match only parcels that have been measured. So `wetland_pct = 0` finds measured parcels with no wetland, and `wetland_pct is unknown` finds the ones not measured. What each site fact means is on [Properties](https://westkite.com/docs/api/properties.md#site-facts).

Site facts are measured county by county. Where no parcel in the searched counties has been measured for a site fact, its clause isn't applied: rows match your other clauses, `summary` says which clause was left out, and `missing` lists the field as `not_covered`.

Sorts: `held_years`, `market_value`, `assessed_value`, `last_sale_price`, `building_sqft`, `lot_sqft`, `year_built`, `last_sale_date`, each with `-` for descending.

### sales

Recorded sales. With `near` set to a property ID, these are its comparables: closed sales from deeds, with nominal deeds left out and portfolio deeds flagged. With `in`, each property's latest sale.

| Field | Operators | Notes |
|---|---|---|
| `sale_date` | `>=`, `between`, `=` | Near a property: from that date. In a place: also `<=`. |
| `price` | `>=`, `<=`, `between` | In a place only |
| `property_type` | `=` | |
| `units`, `lot_sqft`, `building_sqft` | `>=`, `<=`, `between` | |
| `portfolio` | `=` | `false` drops multi-parcel deeds. Near a property only. |

Sorts: `-sale_date` and `distance` near a property; `sale_date` and `-sale_date` in a place.

### permits

Building permits linked to properties. Takes `in`, `near`, `radius_m` and `cursor`. It takes no `sort`.

| Field | Operators | Notes |
|---|---|---|
| `date` | `>=`, `<=`, `=`, `between` | Defaults to the last 12 months |
| `date_kind` | `=` | `activity`, `filed`, `issued`, `completed` |
| `description` | `~` | A keyword or permit number |
| `status` | `=` | |
| `valuation` | `>=` | Dollars |
| `property_type` | `=`, `in` | |

### tax_notices

Parcels on published tax-distress notices. Notices are dated, so taxes may have been paid since. Sorts: `-amount`, `-notice_date`, `-times_listed`.

| Field | Operators | Notes |
|---|---|---|
| `kind` | `=`, `in` | `delinquent`, `tax_sale`, `lands_available` |
| `tax_year` | `=` | |
| `all_years` | `=` | `true` includes earlier years |
| `amount` | `>=` | Dollars owed |
| `times_listed` | `>=` | |
| `property_type` | `=`, `in` | |

### distress_filings

Court and lien filings on a parcel: mortgage foreclosures and lis pendens, notices of default or of a trustee's sale, foreclosed properties registered with a city, sheriff's sales, tax liens filed by a city, county or school district, eviction cases and probate estates. Each property is listed once, with its newest matching filing and how many it has. Coverage is the counties whose courts and recorders publish these filings; when nothing matches, `filingsCoverage` says whether West Kite could check where filings are loaded. With `checked`, `filingsLoadedFor` lists those counties in the states searched (an empty list: none loaded there yet). With `unavailable`, because the scope names no state or the check did not finish, there is no list and `missing` names `filingsLoadedFor`: zero matches is then not evidence that none exist. A filing may have been paid, dismissed or resolved since. `filedOn` is the filing's date (for a sheriff's sale, the day of the sale) and is null where the publisher gives none. Amounts differ in meaning by kind (a claim, a lien, a sale price), and one claim can cover several parcels, so they are never totalled. Names of private parties (defendants, tenants, individual lenders, heirs) are never kept; a lender or lien buyer is named only when it is an organisation. Sorts: `-filed_on` (default), `-amount`.

| Field | Type | Operators | Values | Notes |
|---|---|---|---|---|
| `kind` | enum | `=` `in` | `foreclosure`, `foreclosure_registration`, `sheriff_sale`, `tax_lien`, `eviction`, `probate` |  |
| `filed_on` | date | `>=` `<=` `between` |  |  |
| `status` | enum | `=` | `open`, `any` |  |
| `amount` | number, usd | `>=` |  |  |
| `property_type` | enum | `=` `in` | `Office`, `Industrial`, `Retail`, `Multifamily`, `Land`, `Residential`, `Hospitality`, `Mixed use`, `Civic / institutional` |  |

### recorded_loans

New York City only: each building's latest recorded financing (mortgage, CEMA or consolidation) with lender and amount. Records carry no maturity date. Sorts: `recorded_on`, `-recorded_on`, `-amount`.

| Field | Operators | Notes |
|---|---|---|
| `recorded_on` | `>=`, `<=`, `between` | |
| `amount` | `>=` | |
| `lender` | `~` | |
| `lender_kind` | `=`, `in` | `bank`, `insurer`, `nonbank`, `private`, `government` |
| `satisfied` | `=` | `true` includes satisfied loans |
| `stale` | `=` | `true` includes stale ones |
| `lots` | `<=` | Leaves out blanket loans over more lots |
| `property_type` | `=`, `in` | |

### cmbs_loans

Loans in commercial mortgage-backed securities, from servicer filings, for maturity walls and refinancing risk. `in` takes `City, ST` or a state. Sorts: `maturity`, `-balance`.

| Field | Operators | Notes |
|---|---|---|
| `maturity` | `>=`, `<=`, `between` | Default: the next 24 months |
| `state` | `=` | Two letters |
| `city` | `=`, `in` | |
| `property_type` | `=` | office, retail, multifamily, industrial, warehouse, hotel, mixed use, self storage, manufactured housing or healthcare |
| `balance` | `>=` | |

### sba_loans and sba_lenders

Published SBA 7(a) and 504 loans, and lenders ranked by them. `in` takes `County, ST` or a state.

| Field | Operators | Notes |
|---|---|---|
| `borrower`, `lender` | `~` | |
| `date` | `>=`, `<=`, `between` | |
| `amount` | `>=` | |
| `program` | `=` | `7a` or `504` |
| `status` | `=` | |
| `signal` | `=` | `recent`, `financed`, `fixed-assets`, `purchase` |
| `property_id` | `=` | |

### warn_notices

California layoff, closure and relocation notices: possible space coming back, not confirmed vacancy. `in` takes a California county.

| Field | Operators | Notes |
|---|---|---|
| `employer` | `~` | |
| `date` | `>=`, `<=`, `between` | |
| `signal` | `=` | `recent`, `large`, `closure`, `repeat` |
| `property_id` | `=` | |

### listings

Advertised spaces for sale or lease, with source evidence. Takes `in` and `limit`.

| Field | Operators | Notes |
|---|---|---|
| `transaction` | `=` | sale or lease |
| `use` | `=` | office, retail, industrial and so on |
| `sqft` | `>=`, `<=`, `between` | |
| `keyword` | `~` | |
| `property_id` | `=` | |
| `contacts` | `=` | `true` adds broker contacts |

### facilities

Schools nationwide, from the US Department of Education, and health facilities in New York State, each matched to its lot and that lot's owner. Takes `in` or `near`, and `limit` up to 50; one page, no cursor.

| Field | Operators | Notes |
|---|---|---|
| `kind` | `=`, `in` | `private_school`, `public_school`, `nursing_home`, `hospital`, `clinic`. Default: private schools, nursing homes, hospitals and clinics. |
| `owner_operates` | `=` | `true` keeps facilities whose operator's name matches the lot's owner |
| `property_type` | `=`, `in` | |

### establishments

Named businesses and operators at an address from public registers, such as bank branches, licensed premises, care facilities and schools, each with the property it stands on when one matches. Every answer says per kind and state whether a source is loaded, so no rows is never read as none. Takes `in`, `near` with `radius_m`, `limit` and `cursor`. The kinds, coverage and examples are on [Establishments](https://westkite.com/docs/api/establishments.md).

| Field | Type | Operators | Values | Notes |
|---|---|---|---|---|
| `kind` | enum | `=` `in` | `bank_branch`, `credit_union`, `liquor_license`, `snap_retailer`, `pharmacy`, `medical_practice`, `care_facility`, `health_center`, `child_care`, `school`, `post_office`, `government_facility`, `nonprofit`, `industrial_facility`, `ev_charger`, `fuel_station`, `airport`, `port_terminal`, `refinery`, `gas_storage`, `petroleum_terminal`, `wind_turbine`, `solar_farm`, `stream_gauge`, `wic_vendor`, `casino`, `short_term_rental`, `short_term_rental_market`, `campground`, `library`, `mobile_home_park`, `oil_gas_well`, `water_well`, `water_tower`, `cannabis_license`, `vehicle_dealer`, `contractor`, `consumer_lender`, `lottery_retailer`, `lodging`, `billboard`, `water_right`, `workplace`, `layoff_notice`, `federal_contractor`, `ppp_loan`, `visa_employer_worksite`, `motor_carrier`, `drug_establishment`, `sales_tax_permit`, `subsidized_housing` |  |
| `name` | string | `=` `~` |  | (business or operator name contains) or = |
| `category` | string | `=` |  | As published: main_office, on_premise, nursing_home |
| `status` | string | `=` |  | As published: open, active, pending |
| `opened_on` | date | `>=` `<=` `between` |  | YYYY-MM-DD |
| `property_id` | string | `=` |  | Establishments matched to this property |
| `linked` | boolean | `=` |  | = true (matched to one property) or = false |

### government_comps

San Francisco only: purchase prices and appraised values quoted in public government financing packets and Board legislation, near one property. Each keeps its document's status: proposed, requested, approved or completed. Takes `near` (a property ID, required), `radius_m` from 100 to 16,094 (default 3,219) and `limit` up to 100; one page, no cursor.

Market series have their own endpoint: [Markets](https://westkite.com/docs/api/markets.md). Which places each type covers is on [Data sources](https://westkite.com/docs/data.md).

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | An unknown type or field, an operator the field doesn't take, or a clause that can't be read. Also `lat` without `lng` (or the reverse), `lat` and `lng` with `near`, or degrees out of range. The message names what's allowed. |
| [`max_cost_too_low`](https://westkite.com/docs/api/errors.md#max_cost_too_low) | A full page would cost more than your `max_cost_usd`. |
| [`scope_missing`](https://westkite.com/docs/api/errors.md#scope_missing) | The key doesn't have the `data` scope. |
| [`spend_limit_exceeded`](https://westkite.com/docs/api/errors.md#spend_limit_exceeded) | The key's monthly cap would be passed. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | Your balance can't cover the page. |
| [`rate_limited`](https://westkite.com/docs/api/errors.md#rate_limited) | Too many requests this minute. |
