# Properties

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

Read a property record: its facts, including the site facts measured over the parcel, and the parts you ask for: the owner of record and the research behind it, sales, assessments, zoning, permits, planning, loans and the parcel outline. A record costs $0.01, whatever parts you ask for.

```endpoint
GET /v1/properties/{id}
POST /v1/properties/batch
```

## Parameters

| Name | Type | Description |
|---|---|---|
| `id` | path | A property ID from search or find: `property:<uuid>` or the bare UUID. |
| `parts` | string | Comma-separated parts to include, or `all` for every part. Default `overview`. A record costs $0.01 whatever parts you ask for. |
| `max_cost_usd` | number | Refuse the call if it costs more. |

| Part | Contains |
|---|---|
| `overview` | Address, parcel, property type, lot and building size, year built, units, the owner of record and coordinates, and `site_facts` where they're stored |
| `owner` | Saved ownership research: the owner of record, the people and companies behind it, what contacts can be revealed, and sources. It never starts research, and never includes a person's email or phone. |
| `sales` | Every recorded sale, newest first: date, price, buyers, sellers and document number. See [sales](#sales). |
| `assessments` | Every assessment roll, newest first: assessed, market and taxable values, tax, and the roll's building and land characteristics. See [assessments](#assessments). |
| `zoning` | The zoning code, the district on the national zoning map, zoning map districts, published FAR limits, plan designations and, in New York City, floor area by use. See [zoning](#zoning). |
| `permits` | Every building permit, newest first: number, work, status, filed, issued and completed dates, and status history. See [permits](#permits). |
| `planning` | Planning applications and planning records at the lot, where the city publishes them. See [planning](#planning). |
| `fields` | Every published field on the record, as the source names it, and `site_facts` where they're stored |
| `events` | Violations, inspections and other dated city records, where the city publishes them, with `events_cursor` for more. |
| `outline` | The parcel outline as a GeoJSON Feature. See [outline](#outline). |
| `loans` | CMBS loans from SEC filings, active HUD/FHA mortgages and, in New York City, mortgages recorded against the lot. See [loans](#loans). |

## Request

```curl
curl "https://api.westkite.com/v1/properties/property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0?parts=owner,sales" \
  -H "Authorization: Bearer $WESTKITE_API_KEY"
```

```typescript
const id = "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0";
const res = await fetch(`https://api.westkite.com/v1/properties/${id}?parts=owner,sales`, {
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` },
});
const { data, missing } = await res.json();
```

```python
import os, requests

id = "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"
res = requests.get(
    f"https://api.westkite.com/v1/properties/{id}",
    params={"parts": "owner,sales"},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
body = res.json()
```

## Response

```json 200
{
  "data": {
    "id": "property:3f2b9c1e-…",
    "property": {
      "id": "property:3f2b9c1e-…",
      "address": "1955 Example St",
      "city": "Oakland",
      "state": "CA",
      "property_type": "Industrial",
      "building_sqft": 48200,
      "lot_sqft": 87120,
      "zoning_code": "M-30",
      "zoning_class": "industrial",
      "flood_zone": "X",
      "owner_name": "Hadley Brothers LLC",
      "owner_type": "llc",
      "held_years": 55,
      "last_sale_price": null,
      "flood_sfha_pct": 0,
      "wetland_pct": 0,
      "upland_acres": 2,
      "largest_upland_acres": 2,
      "landlocked": false,
      "road_frontage_ft": 312.5,
      "water_frontage_ft": 0,
      "waterfront_type": null,
      "assemblage": {
        "id": "assemblage:5f0c…",
        "parcel_count": 3,
        "property_ids": ["property:1a2b…", "property:3c4d…", "property:5e6f…"],
        "more_available": false,
        "combined_acres": 6.42,
        "basis": "derived: adjoining parcels (touching or within 10 m) with the same normalized owner"
      }
    },
    "sales": {
      "sales": [
        {
          "id": "8c1e…",
          "basis": "recorded_sale",
          "date": "1971-06-14",
          "date_precision": "day",
          "recording_date": "1971-06-21",
          "document_number": "1971-118204",
          "transfer_type": "GRANT DEED",
          "qualification": "unknown",
          "price_scope": "individual",
          "price": null,
          "transaction_price": null,
          "allocated_price": null,
          "currency": "USD",
          "lot_count": 1,
          "buyers": ["HADLEY BROTHERS LLC"],
          "sellers": ["PACIFIC CANNING CO"],
          "source_id": "alameda-recorder"
        }
      ],
      "more_available": false,
      "sources": [{ "id": "alameda-recorder", "label": "Alameda County Recorder", "publisher": "Alameda County", "url": "https://…", "observed_at": "2026-10-01T00:00:00Z", "effective_at": null }]
    },
    "owner": {
      "research": {
        "names_person": true,
        "owner_of_record": "Hadley Brothers LLC",
        "people": [
          {
            "person_id": "person:3f2b9c1e-…:p2",
            "name": "Walt Hadley",
            "roles": ["manager"],
            "available": { "email": true, "phone": true, "linkedin": false }
          }
        ],
        "companies": [{ "name": "Hadley Brothers LLC", "kind": "company", "roles": ["recorded_owner"], "website": null }],
        "sources": [{ "title": "Statement of Information", "url": "https://bizfileonline.sos.ca.gov/…", "publisher": "California Secretary of State" }],
        "summary": ["Hadley Brothers LLC has held the building since 1971."]
      },
      "last_researched_at": "2026-11-02T18:40:11Z",
      "research_running": false
    }
  },
  "missing": [
    { "field": "owner.research", "reason": "not_found", "note": "No owner research on file. POST /v1/research runs it." }
  ],
  "billing": { "operation_id": "op_5e7a…", "operation": "property", "charged_usd": 0.01, "balance_usd": 9.98 },
  "request_id": "req_5e7a…"
}
```

The example is illustrative, and `property` is trimmed: the real record has every field listed below. A part that couldn't be read this time is `{ "not_checked": true, "retry": "…" }` and comes back in `missing` as `temporarily_unavailable`. Ask for it again on its own. Every part's schema is in the [OpenAPI description](https://api.westkite.com/v1/openapi.json): `SalesPart`, `AssessmentsPart`, `PermitsPart`, `ZoningPart`, `PlanningPart`, `LoansPart`, `OutlinePart` and `OwnerPart`.

## The parts

### Sources in a part

Every item in `sales`, `assessments`, `permits`, `zoning` and `planning` names the sources it rests on, in `source_id` or `source_ids`. The part's `sources` lists exactly those sources, each once, with `id`, `label`, `publisher`, `url`, `observed_at` (when West Kite read it) and `effective_at` (the date its data is current to, where stated). A source no item cites is never listed. `fields` lists the sources its recorded fields come from.

### Complete and empty parts

- Lists hold everything the property's record holds. `more_available: true` says the record itself holds more than it returned.
- Dates are `YYYY-MM-DD` and amounts are numbers. A value the source doesn't state is `null`, never zero.
- A part with nothing in it comes back empty, and `missing` names it with the reason: `not_on_record` (no sale or planning record), `not_published` (no roll or zoning published), `not_covered` (West Kite holds no such records for the county yet, so an empty list isn't evidence of none) or `not_found` (none linked to this property in the records West Kite holds).

### Sales

`sales` is every recorded sale, newest first.

| Field | Meaning |
|---|---|
| `basis` | `recorded_sale`: a transfer the recorder or a sales file publishes. `assessor_roll`: the roll's last-sale date (and price, where stated), given only when no recorded transfer is held. |
| `date`, `date_precision` | `YYYY-MM-DD`, `YYYY-MM` or `YYYY`, as precise as the source, and `day`, `month`, `year` or `unknown`. The newest sale's date matches `property.last_sale_date`. |
| `recording_date`, `document_number` | When the document was recorded, and the recorder's number |
| `transfer_type`, `qualification` | The deed or transfer type, and whether the publisher counts it as an arm's-length sale |
| `price_scope` | `individual` (one property), `portfolio` (one price for several), or `unknown` when the source doesn't say |
| `price` | US dollars attributable to this property: the whole price of an individual sale, or its allocated share of a portfolio. `null` when neither is stated. |
| `transaction_price`, `allocated_price` | The transaction's total as recorded, and this property's allocated share of a portfolio |
| `lot_count`, `buyers`, `sellers` | Parcels conveyed, and grantees and grantors as recorded |

### Assessments

`assessments` is every roll, newest first. A roll loaded twice appears once.

| Field | Meaning |
|---|---|
| `roll_year`, `state` | The roll year, and `observed`, `inferred` or another evidence state |
| `land_value`, `improvement_value`, `total_assessed_value` | The assessed values: the tax basis, not a market valuation |
| `market_value`, `market_value_label` | The publisher's own market or appraised value, and what it calls it |
| `taxable_value`, `tax_amount` | After exemptions, and the annual tax |
| `last_sale_price`, `last_sale_type` | The roll's last sale for that year |
| `characteristics` | The roll's building and land characteristics for that year, only those it states: `use_code`, `year_built`, `building_sqft`, `lot_sqft`, `stories`, `units`, `zoning_code` and more |

### Permits

`permits` is every permit, newest first: `number`, `type_code`, `title`, `description` (the work as the publisher wrote it), `status` (the publisher's current status, not proof the work was done), `filed_on`, `issued_on`, `completed_on`, `url` (the publisher's page or dataset) and `status_history`. A record that gives one date for an activity has it in `recorded_on`.

### Zoning

| Field | Meaning |
|---|---|
| `zoning_code` | The zoning code as published |
| `districts` | Districts from a city's zoning map layers: `base`, `height_bulk` or `special_use` |
| `map_district` | The district on West Kite's national zoning map at the lot's point, the same answer as [`GET /v1/zoning`](https://westkite.com/docs/api/zoning.md): local `code` and `name`, broad `class`, `jurisdiction` and `source`. `null` where the map has no district there, with the reason in `missing`. |
| `limits` | Zoning figures the assessor or land-use file publishes: built and maximum FAR by use, unused zoning floor area, historic district and landmark |
| `designations` | Plan designations an area overlay gives the lot: a General Plan land use, a transit tier, a historic zone |
| `capacity` | New York City only: floor area by use under the zoning resolution, from lot area and district. An estimate, not a zoning determination. |
| `records` | Zoning records linked to the lot, with the publisher's fields |

### Planning

`projects` (planning applications linked to the lot, with `projects_total`), `context` (planning records at or near the lot from a city's planning layers) and `records` (other planning records linked to the lot).

### Loans

`loans` (CMBS loans, the newest report linked to the property for each, with balance, rate, maturity, collateral and parties), `hud_fha` (active HUD/FHA multifamily mortgages), `recorded_debt` (New York City: mortgages, assignments and satisfactions recorded against the lot; no term is published, so no maturity), `coverage` and `rate_summary`. A field the filing doesn't report is left out.

### Outline

`outline` is the parcel outline as one GeoJSON Feature, `[longitude, latitude]` in WGS 84. It's the same outline the map draws and the [aerial image](https://westkite.com/docs/api/images.md) outlines. A property on several lots gets their union. A condominium unit leaves out the shared common lot.

| Field | Meaning |
|---|---|
| `geometry` | A `Polygon` or `MultiPolygon` |
| `properties.parcel_count`, `properties.parcel_ids` | The lots the outline joins, as `parcel:<uuid>` |
| `properties.area_sqft` | The outline's ground area in square feet, measured on the earth's surface. This isn't the assessor's lot size, which is `property.lot_sqft`. |
| `properties.simplified` | `true` when the published outline had more than 20,000 vertices and was simplified to about half a metre |

When no parcel outline is on record, `outline` is `null` and `missing` lists it as `not_published`. The property's point is still in `property.latitude` and `property.longitude`.

```bash
curl "https://api.westkite.com/v1/properties/property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0?parts=outline" \
  -H "Authorization: Bearer $WESTKITE_API_KEY"
```

## The property record

`property` comes back on every call, whatever parts you ask for. It has every field below, always. A field that is `null` isn't stated by the source, or hasn't been measured.

| Field | Meaning |
|---|---|
| `id` | `property:<uuid>` |
| `address`, `city`, `neighborhood` | As published |
| `state`, `county`, `county_fips` | Two-letter state code, county name and five-digit county FIPS code |
| `apn` | The parcel number as the county writes it |
| `coordinates`, `point_basis` | `[longitude, latitude]`, and how the point was placed: `parcel-point-on-surface`, `source-parcel-point`, `source-unit-point` or `address-point` |
| `property_kind` | The kind of record, such as `site` |
| `property_type`, `subtype` | Office, Industrial, Retail, Multifamily, Land, Residential, Hospitality, Mixed use or Civic / institutional, and the publisher's use below the type |
| `property_type_basis` | How the type was read: `source-use-code`, `use-correction`, `planning-designation` or `none` |
| `general_commercial` | `true` for a commercial parcel whose roll records no specific use |
| `building_sqft`, `lot_sqft` | Square feet, whole |
| `year_built`, `stories`, `units`, `bedrooms`, `bathrooms` | As published |
| `zoning_code` | The zoning code as published |
| `zoning_class` | See [owner type and zoning class](#owner-type-and-zoning-class) |
| `flood_zone` | The FEMA flood zone as the assessor or flood map publishes it |
| `owner_name` | The owner of record as published |
| `owner_type` | See [owner type and zoning class](#owner-type-and-zoning-class) |
| `owner_since`, `held_years` | The date the current owner took title, and whole years since |
| `last_sale_date`, `last_sale_date_precision` | `YYYY-MM-DD`, and `day` or `month` when the sale is known only to the month |
| `last_sale_price` | US dollars |
| `last_sale_portfolio_price` | A portfolio total the last sale was recorded at. Never this property's own price. |
| `market_value` | The assessor's market value in US dollars. Not an appraisal. |
| `assessed_value`, `taxable_value` | US dollars: the tax basis, and the value after exemptions |
| `tax_amount`, `valuation_year` | Annual property tax in US dollars, and the roll year of the values |
| `flood_sfha_pct`, `wetland_pct`, `upland_acres`, `largest_upland_acres`, `landlocked`, `road_frontage_ft`, `water_frontage_ft`, `waterfront_type` | See [site facts](#site-facts) |
| `assemblage` | Adjoining parcels the same owner holds, or `null`. See [owner assemblage](#owner-assemblage) |
| `updated_at` | When West Kite last rebuilt the record from its sources |

## Owner assemblage

`assemblage` is the group of neighbouring parcels this property's owner also holds. West Kite works it out from the parcel outlines and owner names; no county publishes it.

- **Neighbours.** Two parcels are neighbours when their outlines touch or lie within 10 m of each other, so a road or alley between two lots still counts.
- **Same owner.** The owner names must match once punctuation, legal forms and series numbers are read off. "Acme Holdings, L.L.C." and "ACME HOLDINGS II LLC" match. Different spellings of a name don't.
- **Chains.** A next to B next to C is one group, even when A and C are far apart.
- **Never grouped.** Government owners, since their streets and parks would join whole cities. Blank owners, condo units, and parcels on either side of a state line.

| Field | Meaning |
|---|---|
| `id` | `assemblage:<uuid>`. It stays the same while the group keeps its first member. |
| `parcel_count` | How many properties are in the group, this one included |
| `property_ids` | The members' `property:<uuid>` IDs, sorted, up to 100 |
| `more_available` | `true` when the group has more members than `property_ids` lists |
| `combined_acres` | The area of all the members' outlines together, in acres. It's measured from the outlines, not the rolls' lot areas. |
| `basis` | Always `derived: adjoining parcels (touching or within 10 m) with the same normalized owner` |

`null` means no neighbouring parcel has the same owner. Where a state isn't computed yet, or the read fails, `assemblage` is also `null`, and `missing` lists `property.assemblage` as `not_covered` or `temporarily_unavailable`. Read `null` as "none" only when `missing` doesn't list it. `POST /v1/properties/batch` lists those records under `properties.assemblage`.

## Owner type and zoning class

- `owner_type` is the owner's class, read from the owner name: `government`, `nonprofit`, `llc`, `corporation`, `trust`, `estate` or `individual`.
- `zoning_class` is `commercial`, `industrial`, `residential` or `mixed use`. It's read from the zoning code's opening letters, so C2 is commercial and M1 is industrial. It's a reading of the code, not a legal finding.

[Find](https://westkite.com/docs/api/find.md) filters on both under the same names.

## Site facts

Site facts are measured over the parcel outline, from FEMA flood maps, the National Wetlands Inventory, public road maps and USGS water maps. These eight are on `property`, and on find rows under the same names.

| Field | Unit | Meaning | Find filter |
|---|---|---|---|
| `flood_sfha_pct` | Percent of parcel, 0 to 100 | Share in the 100-year floodplain: a FEMA special flood hazard area, with a 1% annual chance of flooding | `floodplain_pct` or `flood_sfha_pct` |
| `wetland_pct` | Percent of parcel, 0 to 100 | Share that is mapped wetland | `wetland_pct` |
| `upland_acres` | Acres | Land outside the floodplain, wetlands and water | `upland_acres` |
| `largest_upland_acres` | Acres | The largest contiguous piece of that upland | `largest_upland_acres` |
| `landlocked` | `true` or `false` | `true` when no public road lies within 20 m of the parcel. `false` when one does. | `site_access` or `landlocked` |
| `road_frontage_ft` | Feet | Parcel edge along public roads | `road_frontage_ft` |
| `water_frontage_ft` | Feet | Parcel edge along water | `water_frontage_ft` |
| `waterfront_type` | Text | The kind of water the parcel fronts: bay, canal, coast, lake, pond, river, stream or swamp | `waterfront` or `waterfront_type` |

### More site facts

Records in `overview` and `fields` can carry `site_facts`, with more facts from the same measurements, at `data.overview.records[].site_facts`. A record with none stored has no `site_facts` key, and each fact inside appears only when it was measured. A share is an object of name to percent of parcel, such as `{ "X": 82.4, "AE": 17.6 }`.

| Field | Unit | Meaning |
|---|---|---|
| `parcel_gis_sqft` | Square feet | Area of the parcel outline as mapped |
| `flood_zone` | Text | The FEMA flood zone covering the largest share of the parcel. `property.flood_zone` is the zone as published, which can differ. |
| `flood_zone_shares` | Percent of parcel, by zone | Each FEMA flood zone's share of the parcel |
| `floodway_pct` | Percent of parcel | Share in a regulatory floodway |
| `flood_bfe_ft` | Feet | FEMA base flood elevation over the parcel |
| `flood_map_date` | Date | Effective date of the FEMA flood map read, `YYYY-MM-DD` |
| `deepwater_pct` | Percent of parcel | Share that is open water in the National Wetlands Inventory |
| `wetland_types` | Percent of parcel, by type | Each wetland type's share of the parcel |
| `upland_pct` | Percent of parcel | Upland share of the parcel |
| `water_pct` | Percent of parcel | Share that is water |
| `water_body_name` | Text | Name of the water the parcel fronts |
| `nearest_road_m` | Meters | Distance to the nearest public road |
| `frontage_roads` | List | The roads the parcel fronts: names, or objects naming each road |
| `frontage_surface` | Text | Surface of the fronting road: paved or unpaved |
| `unpaved_only_access` | `true` or `false` | `true` when every fronting road is unpaved |
| `vacant_class` | Text | The vacant land class read from the parcel |
| `zoning_shares` | Percent of parcel, by district | Each zoning district's share of the parcel |
| `zoning_jurisdiction` | Text | The government whose zoning map was read |
| `future_land_use` | Text | The future land use designation covering the largest share of the parcel |
| `future_land_use_description` | Text | The designation as the plan describes it |
| `future_land_use_shares` | Percent of parcel, by designation | Each designation's share of the parcel |
| `future_land_use_jurisdiction` | Text | The government whose plan was read |
| `water_service_area` | `true` or `false` | `true` when the parcel lies in a mapped public water service area |
| `water_provider` | Text | The water utility serving the area |
| `sewer_service_area` | `true` or `false` | `true` when the parcel lies in a mapped sewer service area |
| `sewer_provider` | Text | The sewer utility serving the area |
| `flwmi_drinking_water` | Text | Florida Water Management Inventory drinking water code |
| `flwmi_wastewater` | Text | Florida Water Management Inventory wastewater code |
| `plat_name` | Text | The recorded plat or subdivision the parcel lies in |
| `nearest_aadt` | Vehicles per day | Annual average daily traffic at the nearest state DOT count station within 500 m |
| `nearest_aadt_year` | Year | Year of that traffic count |
| `nearest_aadt_road` | Text | Road of that count station |
| `nearest_aadt_m` | Meters | Distance to that count station |

### Null, absent and zero

- On `property`, a fact that wasn't measured is `null`. On find rows and in `site_facts`, it's left out.
- A measured `0` or `false` is a reading. `water_frontage_ft: 0` means the parcel was measured and fronts no water. `landlocked: false` means a public road is within 20 m.
- Not measured is never zero. Don't read a `null` or a missing key as "none".
- Site facts are measured county by county. [Coverage](https://westkite.com/docs/api/coverage.md) gives the share of properties with each fact, county by county.

## Reading the owner

- `owner_of_record` is the name on the county roll. It's usually the buyer in the latest sale, not the seller. A registered agent isn't the owner.
- `owner` returns research already on file. With none, `research` is `null` and `missing` lists `owner.research` as `not_found`; start it with [owner research](https://westkite.com/docs/api/research.md). `research_running` says a run is under way.
- **Contacts ready to fetch.** When West Kite has already found a phone number, email or LinkedIn for a person, `available` marks it `true`. Call [contacts](https://westkite.com/docs/api/research.md#retrieve-contact-details) with the `person_id` and channel to get it; that's when it's charged.

## Batch retrieve properties

`POST /v1/properties/batch` returns the overview record of up to 100 properties. Each record returned costs $0.01. IDs with no published record are listed in `not_found` and are not charged.

```curl
curl https://api.westkite.com/v1/properties/batch \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "property_ids": ["property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"] }'
```

```json 200
{
  "data": { "properties": [{ "id": "property:08cdd01c-…", "address": "550 Madison Avenue", "…": "…" }], "not_found": [] },
  "missing": [],
  "billing": { "operation_id": "op_3c1e…", "operation": "property", "charged_usd": 0.01, "balance_usd": 9.97 },
  "request_id": "req_3c1e…"
}
```

The batch endpoint returns the overview only. To retrieve other parts, call `GET /v1/properties/{id}` for each property. To retrieve every property in a market, use [exports](https://westkite.com/docs/api/exports.md).

## Errors

| Code | When |
|---|---|
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No property has that ID. |
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | An ID that isn't a property ID, or an unknown part. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | Your balance can't cover $0.01. |
| [`max_cost_too_low`](https://westkite.com/docs/api/errors.md#max_cost_too_low) | You sent a `max_cost_usd` below $0.01. |
