# Images

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

Returns an aerial photo of a property with its parcel outline drawn on it, as a JPEG, or its metadata as JSON. Free.

```endpoint
GET /v1/properties/{id}/image
```

## Parameters

| Name | Type | Description |
|---|---|---|
| `id` | path | A property ID. |
| `size` | integer | Width and height in pixels: 256, 512, 768 or 1024. Default 1024. |
| `format` | string | `jpeg` (default), or `json` for the photo's source, year flown, credit and outline, and every year on record with its source, instead of the picture. |
| `year` | integer | A year from `years`, for the lot as it looked then. Leave it out for the newest photo, the first entry in `years`. |

## Request

```curl
curl "https://api.westkite.com/v1/properties/property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0/image?size=1024" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -o lot.jpg
```

```typescript
const id = "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0";
const res = await fetch(`https://api.westkite.com/v1/properties/${id}/image?size=1024`, {
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` },
});
const jpeg = Buffer.from(await res.arrayBuffer());
```

```python
import os, requests

id = "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"
res = requests.get(
    f"https://api.westkite.com/v1/properties/{id}/image",
    params={"size": 1024},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
open("lot.jpg", "wb").write(res.content)
```

## Response

The body is a JPEG, not the usual JSON envelope. Its headers carry the year flown, the credit to show and the charge:

| Header | Means |
|---|---|
| `X-Imagery-Source` | The name of the imagery |
| `X-Imagery-Year` | The year it was flown, or `unknown` |
| `X-Imagery-Credit` | The credit its publisher asks for. Show it wherever you show the image. |
| `X-Imagery-License` | `public-domain`, `open`, `no-restriction-stated`, or `permission` for imagery its publisher granted West Kite to serve (NYC's aerials back to 1924) |
| `X-Charged-USD`, `X-Balance-USD` | The charge (zero) and your balance, in place of `billing` |
| `X-Request-Id` | Quote it when you contact support |

With `format=json`:

```json 200
{
  "data": {
    "property_id": "property:3f2b9c1e-…",
    "source": "…",
    "publisher": "…",
    "year": 2024,
    "flown": "2024",
    "resolution_inches": 24,
    "license": "open",
    "license_url": "https://…",
    "credit": "…",
    "width": 1024,
    "height": 1024,
    "outline": { "type": "Polygon", "coordinates": [[[-118.2391, 34.0287], [-118.2386, 34.0287], [-118.2386, 34.0283], [-118.2391, 34.0287]]] },
    "years": [
      { "year": 2024, "source": "New York City", "publisher": "NYC OTI, served by NYS ITS Geospatial Services", "resolution_inches": 3, "license": "open" },
      { "year": 2022, "source": "USDA NAIP", "publisher": "USDA FPAC, served by USFS GTAC on GeoPlatform", "resolution_inches": 24, "license": "public-domain" }
    ],
    "available_years": [2024, 2022]
  },
  "missing": [],
  "billing": { "operation_id": "op_0b3e…", "operation": "image", "charged_usd": 0, "balance_usd": 9.98 },
  "request_id": "req_0b3e…"
}
```

`years` lists every year with a photo of the lot we may serve, newest first, and names the source each year's photo comes from. With no `year` the photo is the first entry; `year=2022` returns the 2022 entry, from the source it names. If that source does not answer, the next available source is used and `source` and `year` describe it. `available_years` is the same years as plain numbers. `year` is `null` when the flight can't be dated. USDA aerial photos go back to 2004, but each state is flown every two or three years, so the list has gaps. Newer state and county photos are listed where we have them, and in New York City every citywide flight back to 1924. When `license` is `permission`, a `permission` field names the grant; show the credit with the photo.

## Past years

Ask for a year from `years` to see the lot as it looked then, for example before a building went up:

```curl
curl "https://api.westkite.com/v1/properties/property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0/image?year=2012" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -o lot-2012.jpg
```

Where no parcel outline is on record, `outline` is `null`, a `note` says so, and the photo is centered on the property's point without a lot line.

## Errors

| Code | When |
|---|---|
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No published property with a location has that ID. |
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | A `size` or `format` it doesn't take, or a `year` with no photo of the lot. The message lists the years that have one. |
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No public imagery West Kite serves was flown over the lot, as in most of Alaska. |
| [`service_unavailable`](https://westkite.com/docs/api/errors.md#service_unavailable) | The imagery's publisher didn't answer just now. Retry shortly. |
