Skip to content
Land Insights Land Insights

Add a region to the user's saved markets

POST
/api/public/v1/markets/
 
curl --request POST \
  --url https://example.com/api/public/v1/markets/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "region_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "status": "example" }'

Saves a market (county or ZIP region) to the authenticated user’s market list. Look up the region_id from the Market Stats response (its id field).

Cost: free.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
region_id
required

UUID of the region to save. Obtain from the /markets-stats/{fips}/stats/ response (its id field) or another regions response.

string format: uuid
status

Pipeline label, mirroring the in-app market board columns (e.g., ‘Backlog’, ‘Watching’, ‘Active’). Free-form string.

string
>= 1 characters
Example generated
{
  "region_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status": "example"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”
Media type application/json
object
id
required

Identifier for the saved market row.

string format: uuid
region
required

Snapshot of the saved region’s stats at response time.

object
id
required

Internal region identifier.

string format: uuid
type
required

Region type — ‘county’ for full-county stats, ‘zip’ for a single ZIP.

  • county - Whole county.
  • zip - Single ZIP code.
string
Allowed values: county zip
name
required

County name (when type=‘county’) or ZIP code (when type=‘zip’).

string
state
required

Two-letter US state code (e.g., ‘CA’).

string
county_name
required

Primary county name. For ZIP regions, the county the ZIP falls into.

string
fips
required

5-digit county FIPS code.

string
nullable
stats
required

List of statistic buckets, one per acreage range. May be empty for regions where no stats have been computed yet.

Array<object>
object
type
required

Acreage bucket label. The list contains overlapping ranges (e.g. both 5 acre-10 acre and 5 acre-100 acre) because the pipeline emits multiple useful slices; pick the bucket closest to the acreage you’re analysing.

string
Allowed values: 0-9.5k sqft 0-0.25 acre 0.15 acre-1 acre 0.2 acre-100 acre 9.5k sqft-1 acre 0.25 acre-1 acre 1 acre-2 acre 1 acre-3 acre 2 acre-5 acre 2 acre-100 acre 3 acre-5 acre 5 acre-10 acre 5 acre-100 acre 5 acre-10000 acre 10 acre-20 acre 20 acre-40 acre 40 acre-60 acre 40 acre-100 acre 40 acre-10000 acre 60 acre-80 acre 80 acre-500 acre 100 acre-10000 acre
data
required

Aggregated metrics for parcels in this acreage bucket. Field names mirror the internal pipeline labels — abbreviations: STR = sell-through rate, DOM = days on market, PPA = price per acre, Gini = Gini coefficient of PPA dispersion (0–100, lower = tighter).

object
Active

Number of currently-active listings in this bucket.

number
nullable
Pending

Number of pending (under-contract) listings.

number
nullable
Sold: 1mo

Closed sales in the trailing 1 month.

number
nullable
Sold: 3mo

Closed sales in the trailing 3 months.

number
nullable
Sold: 6mo

Closed sales in the trailing 6 months.

number
nullable
Sold: 1yr

Closed sales in the trailing 12 months.

number
nullable
Pending STR

Pending sell-through rate (%): pending listings as a fraction of active inventory.

number
nullable
1mo STR

1-month sell-through rate (%): trailing-month sales as a fraction of active inventory.

number
nullable
3mo STR

3-month sell-through rate (%).

number
nullable
6mo STR

6-month sell-through rate (%).

number
nullable
1yr STR

12-month sell-through rate (%).

number
nullable
Avg DOM 1mo

Average days-on-market for sales closed in the trailing month.

number
nullable
Avg DOM 3mo

Average days-on-market over the trailing 3 months.

number
nullable
Avg DOM 6mo

Average days-on-market over the trailing 6 months.

number
nullable
Avg DOM 1yr

Average days-on-market over the trailing 12 months.

number
nullable
Median Price 1mo

Median closed sale price (USD) in the trailing month.

number
nullable
Median Price 3mo

Median closed sale price (USD) over the trailing 3 months.

number
nullable
Median Price 6mo

Median closed sale price (USD) over the trailing 6 months.

number
nullable
Median Price 1yr

Median closed sale price (USD) over the trailing 12 months.

number
nullable
Median Pending Price

Median asking price (USD) across pending listings.

number
nullable
Median Active Price

Median asking price (USD) across active listings.

number
nullable
Median Active Acreage

Median acreage across active listings.

number
nullable
Median Pending Acreage

Median acreage across pending listings.

number
nullable
Median Sold Acreage

Median acreage across closed sales (trailing 12 months).

number
nullable
Median Pending PPA

Median price per acre (USD) across pending listings.

number
nullable
Median Active PPA

Median price per acre (USD) across active listings.

number
nullable
Median Sold PPA

Median price per acre (USD) across closed sales in the trailing 12 months.

number
nullable
Active PPA Min

Minimum price per acre observed across active listings.

number
nullable
Active PPA Max

Maximum price per acre observed across active listings.

number
nullable
Pending PPA Min

Minimum price per acre observed across pending listings.

number
nullable
Pending PPA Max

Maximum price per acre observed across pending listings.

number
nullable
PPA Range 1mo Min

Minimum price per acre in sales closed during the trailing month.

number
nullable
PPA Range 1mo Max

Maximum price per acre in sales closed during the trailing month.

number
nullable
PPA Range 3mo Min

Minimum price per acre in sales closed during the trailing 3 months.

number
nullable
PPA Range 3mo Max

Maximum price per acre in sales closed during the trailing 3 months.

number
nullable
PPA Range 6mo Min

Minimum price per acre in sales closed during the trailing 6 months.

number
nullable
PPA Range 6mo Max

Maximum price per acre in sales closed during the trailing 6 months.

number
nullable
PPA Range 1yr Min

Minimum price per acre in sales closed during the trailing 12 months.

number
nullable
PPA Range 1yr Max

Maximum price per acre in sales closed during the trailing 12 months.

number
nullable
Gini 1mo

Gini coefficient (0–100) of price-per-acre in trailing-month sales. Lower = tighter clustering.

number
nullable
Gini 3mo

Gini coefficient (0–100) over the trailing 3 months.

number
nullable
Gini 6mo

Gini coefficient (0–100) over the trailing 6 months.

number
nullable
Gini 1yr

Gini coefficient (0–100) over the trailing 12 months.

number
nullable
status

Pipeline label, mirroring the in-app market board columns (e.g., ‘Backlog’, ‘Watching’, ‘Active’). Free-form string.

string
created_at
required

ISO-8601 timestamp.

string format: date-time
updated_at
required

ISO-8601 timestamp.

string format: date-time
Example 
{
  "region": {
    "type": "county",
    "stats": [
      {
        "type": "0-9.5k sqft"
      }
    ]
  }
}

400

Section titled “400 ”

Validation error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

401

Section titled “401 ”

Missing or invalid credentials.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

402

Section titled “402 ”

A Pro subscription or higher API tier is required.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

403

Section titled “403 ”

Authenticated but not permitted.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

404

Section titled “404 ”

Resource not found.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

429

Section titled “429 ”

Rate limit exceeded.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}

500

Section titled “500 ”

Internal error.

Media type application/json
object
error
required
object
code
required

Stable machine-readable error code. One of: unauthorized, forbidden, subscription_required, tier_upgrade_required, usage_limit_exceeded, validation_error, not_found, method_not_allowed, rate_limited, internal_error.

string
message
required

Human-readable description of the error.

string
request_id
required

Echoes the request’s X-Request-Id (or a server-issued id). Quote it in support requests.

string
details

Present on validation errors only: maps each rejected field to its list of messages.

object
key
additional properties
any
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "request_id": "example",
    "details": {}
  }
}