Response Format

Every API endpoint — success or error — returns the same three top-level keys:

{
  "data": { ... },
  "meta": { ... },
  "error": null
}

Field	Always present	Description
data	Yes	The endpoint-specific payload. null on error.
meta	Yes	Request metadata: timing, query echo, pagination, credits.
error	Yes	null on success. Contains code and message on failure.

This means every client can always rely on the same three top-level keys, regardless of which endpoint was called.

---

Success response

{
  "data": {
    "location_info": {
      "formatted_address": "123 Ocean Dr, Miami Beach, FL 33139",
      "city": "Miami Beach",
      "state_code": "FL",
      "latitude": 25.77,
      "longitude": -80.13
    },
    "fema_flood_zone": {
      "fld_zone": "AE",
      "sfha": true,
      "static_bfe": 8.0,
      "user_label": "High Risk"
    }
  },
  "meta": {
    "compute_ms": 464,
    "query": {
      "address": "123 Ocean Dr, Miami Beach, FL",
      "latitude": 25.77,
      "longitude": -80.13
    },
    "api_version": "v1.0.0",
    "request_id": "9f39f105...",
    "response_timestamp": "2026-04-15T20:59:46Z",
    "credits": {
      "charged": 10,
      "remaining": 990,
      "pool": "api",
      "breakdown": {
        "base": 10,
        "variable": 0,
        "description": "flood_zone: 10 credits"
      }
    }
  },
  "error": null
}

---

meta fields

Every response includes meta with at minimum:

Field	Present	Description
compute_ms	Always	Server-side processing time in milliseconds
query	Always	Echo of resolved query parameters (lat/lon after geocoding)
api_version	Always	API version string
request_id	Always	Unique request identifier — include in support tickets
response_timestamp	Always	ISO-8601 UTC timestamp
credits	Always	Credit usage for this request (see Credits & Pricing)

Pagination fields (list endpoints only)

Endpoints that return lists (e.g., /v1/crime-data) include additional meta fields:

Field	Description
count	Number of records returned in this page
truncated	true if more records exist beyond this page
next_cursor	Opaque string — pass as cursor param to get the next page. null if last page.

"meta": {
  "compute_ms": 84,
  "query": { "lat": 40.03, "lon": -76.31, "radius_mi": 5.0 },
  "count": 50,
  "truncated": true,
  "next_cursor": "eyJvZmZzZXQiOiA1MH0=",
  "credits": { "charged": 10, "remaining": 960 }
}

query echo

The query object always uses resolved values — latitude and longitude after geocoding, normalized dates. Field names match request parameter names:

"query": {
  "address": "470 Manor St, Lancaster, PA 17603",
  "latitude": 40.0358,
  "longitude": -76.3140,
  "radius_mi": 5.0,
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}

---

credits block

Every response includes credit usage information in meta.credits:

"credits": {
  "charged": 45,
  "remaining": 955,
  "pool": "api",
  "breakdown": {
    "base": 40,
    "variable": 5,
    "description": "Property valuation: 40 base + 5 comps"
  }
}

Field	Description
charged	Total API credits deducted for this request
remaining	Credits left in your monthly pool
pool	Always "api" for REST API calls
breakdown.base	Fixed cost component
breakdown.variable	Variable cost (comps, incidents, keys)
breakdown.description	Human-readable cost explanation

Failed requests (4xx, 5xx) always return "charged": 0.

---

Error response

All errors use the same envelope. data is null, error contains a machine-readable code and human-readable message:

{
  "data": null,
  "meta": {},
  "error": {
    "code": "MISSING_LOCATION",
    "message": "Must provide either address or both latitude and longitude"
  }
}

Error codes

HTTP Status	Code	When
400	MISSING_LOCATION	No address or coordinates provided
400	INVALID_PARAMS	Invalid parameter value (radius, date, etc.)
400	PARAMETER_CAP_EXCEEDED	Parameter exceeds your plan limit
401	MISSING_API_KEY	No X-API-Key header
401	AUTH_FAILED	Invalid API key
402	INSUFFICIENT_CREDITS	Not enough credits for this request
404	NOT_FOUND	Resource not found (e.g., batch job ID)
422	VALIDATION_ERROR	Request body validation failed
429	RATE_LIMITED	Too many requests — check Retry-After header
500	INTERNAL_ERROR	Server error — include request_id in support tickets

Insufficient credits error

The 402 response includes extra context in meta:

{
  "data": null,
  "meta": {
    "credits_remaining": 5,
    "estimated_cost": 40
  },
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This request requires ~40 credits but you have 5 remaining."
  }
}

---

Endpoint-specific data shapes

Each endpoint returns different fields inside data:

Endpoint	data contains
/v1/flood-zone	location_info, fema_flood_zone
/v1/fire-risk	location_info, fire_risk
/v1/storm-surge	location_info, storm_surge
/v1/sinkhole-risk	location_info, sinkhole_risk
/v1/natural-hazards	location_info, natural_hazards
/v1/census-data	location_info, census_geoids, acs_data
/v1/crime-data	crimes, summary, location_info
/v1/socioeconomic-data	location_info, census_geoids, socioeconomic, natural_hazards
/v1/avm/property	address_info, valuation (incl. fsd + confidence), comparables
/v1/avm/rental	address_info, valuation (incl. fsd + confidence), comparables
/v1/avm/multifamily	address_info, valuation (incl. fsd + confidence), comparables
/v1/comprehensive	address_info + requested service data
/v1/avm/batch/* (202)	job_id, status, avm_type, total, status_url
/v1/avm/batch/{job_id}	job_id, status, results, progress_pct

See the API Reference for full field documentation per endpoint.

---

AVM accuracy fields (FSD & confidence)

All AVM endpoints (/v1/avm/property, /v1/avm/rental, /v1/avm/multifamily) include accuracy metrics inside data.valuation:

"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.65,
      "mae": 33637.25,
      "rmse": 53954.33,
      "r2": 0.87,
      "pct_within_5": 26.27,
      "pct_within_10": 47.79,
      "pct_within_15": 62.96,
      "pct_within_20": 72.66
    },
    "per_model": { "xgboost": { ... }, "lightgbm": { ... }, "catboost": { ... } }
  },
  "properties": [ ... ]
}

FSD (Forecast Standard Deviation) is the industry-standard AVM accuracy metric. Lower is better. See the Property Valuation Confidence guide for full field reference.

If the property is in a region without trained models, fsd and confidence are absent from the response.