Property Valuation

The PadStats AVM (Automated Valuation Model) produces instant property valuations using an ensemble of XGBoost, LightGBM, and CatBoost models trained on local sale comparables and property attributes.

Endpoints

Endpoint	Description	API Reference
`POST /v1/avm/property`	Single-family, townhome, condo, and small multifamily (2–4 unit)	Reference
`GET /v1/avm/property`	Same, via query parameters	Reference
`POST /v1/avm/rental`	Rental rate estimates per unit	Reference
`GET /v1/avm/rental`	Same, via query parameters (single unit)	Reference
`POST /v1/avm/multifamily`	Multifamily buildings (2+ units)	Reference
`GET /v1/avm/multifamily`	Same, via query parameters	Reference

Property AVM

Minimal request

The minimum required fields are a location plus bedrooms and bathrooms:

curl -X POST https://api.padstats.io/v1/avm/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": { "address": "456 Oak Ave, Tampa, FL 33602" },
    "property_fields": {
      "bedrooms": 3,
      "bathrooms": 2
    }
  }'

Full request with all fields

{
  "location": { "address": "456 Oak Ave, Tampa, FL 33602" },
  "property_fields": {
    "bedrooms": 3,
    "bathrooms": 2,
    "living_area": 1650,
    "lot_size": 6500,
    "year_built": 2004,
    "property_type": "houses",
    "total_units": 1,
    "has_pool": true,
    "has_basement": false,
    "has_central_air": true,
    "has_porch": true,
    "has_deck": false,
    "has_laundry": true,
    "has_adu": false,
    "fireplace_count": 1,
    "garage_spaces": 2,
    "other_spaces": 0,
    "num_stories": 1,
    "condition": 3.5
  },
  "search_params": {
    "radius_mi": 5.0,
    "lookback_months": 12,
    "num_comps": 5
  }
}

Request fields

Location (location object) — provide one of address or (latitude + longitude):

Field	Type	Description
`address`	string	Full street address
`latitude`	float	Latitude (-90 to 90)
`longitude`	float	Longitude (-180 to 180)

Property fields (property_fields object):

Field	Type	Required	Description
`bedrooms`	int	Yes	Number of bedrooms (0–50)
`bathrooms`	float	Yes	Number of bathrooms (0–50)
`living_area`	int	No	Living area in sqft
`lot_size`	int	No	Lot size in sqft
`year_built`	int	No	Year built (1800–2030)
`property_type`	string	No	`houses`, `townhomes`, `condos`, `small_multifamily`, `multifamily`, `mobile`
`total_units`	int	No	Units in building (1–4). For `small_multifamily`, defaults to 2 if omitted.
`has_pool`	bool	No	Has pool. If omitted, estimated from comparables.
`has_basement`	bool	No	Has basement. If omitted, estimated from comparables.
`has_central_air`	bool	No	Has central air. If omitted, estimated from comparables.
`has_porch`	bool	No	Has patio/porch. If omitted, estimated from comparables.
`has_deck`	bool	No	Has deck/balcony. If omitted, estimated from comparables.
`has_laundry`	bool	No	Has in-unit laundry. If omitted, estimated from comparables.
`has_adu`	bool	No	Has accessory dwelling unit. Defaults to false.
`fireplace_count`	int	No	Number of fireplaces (0–10). Defaults to 0.
`garage_spaces`	int	No	Garage spaces. If omitted, estimated from comparables.
`other_spaces`	int	No	Other parking spaces. If omitted, estimated from comparables.
`num_stories`	int	No	Number of stories (1–5)
`condition`	float	No	Condition (0–5). 1=poor, 2=fair, 3=average, 4=good, 5=excellent

Search parameters (search_params object):

Field	Type	Default	Description
`radius_mi`	float	5.0	Search radius for comparables (0.1–10.0 miles)
`lookback_months`	int	—	Months to look back for sale comparables (1–36)
`num_comps`	int	0	Comparable properties to return (0–20). Set to `0` to skip the comparables query and get the fastest response.
`date`	string	today	As-of date for the valuation (`YYYY-MM-DD`)

