# Surroundings for AI assistants and developers

Surroundings maps travel-time catchments and estimates the residents within reach of an address. Use consistent travel settings to compare candidate locations. Population is modelled residential population. Job counts, visits, demand, and investment returns require separate evidence.

## Public examples

Read four saved snapshots without an account, key, or query debit.

```sh
curl https://www.surroundings.land/api/v1/examples
curl https://www.surroundings.land/api/v1/examples/toronto
```

The [OpenAPI 3.1 specification](https://www.surroundings.land/openapi.json) covers both the public examples and the subscriber endpoints. Public example catalog fields describe the catalog itself.

## Run a new analysis with Premium

Professional costs CAD $10/month or $99/year upfront and includes 500 completed address queries per subscription month. Business costs CAD $99/month or $990/year upfront and includes 10,000 per subscription month. Allowances reset monthly with either billing interval. Existing subscribers retain their agreed pricing and annual allowance.

1. Sign in and open [API access](https://www.surroundings.land/account/api-access). Create a key and store it securely as `SURROUNDINGS_API_KEY`. The secret is shown once. Each account has one key, valid for 90 days. Replacing or revoking it prevents new requests with the old key.
2. Send the key as a Bearer credential. This key grants access to analysis, API-created reports and usage for that subscriber. Keep it out of URLs, logs, and shared files.
3. Submit an address and a unique idempotency key. Keep that idempotency key with the address so you can safely repeat the request.

```sh
curl -sS https://www.surroundings.land/api/v1/analyses \
  -H "Authorization: Bearer $SURROUNDINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chicago-study-2026-001" \
  -d '{"address":"1311 S Keeler Ave, Chicago, IL 60623"}'
```

A new completed analysis returns HTTP 201 and a compact `report` object. Read `report.location` for the geocoded location, `report.population.bands` for cumulative estimates, and `report.market_benchmark` for available ZIP statistics. The response has a persistent `id` and a relative `links.self` path. API responses omit isochrone geometry to keep transfers small. The full map report, including geometry, is saved in the subscriber's workspace.

```sh
curl -sS "https://www.surroundings.land/api/v1/analyses/$ANALYSIS_ID" \
  -H "Authorization: Bearer $SURROUNDINGS_API_KEY"

curl -sS https://www.surroundings.land/api/v1/usage \
  -H "Authorization: Bearer $SURROUNDINGS_API_KEY"
```

### Inputs, multiple addresses, and retries

- Submit one address per request. A list of 25 lots is 25 requests with distinct idempotency keys. Keep one request active per account and gather the completed reports into a local table or file.
- New reports use Mapbox driving catchments at 15, 30, 45, and 60 minutes. Older requests may still include `travel_options`; new reports use the fixed driving catchments.
- Optional `acres` records a supplied parcel size. When omitted, the saved workspace report uses a one-acre placeholder. Travel catchments are measured from the geocoded address.
- If a connection drops or returns a transient error, resend the same input and idempotency key. A completed replay returns HTTP 200. An identical request still running returns 202. Follow `Location` after the indicated `Retry-After`. A different payload with the same key returns 409.
- HTTP 429 with `ANALYSIS_BUSY` means another API analysis is running. Retry after the delay with the same key. `QUERY_LIMIT` means the shared plan allowance is exhausted. One successful address consumes one query. Reading results, replays, and unsuccessful analyses consume no extra queries.
- For a terminal `ANALYSIS_FAILED` or `ANALYSIS_INTERRUPTED` response, check the address and travel settings, then use a new idempotency key if you decide to submit again. If you delete a saved report in the workspace, the old key cannot recreate it.

## Interpret historical and housing metrics

- `population_2024` gives cumulative WorldPop 2024 residential population. `population_change` compares 2021 and 2016 to both 2024 and 2026. Select periods by `start_year` and `end_year`.
- `area_income` gives cumulative modeled aggregate household income in 2024 USD using ACS B19025. `area_income_change` compares 2021 and 2016 to 2024.
- `housing_units` gives 2024 ACS housing estimates keyed by travel minutes. `housing_unit_change` compares 2021 and 2016 to 2024.
- `house_price_change` gives FHFA nominal percentage changes for 2021–2024 and 2016–2024 alongside the 1-, 5-, and 10-year comparisons for the origin US ZIP, with the index release date and exact endpoint years.

Each catchment comparison includes cumulative bands with `start`, `end`, `change`, and `percent_change`. Both endpoints use their shared raster coverage, so comparison endpoints may differ from standalone totals. Income, housing, and house price data are US-only. Missing values and percentages with no usable baseline are null. An older saved analysis can pick up these fields through its existing self link without using another query.

## Interpret the ZIP benchmark

For a covered US address, `market_benchmark.average_list_price` is the mean asking price from the ZIP-level housing market dataset for `reporting_month`, in USD. It describes listings in the origin ZIP, rather than the individual lot, comparable land sales, or listings throughout the drive-time area. Two lots in the same ZIP and reporting month can share a price benchmark while reaching different populations. A missing benchmark or value is returned as null.

For example, to compare the Chicago lots, use the 60-minute band as the x-axis and ZIP average list price as the y-axis. Expect one horizontal group per ZIP benchmark. Use the actual listing asking prices if you want each lot's price on the y-axis.

Both APIs label their population totals as cumulative. Use the value at the requested travel time directly. Adding the 15-, 30-, 45-, and 60-minute totals would count some residents more than once. Check the dataset version, analysis date, and geographic limits when comparing reports.

## Run a batch in the website

An opt-in background API is also available on configured deployments at `POST /api/v1/batches`. Submit `{"addresses":["<complete address>","<complete address>"]}` with the same Bearer key and a unique `Idempotency-Key`. It targets `ceil(unique addresses / 10)` concurrent analyses (100 addresses → 10 lanes; maximum 100 lanes within shared capacity), with a five-minute completion goal that provider delays and retries can exceed. It accepts 2–1,000 addresses and returns HTTP 202 with a batch ID/self link. Poll `GET /api/v1/batches/{id}`; follow `next_cursor` for status pages. `PATCH` the self link with `{"action":"pause"}`, `resume`, or `cancel`; retry a failed item with `{"action":"retry","item_id":"<uuid>","address":"<optional corrected address>"}`. `GET /api/v1/batches/{id}/export` downloads a CSV. Completed item reports are at `/api/v1/batches/{id}/items/{itemId}`. All routes enforce subscriber ownership. One unfinished background batch per account is allowed; work continues after disconnect. In-flight queries are provisionally reserved and refunded on failure. Pause/cancel stop new items; in-flight work finishes. A disabled deployment returns `BATCH_UNAVAILABLE` for new work. Use comma-separated street, city, region/postal code, and country; a detected city/US ZIP mismatch requires correcting the failed item before retrying.

Open the [Premium workspace](https://www.surroundings.land/workspace), choose **Batch**, and enter one address per line. Set a common travel mode and travel times, then run the batch. Split a 25-address list into groups of 20 and 5. Use **Copy results** to paste the completed rows into a spreadsheet. Review the failure list separately and retry only the affected addresses.

- [Premium pricing](https://www.surroundings.land/pricing)
- [Public examples](https://www.surroundings.land/workspace#examples)
- [Contact](https://www.surroundings.land/contact)
