# Nearby infrastructure

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

Returns transport, utility and brand features near a property or a point, nearest first, each with its distance, direction and source. `/v1/nearby` reads every kind at once; transport, utilities and brands have their own endpoints, and power has its own [report](https://westkite.com/docs/api/power.md). These four are $0.01 a call.

```endpoint
GET /v1/nearby
GET /v1/transport
GET /v1/utilities
GET /v1/brands
```

| Endpoint | Kinds | Price |
|---|---|---|
| `GET /v1/nearby` | Every kind below, and `brands` | $0.01, or $0.05 when you ask for a power kind |
| `GET /v1/transport` | `interstates`, `highways`, `highway_ramps`, `truck_routes`, `local_roads`, `rail_lines`, `rail_sidings`, `rail_crossings`, `intermodal_terminals`, `airports`, `ports`, `obstructions` | $0.01 |
| `GET /v1/utilities` | `water_systems`, `sewer_service`, `wastewater_plants`, `gas_pipelines`, `gas_utilities` | $0.01 |
| `GET /v1/brands` | `brands` | $0.01 |
| [`GET /v1/power`](https://westkite.com/docs/api/power.md) | `power_plants`, `substations`, `transmission_lines`, `electric_utilities`, `power_capacity`, `interconnection_queues` | $0.05 |

They all take the same parameters and answer in the same shape. On a domain endpoint, `kinds` narrows that domain's own kinds, and leaving it out returns all of them. Asking `/v1/nearby` for any power kind charges the power report's $0.05.

## Parameters

| Name | Type | Description |
|---|---|---|
| `property_id` | string | A property ID. Or send `lat` and `lng`. |
| `lat`, `lng` | number | A point in the United States, in decimal degrees, instead of `property_id`. |
| `kinds` | string | Comma-separated kinds, below. On `/v1/nearby` the default is `interstates,highways,rail_lines,airports,ports,gas_pipelines,water_systems`; on the others, all of the endpoint's kinds. |
| `radius_m` | number | Keep features within this many meters, 50 to 200,000, never wider than each source is searched. For `brands`, the radius read, up to 8,047 (five miles); default 1,609. |
| `limit` | integer | Features per kind, 1 to 50. Default 10. |
| `max_cost_usd` | number | Refuse the call if it costs more. |

Every kind `/v1/nearby` takes: `substations`, `transmission_lines`, `power_plants`, `electric_utilities`, `power_capacity`, `interconnection_queues`, `gas_pipelines`, `gas_utilities`, `water_systems`, `sewer_service`, `wastewater_plants`, `local_roads`, `highways`, `interstates`, `highway_ramps`, `truck_routes`, `rail_lines`, `rail_sidings`, `rail_crossings`, `intermodal_terminals`, `airports`, `ports`, `obstructions`, `elevation`, `brands`.

## Request

```curl
curl --get "https://api.westkite.com/v1/transport" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "property_id=property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0" \
  --data-urlencode "kinds=interstates,highway_ramps,rail_lines,ports"
```

```typescript
const params = new URLSearchParams({
  property_id: "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0",
  kinds: "interstates,highway_ramps,rail_lines,ports",
});
const res = await fetch(`https://api.westkite.com/v1/transport?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` },
});
const { data, missing } = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.westkite.com/v1/transport",
    params={
        "property_id": "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0",
        "kinds": "interstates,highway_ramps,rail_lines,ports",
    },
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
body = res.json()
```

## Response

```json 200
{
  "data": {
    "point": { "lat": 29.7604, "lng": -95.3698, "label": "1840 Industrial Way", "property_id": "property:3f2b9c1e-…" },
    "features": [
      {
        "kind": "highway_ramps",
        "name": "I-10 exit 768",
        "detail": null,
        "distance_m": 2092,
        "distance_miles": 1.3,
        "direction": "north",
        "source": { "id": "census-tiger-roads", "label": "TIGER/Line roads", "publisher": "U.S. Census Bureau (TIGERweb)" }
      }
    ],
    "searched": [{ "kind": "highway_ramps", "radius_m": 16093 }],
    "headlines": { "roads": "…" },
    "sources": [{ "id": "census-tiger-roads", "label": "TIGER/Line roads", "publisher": "U.S. Census Bureau (TIGERweb)" }],
    "note": "Distances are straight-line from the point. A utility or service area at 0 m covers the point; its provider confirms service to the parcel."
  },
  "missing": [{ "field": "features.ports", "reason": "not_found", "note": "None within 160,934 m." }],
  "billing": { "operation_id": "op_4a7d…", "operation": "transport", "charged_usd": 0.01, "balance_usd": 9.9 },
  "request_id": "req_4a7d…"
}
```

- **Each source has its own reach.** Substations are searched to 10 miles, power plants to 15 and ports to 100. `searched` says how far each kind was searched; `radius_m` only narrows it.
- **Rail service.** `rail_sidings` are sidings, industry track and yards within 3 miles, where a railroad can set out cars: the sign of a site rail can serve, though the railroad decides. `rail_crossings` are highway-rail crossings within 1 mile from the FRA crossing inventory, with position, public or private, railroad, through trains a day, timetable speed and road traffic.
- **Tall structures.** `obstructions` are towers, stacks, buildings and cranes within 2 miles from the FAA Digital Obstacle File, with height above ground and above sea level. Not every tall structure is filed.
- **Distances are straight-line.** A utility or service area at 0 m covers the point. The provider confirms service to the parcel.
- **Brands** come from stored Overture Maps places in New York City, Houston, central and southwest Florida and Atlanta: `brands` lists the chains and the tenant mix in the radius. Elsewhere, `missing` lists `brands` as `not_covered`. Live Google Maps listings stay in the app.

A kind that found nothing in its reach is in `missing` as `not_found`. A call that finds nothing at all costs nothing.

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | Both or neither of `property_id` and `lat`/`lng`, a point outside the United States, an unknown kind, or a `radius_m` or `limit` out of range. |
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No published property with a location has that ID. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | Your balance can't cover $0.01. |