Response

All responses use the standard {data, meta, error} envelope. See Response Format for details.

{
  "data": {
    "address_info": {
      "formatted_address": "456 Oak Ave, Tampa, FL 33602",
      "street_address": "456 Oak Ave",
      "city": "Tampa",
      "state": "Florida",
      "state_code": "FL",
      "county": "Hillsborough County",
      "postal_code": "33602",
      "latitude": 27.9478,
      "longitude": -82.4584,
      "geohash8": "dhvrgkqp",
      "census_geoids": {
        "state_fips": "12",
        "county_fips": "057",
        "tract_fips": "010100",
        "block_fips": "1"
      }
    },
    "valuation": {
      "fsd": 0.3806,
      "confidence": {
        "fsd": 0.3806,
        "model_region": "csp",
        "last_trained_at": "2026-03-18T03:01:23+00:00",
        "metrics": {
          "mape": 19.466,
          "mdape": 10.6471,
          "mae": 33637.25,
          "rmse": 53954.33,
          "r2": 0.86963,
          "pct_within_5": 26.27,
          "pct_within_10": 47.79,
          "pct_within_15": 62.96,
          "pct_within_20": 72.66
        },
        "per_model": {
          "xgboost":  { "fsd": 0.3806, "mape": 19.466, "mae": 33637.25, "rmse": 53954.33, "r2": 0.87 },
          "lightgbm": { "fsd": 0.3822, "mape": 20.041, "mae": 37992.69, "rmse": 78678.24, "r2": 0.77 },
          "catboost": { "fsd": 0.3791, "mape": 18.852, "mae": 32104.18, "rmse": 51208.91, "r2": 0.88 }
        }
      },
      "properties": [
        {
          "property_index": 0,
          "status": "complete",
          "point_value": 412000,
          "confidence_interval_95": { "lower": 381000, "upper": 443000 },
          "box_plot_params": {
            "mean": 412000,
            "q1": 390000,
            "q3": 435000,
            "whisker_lower": 381000,
            "whisker_upper": 443000
          },
          "probabilistic_distribution": {
            "mean": 412000,
            "sigma_68_lower": 395000,
            "sigma_68_upper": 429000,
            "ci_95_lower": 381000,
            "ci_95_upper": 443000,
            "percentiles": { "p5": 383000, "p25": 397000, "p50": 412000, "p75": 427000, "p95": 441000 }
          }
        }
      ],
      "metadata": { "total_properties_processed": 1 }
    },
    "comparables": {
      "properties": [ ... ],
      "statistics": { ... }
    }
  },
  "meta": {
    "compute_ms": 312,
    "query": { ... },
    "credits": { "charged": 45, "remaining": 955, "pool": "api", "breakdown": { ... } }
  },
  "error": null
}

Confidence & Accuracy

Every AVM response includes accuracy metrics for the model that produced the valuation, sourced from the latest training run for the property's region.

`valuation.fsd` — Forecast Standard Deviation

The FSD is the industry-standard measure of AVM accuracy. It expresses the model's prediction error as a fraction of the predicted value (e.g., 0.10 means typical error is ±10% of the predicted value).

Lower is better. A lower FSD means the model is more accurate for that region.
Computed across the ensemble (xgboost, lightgbm, catboost) — averaged.
Sourced from holdout validation in the most recent training run (no inference-time computation).

`valuation.confidence` block

Field	Description
`fsd`	Same FSD value (duplicated for convenience)
`model_region`	Region code that produced the prediction (e.g., `csp`, `sfl`)
`last_trained_at`	ISO-8601 timestamp of the most recent training run
`metrics.mape`	Mean Absolute Percentage Error (%) — average error as a percentage
`metrics.mdape`	Median APE (%) — robust to outliers
`metrics.mae`	Mean Absolute Error in dollars
`metrics.rmse`	Root Mean Squared Error in dollars
`metrics.r2`	R² coefficient (0-1, higher = better fit)
`metrics.pct_within_5`	% of holdout predictions within 5% of actual sale price
`metrics.pct_within_10`	% of holdout predictions within 10% of actual sale price
`metrics.pct_within_15`	% of holdout predictions within 15% of actual sale price
`metrics.pct_within_20`	% of holdout predictions within 20% of actual sale price
`per_model`	Per-model breakdown of all the above (xgboost, lightgbm, catboost)

