Gnowise Unified Property Valuation API

1. Overview

The Unified API uses one endpoint and one API-key authentication pattern. This documentation focuses only on the working Unified API structure. Legacy forecast/off-market client pages and the broken interactive OpenAPI client are intentionally excluded.

2. Endpoint & authentication

Basic cURL

curl -X POST "https://api.gnowise.com" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $GNOWISE_API_KEY" \
  -d @examples/address-only.json

3. Live API tester

Enter your own API key, edit any default payload, and send one of the three supported test profiles. The live tester calls a same-origin Cloudflare Pages Function, which forwards the request server-to-server to the production Unified API. The API key is stored only in this browser if you choose to save it.

4. Three default test inputs

These same editable payloads are included in /examples, in the live tester above, and in the Postman collection. Use them first, verify the response, then change values.

{
  "Address": "299 chaplin cres toronto m5p1b1",
  "AptNum": "",
  "PropertyType": "Detached",
  "IsCondo": false
}

{
  "address": "299 chaplin cres",
  "attributes": {
    "City": "Toronto",
    "PostalCode": "m5p1b1",
    "NumBedrooms": "3",
    "NumDens": "1",
    "NumBathrooms": "2",
    "NumParkingSpaces": "16",
    "Pool": "Inground",
    "BasementType": "Finished",
    "NumKitchens": "2",
    "PropertyType": "Detached",
    "BuildingStyle": "3-Storey",
    "RoomsArea": "1600",
    "LotArea": "3300",
    "Age": "51-99",
    "AirConditioning": "Central Air",
    "Sqft": null
  },
  "aptNum": "",
  "isCondo": false,
  "condition": 3
}

{
  "Address": "299 chaplin cres toronto m5p1b1",
  "AptNum": "",
  "PropertyType": "Detached",
  "IsCondo": false,
  "HistValue": 1500000,
  "HistValueDate": "2021-06-15",
  "HistPropertyType": "Detached"
}

5. Request profiles and field casing

Address-only profile

Enriched attributes profile

Historical/HPI-adjusted profile

Use the address-only profile plus HistValue, HistValueDate, and HistPropertyType. The Address string must include the postal code.

6. Field options

PropertyType: Detached, Semi-Detached, Att/Row/Twnhouse, Duplex, Triplex, Fourplex, Multiplex, Condo Apt, Condo Townhouse, Comm Element Condo.

Condition: 1 Major repairs required · 2 Repairs needed · 3 Well maintained/default · 4 Like new · 5 New.

Units: area fields are square feet; rent is monthly CAD; cap rate and growth rates are decimal proportions.

7. Response schema

The response is returned under Report. Fields can be null or omitted depending on match quality, confidence, coverage, and account entitlements.

{
  "Report": {
    "gnowise_value": 1883000,
    "value_low": 1750000,
    "value_high": 2025000,
    "valuation_source": "A",
    "valuation_confidence": 0.91,
    "gnowise_lease": 4400,
    "lease_low": 4100,
    "lease_high": 4700,
    "lease_confidence": 0.88,
    "gnowise_cap_rate": 0.028,
    "liquidity_score": 0.68,
    "risk_of_decline": 32,
    "one_year_growth_rate": -0.04,
    "two_year_growth_rate": 0.02,
    "price_in_one_year": 1808000,
    "price_in_two_years": 1920000,
    "property_attributes": {},
    "appr_attributes": {},
    "hpi": {
      "M5P_All_median_ci_width": null,
      "M5P_Apartment_median_ci_width": 393562.0,
      "M5P_Detached_median_ci_width": null,
      "M5P_Row_median_ci_width": null,
      "M5P_All_median_price": 690725.0,
      "M5P_Row_median_price": null,
      "M5P_Apartment_median_price": 1216046.0,
      "M5P_Detached_median_price": null
    },
    "rent_comps": [],
    "request_id": "req_01JABCXYZ"
  }
}

8. Optional comparable and neighborhood sections

The Unified API can return entitlement-aware supporting sections such as rent comparables and FSA-level median prices.

9. Confidence, provenance and display rules

A successful API response is not automatically a displayable value. Enterprise clients should apply confidence, source, condo/unit, and commercial policy gates before showing values to users.

• valuation_source = A: property-level AVM pathway.
• valuation_source = HA: historical/HPI-adjusted pathway; label accordingly.
• valuation_source = H: index/fallback pathway; treat as less property-specific.
• Recommended display threshold: valuation_confidence >= 0.85, unless the contract specifies another threshold.

10. Status codes, errors and retries

11. Security checklist

• Do not embed shared enterprise API keys in public repositories, public examples, or permanent front-end code.
• The live tester accepts a user-supplied API key for manual testing and stores it only in browser localStorage when the user clicks Save.
• Production integrations should use server-to-server calls or a signed backend proxy under the client’s control.
• Store keys in a secrets manager and rotate keys regularly.
• Log request_id, status, and internal correlation IDs; avoid logging unnecessary personal information.
• Monitor success rate, confidence distribution, 4xx/5xx rate, latency, and null-field rate.

12. Included files

• openapi.yaml - OpenAPI 3.0.3 contract for the Unified endpoint only.
• examples/address-only.json - minimum detached/address test payload.
• examples/address-and-attributes.json - enriched nested attribute test payload.
• examples/hpi-adjusted.json - historical/HPI-adjusted test payload.
• postman/Gnowise_Unified_API.postman_collection.json - downloadable three-request Postman collection.

Postman import steps

1. Click Download Postman JSON.
2. Open Postman → Import → select the downloaded JSON file.
3. Open the imported collection variables and set gnowise_api_key.
4. Run one of the three default requests, then change the payload values as needed.