Region availability

If the property is in a region where models haven't been trained yet, fsd and confidence will be absent from the response. The valuation itself will still be returned.

Batch processing

Submit up to 500 properties for async valuation. See the Property Batch AVM reference for the full schema.

curl -X POST https://api.padstats.io/v1/avm/batch/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      {
        "property_id": "prop-001",
        "location": { "address": "456 Oak Ave, Tampa, FL 33602" },
        "property_fields": { "bedrooms": 3, "bathrooms": 2 }
      },
      {
        "property_id": "prop-002",
        "location": { "address": "123 Main St, Austin, TX 78701" },
        "property_fields": { "bedrooms": 4, "bathrooms": 3, "living_area": 2200 }
      }
    ],
    "notify_url": "https://your-server.com/webhook"
  }'

Returns HTTP 202 with a job_id. Poll with GET /v1/avm/batch/{job_id}.

`property_type` values

Value	Description
`houses`	Single-family detached homes
`townhomes`	Attached townhouses
`condos`	Condominium units
`small_multifamily`	2–4 unit properties
`multifamily`	5+ unit apartment buildings
`mobile`	Mobile/manufactured homes

tip

When property_type is small_multifamily and total_units is omitted or set to 1, the API defaults total_units to 2. Always pass the actual unit count when you have it.

Rental AVM

Returns estimated monthly rent for one or more units in a property. See the Rental AVM POST reference for the full schema.

{
  "location": { "address": "789 Elm St, Nashville, TN 37201" },
  "property_fields": {
    "property_type": "small_multifamily",
    "total_units": 4,
    "has_central_air": true,
    "has_laundry": true,
    "has_parking": true,
    "units": [
      { "bedrooms": 2, "bathrooms": 1, "size": 900 },
      { "bedrooms": 1, "bathrooms": 1, "size": 650 }
    ]
  },
  "search_params": { "radius_mi": 5.0, "num_comps": 5 }
}

Rental unit fields

Each entry in the units array accepts:

Field	Type	Required	Description
`bedrooms`	int	Yes	Bedrooms (0–10)
`bathrooms`	float	Yes	Bathrooms (0–10)
`size`	int	No	Unit size in sqft
`is_furnished`	bool	No	Is furnished. Defaults to false if omitted.

Rental property fields

Field	Type	Description
`property_type`	string	`houses`, `townhomes`, `condos`, `small_multifamily`, `multifamily`
`total_units`	int	Total units in building (not units being valued)
`condition`	float	Condition (0–5)
`has_central_air`	bool	Has central air
`has_laundry`	bool	Has in-unit laundry
`has_parking`	bool	Has off-street parking

GET request (single unit)

For a single unit, use query parameters — no units array needed:

curl "https://api.padstats.io/v1/avm/rental?address=789+Elm+St,+Nashville,+TN+37201&bedrooms=2&bathrooms=1&size=900&property_type=houses" \
  -H "X-API-Key: YOUR_API_KEY"

Batch processing

Submit up to 500 rental properties for async valuation. See the Rental Batch AVM reference.

curl -X POST https://api.padstats.io/v1/avm/batch/rental \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      {
        "property_id": "rental-001",
        "location": { "address": "789 Elm St, Nashville, TN 37201" },
        "property_fields": {
          "units": [{ "bedrooms": 2, "bathrooms": 1 }],
          "property_type": "houses"
        }
      }
    ]
  }'

Multifamily AVM

For buildings with 2 or more units. Returns both a whole-building valuation and a price-per-unit breakdown with full probabilistic distributions. See the Multifamily AVM POST reference for the full schema.

{
  "location": { "address": "100 Harbor Blvd, Miami, FL 33132" },
  "property_fields": {
    "bedrooms": 24,
    "bathrooms": 24,
    "total_units": 12,
    "living_area": 14400,
    "year_built": 1985,
    "num_stories": 3,
    "condition_rating": 3.5
  },
  "search_params": { "radius_mi": 5.0, "num_comps": 5 }
}

Multifamily-specific fields

Field	Type	Required	Description
`bedrooms`	int	Yes	Total bedrooms across all units (0–5000)
`bathrooms`	float	Yes	Total bathrooms across all units (0–5000)
`total_units`	int	Yes	Total units in building (2–1000)
`living_area`	int	No	Total living area in sqft
`year_built`	int	No	Year built
`num_stories`	float	No	Number of stories
`condition_rating`	float	No	Property condition (0–5). Also accepts `condition` or `condition_score` as aliases

note

total_units is required and must be ≥ 2. Credit pricing is 60 base (2–4 units) or 80 base (5+ units) + 1 per comparable.

Multifamily response

The response includes both total property value and price-per-unit estimates:

{
  "valuation": {
    "total_units": 12,
    "point_value": 4800000,
    "estimated_value": 4800000,
    "estimated_value_low": 3600000,
    "estimated_value_high": 6200000,
    "confidence_interval_95": { "lower": 3400000, "upper": 6500000 },
    "confidence_interval_90": { "lower": 3600000, "upper": 6200000 },
    "price_per_unit": 400000,
    "price_per_unit_low": 300000,
    "price_per_unit_high": 517000,
    "probabilistic_distribution": {
      "mean": 4800000,
      "percentiles": { "p5": 3600000, "p10": 3800000, "p25": 4200000, "p50": 4800000, "p75": 5400000, "p90": 5900000, "p95": 6200000 }
    },
    "price_per_unit_distribution": {
      "point_value": 400000,
      "probabilistic_distribution": {
        "mean": 400000,
        "percentiles": { "p5": 300000, "p25": 350000, "p50": 400000, "p75": 450000, "p95": 517000 }
      }
    }
  }
}

Field	Description
`point_value` / `estimated_value`	Median total property value
`estimated_value_low` / `estimated_value_high`	5th and 95th percentile bounds
`confidence_interval_95`	2.5th–97.5th percentile range
`confidence_interval_90`	5th–95th percentile range
`price_per_unit`	Median per-unit value
`price_per_unit_low` / `price_per_unit_high`	Per-unit 5th–95th percentile
`price_per_unit_distribution`	Full probabilistic distribution for per-unit value

Batch processing

Submit up to 500 multifamily properties for async valuation. See the Multifamily Batch AVM reference.

Polling batch jobs

All batch endpoints return HTTP 202 with a job_id. Poll for results with GET /v1/avm/batch/{job_id}:

curl "https://api.padstats.io/v1/avm/batch/abc123-def456" \
  -H "X-API-Key: YOUR_API_KEY"

Job status progresses: queued → processing → complete (or failed). For details on webhook notifications, retry strategies, and performance tips, see the Batch Processing guide.

Performance tips

num_comps: 0 skips the comparables database query — use this for batch workloads where you only need the valuation, not comparable listings.
For single properties, typical response times are 1–3 seconds.
For large volumes, use the batch endpoints above.

Endpoints​

Property AVM​

Minimal request​

Full request with all fields​

Request fields​

Response​

Confidence & Accuracy​

valuation.fsd — Forecast Standard Deviation​

valuation.confidence block​

Batch processing​

property_type values​

Rental AVM​

Rental unit fields​

Rental property fields​

GET request (single unit)​

Batch processing​

Multifamily AVM​

Multifamily-specific fields​

Multifamily response​

Batch processing​

Polling batch jobs​

Performance tips​

Endpoints

Property AVM

Minimal request

Full request with all fields

Request fields

Response

Confidence & Accuracy

`valuation.fsd` — Forecast Standard Deviation

`valuation.confidence` block

Batch processing

`property_type` values

Rental AVM

Rental unit fields

Rental property fields

GET request (single unit)

Batch processing

Multifamily AVM

Multifamily-specific fields

Multifamily response

Batch processing

Polling batch jobs

Performance tips