{"openapi":"3.0.0","paths":{"/health-check":{"get":{"operationId":"HealthCheckController_check","summary":"Check API health","description":"Returns the current status of the API. Use this endpoint to verify that the API is up and running.","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"}}}}}}}}},"tags":["health-check"]}},"/health-check/authenticated":{"get":{"operationId":"HealthCheckController_authenticatedHealthCheck","summary":"Check authenticated API health","description":"Returns the current status of the API with authentication check. Use this endpoint to verify that your API key is valid.","parameters":[],"responses":{"200":{"description":"API is up and running, and authentication is working","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"authenticated":{"type":"boolean","example":true},"timestamp":{"type":"string","example":"2023-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["health-check"],"security":[{"api-key":[]}]}},"/properties/search":{"get":{"operationId":"sfr_search_properties","summary":"Search properties","description":"Search for properties using location, distress, and property filters. Premium subscribers can filter by pre-foreclosure and vacancy status. At least one location filter (state, city, county, zip_codes, or msa) is required.","parameters":[{"name":"state","required":false,"in":"query","description":"State abbreviation (e.g., \"FL\")","example":"FL","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Miami","schema":{"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name","schema":{"type":"string"}},{"name":"zip_codes","required":false,"in":"query","description":"Comma-separated zip codes","example":"33101,33102","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","schema":{"type":"string"}},{"name":"pre_foreclosure","required":false,"in":"query","description":"Filter for pre-foreclosure properties","example":true,"schema":{"type":"boolean"}},{"name":"pre_foreclosure_date_min","required":false,"in":"query","description":"Earliest pre-foreclosure recording date (YYYYMMDD)","example":"20240101","schema":{"type":"string"}},{"name":"pre_foreclosure_date_max","required":false,"in":"query","description":"Latest pre-foreclosure recording date (YYYYMMDD)","example":"20241231","schema":{"type":"string"}},{"name":"vacant","required":false,"in":"query","description":"Filter for vacant properties","example":true,"schema":{"type":"boolean"}},{"name":"zombie_foreclosure","required":false,"in":"query","description":"Filter for zombie foreclosure properties","example":true,"schema":{"type":"boolean"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"year_built_min","required":false,"in":"query","description":"Minimum year built","example":1990,"schema":{"type":"number"}},{"name":"year_built_max","required":false,"in":"query","description":"Maximum year built","example":2024,"schema":{"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter","schema":{"type":"string"}},{"name":"owner_name","required":false,"in":"query","description":"Search by property owner name (partial match)","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default 1)","example":1,"schema":{"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default 20, max 100)","example":20,"schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","example":"recording_date","schema":{"enum":["recording_date","assessed_value","year_built"],"type":"string"}}],"responses":{"200":{"description":"Search results with paginated properties","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"object","properties":{"formatted_street_address":{"type":"string","example":"123 Main St"},"street_number":{"type":"string","nullable":true,"example":"123"},"street_suffix":{"type":"string","nullable":true,"example":"St"},"street_pre_direction":{"type":"string","nullable":true},"street_name":{"type":"string","nullable":true,"example":"Main"},"street_post_direction":{"type":"string","nullable":true},"unit_type":{"type":"string","nullable":true},"unit_number":{"type":"string","nullable":true},"city":{"type":"string","example":"Los Angeles"},"state":{"type":"string","example":"CA"},"zip_code":{"type":"string","example":"90001"},"zip_plus_four_code":{"type":"string","nullable":true},"carrier_code":{"type":"string","nullable":true},"latitude":{"type":"number","example":34.052235},"longitude":{"type":"number","example":-118.243683},"geocoding_accuracy":{"type":"string","nullable":true},"census_tract":{"type":"string","nullable":true},"census_block":{"type":"string","nullable":true}}},"assessed_year":{"type":"number","nullable":true,"example":2023},"assessments":{"type":"object","properties":{"land_value":{"type":"number","nullable":true,"example":300000},"improvement_value":{"type":"number","nullable":true,"example":450000},"assessed_value":{"type":"number","nullable":true,"example":700000},"market_value":{"type":"number","nullable":true,"example":750000}}},"exemptions":{"type":"object","properties":{"homeowner":{"type":"boolean","nullable":true},"veteran":{"type":"boolean","nullable":true},"disabled":{"type":"boolean","nullable":true},"widow":{"type":"boolean","nullable":true},"senior":{"type":"boolean","nullable":true},"school":{"type":"boolean","nullable":true},"religious":{"type":"boolean","nullable":true},"welfare":{"type":"boolean","nullable":true},"public":{"type":"boolean","nullable":true},"cemetery":{"type":"boolean","nullable":true},"hospital":{"type":"boolean","nullable":true},"library":{"type":"boolean","nullable":true}}},"market_year":{"type":"number","nullable":true},"owner":{"type":"object","description":"Premium only","properties":{"owner_occupied":{"type":"boolean","nullable":true},"name":{"type":"string","nullable":true,"example":"Sample Owner LLC"},"second_name":{"type":"string","nullable":true},"formatted_street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip_code":{"type":"string","nullable":true},"zip_plus_four_code":{"type":"string","nullable":true},"corporate_owner":{"type":"boolean","nullable":true},"care_of_name":{"type":"string","nullable":true}}},"parcel":{"type":"object","properties":{"apn_original":{"type":"string","nullable":true},"fips_code":{"type":"string","nullable":true},"frontage_ft":{"type":"number","nullable":true},"depth_ft":{"type":"number","nullable":true},"area_acres":{"type":"number","nullable":true},"area_sq_ft":{"type":"number","nullable":true,"example":5500},"zoning":{"type":"string","nullable":true,"example":"R1"},"county_land_use_code":{"type":"string","nullable":true},"lot_number":{"type":"string","nullable":true},"subdivision":{"type":"string","nullable":true},"section_township_range":{"type":"string","nullable":true},"legal_description":{"type":"string","nullable":true},"state_land_use_code":{"type":"string","nullable":true},"building_count":{"type":"number","nullable":true}}},"school_tax_district_1":{"type":"string","nullable":true},"school_tax_district_2":{"type":"string","nullable":true},"school_tax_district_3":{"type":"string","nullable":true},"school_district_name":{"type":"string","nullable":true},"structure":{"type":"object","properties":{"total_area_sq_ft":{"type":"number","nullable":true,"example":1800},"year_built":{"type":"number","nullable":true,"example":1985},"effective_year_built":{"type":"number","nullable":true},"beds_count":{"type":"number","nullable":true,"example":3},"rooms_count":{"type":"number","nullable":true},"baths":{"type":"number","nullable":true,"example":2},"partial_baths_count":{"type":"number","nullable":true},"basement_type":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true},"construction_type":{"type":"string","nullable":true},"exterior_wall_type":{"type":"string","nullable":true},"fireplaces":{"type":"string","nullable":true},"heating_type":{"type":"string","nullable":true},"heating_fuel_type":{"type":"string","nullable":true},"parking_spaces_count":{"type":"number","nullable":true},"pool_type":{"type":"string","nullable":true},"quality":{"type":"string","nullable":true},"roof_material_type":{"type":"string","nullable":true},"roof_style_type":{"type":"string","nullable":true},"sewer_type":{"type":"string","nullable":true},"stories":{"type":"string","nullable":true},"units_count":{"type":"number","nullable":true},"water_type":{"type":"string","nullable":true},"living_area_sqft":{"type":"number","nullable":true,"example":1650},"ac_description":{"type":"string","nullable":true},"garage_description":{"type":"string","nullable":true},"building_class_description":{"type":"string","nullable":true},"sqft_description":{"type":"string","nullable":true}}},"tax_amount":{"type":"number","nullable":true,"example":8500},"tax_delinquent_year":{"type":"number","nullable":true},"tax_rate_code_area":{"type":"string","nullable":true},"tax_year":{"type":"number","nullable":true,"example":2023},"valuation":{"type":"object","properties":{"value":{"type":"number","nullable":true,"example":780000},"high":{"type":"number","nullable":true,"example":820000},"low":{"type":"number","nullable":true,"example":740000},"forecast_standard_deviation":{"type":"number","nullable":true},"date":{"type":"string","nullable":true,"example":"2023-06-01"}}},"property_class_description":{"type":"string","nullable":true},"vacant":{"type":"boolean","nullable":true,"description":"Premium only"},"pre_foreclosure":{"type":"object","description":"Premium only","properties":{"flag":{"type":"boolean","nullable":true},"ind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"doc_type":{"type":"string","nullable":true},"recording_date":{"type":"string","nullable":true}}},"last_sale":{"type":"object","properties":{"date":{"type":"string","nullable":true,"example":"2022-05-15"},"price":{"type":"number","nullable":true,"example":750000},"document_type":{"type":"string","nullable":true},"mtg_amount":{"type":"number","nullable":true,"example":600000},"mtg_type":{"type":"string","nullable":true},"lender":{"type":"string","nullable":true,"example":"Wells Fargo"},"mtg_interest_rate":{"type":"number","nullable":true},"mtg_term_months":{"type":"number","nullable":true},"mtg_1_est_remaining":{"type":"number","nullable":true,"example":320000},"mtg_2_est_remaining":{"type":"number","nullable":true},"mtg_3_est_remaining":{"type":"number","nullable":true},"mtg_4_est_remaining":{"type":"number","nullable":true}}},"current_sale":{"type":"object","properties":{"doc_num":{"type":"string","nullable":true},"buyer_1":{"type":"string","nullable":true},"buyer_2":{"type":"string","nullable":true},"seller_1":{"type":"string","nullable":true},"seller_2":{"type":"string","nullable":true}}},"msa":{"type":"string","nullable":true,"example":"Los Angeles-Long Beach-Anaheim"},"county":{"type":"string","nullable":true,"example":"Los Angeles"},"property_type":{"type":"string","nullable":true,"example":"Single Family Residential"},"hoa":{"type":"number","nullable":true,"description":"HOA fee amount for the period indicated by hoa_frequency. Uses the primary HOA fee when available; falls back to the secondary HOA fee amount."},"hoa_frequency":{"type":"string","nullable":true,"enum":["annual","monthly","quarterly","semi_annual"],"description":"Billing frequency for the returned HOA fee amount. Values are normalized from First American HOA fee frequency codes."},"owner_type":{"type":"string","nullable":true,"description":"Premium only"},"purchase_method":{"type":"string","nullable":true},"listing_status":{"type":"string","nullable":true},"months_owned":{"type":"number","nullable":true}}}},"total":{"type":"number","example":145},"page":{"type":"number","example":1},"page_size":{"type":"number","example":20}}}}}},"400":{"description":"Invalid request - missing location filter or invalid parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"403":{"description":"Distress filters require a Premium or Unlimited subscription"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/by-address":{"get":{"operationId":"sfr_get_property","summary":"Get property by address","description":"Returns comprehensive property information based on a full address. Premium subscribers receive additional data fields.","parameters":[{"name":"address","required":true,"in":"query","description":"Full property address (e.g., \"123 Main St, Los Angeles, CA 90001\")","example":"123 Main St, Los Angeles, CA 90001","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"Property information including details, valuation, features, and transaction history","content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"object","properties":{"formatted_street_address":{"type":"string","example":"123 Main St"},"street_number":{"type":"string","nullable":true,"example":"123"},"street_suffix":{"type":"string","nullable":true,"example":"St"},"street_pre_direction":{"type":"string","nullable":true},"street_name":{"type":"string","nullable":true,"example":"Main"},"street_post_direction":{"type":"string","nullable":true},"unit_type":{"type":"string","nullable":true},"unit_number":{"type":"string","nullable":true},"city":{"type":"string","example":"Los Angeles"},"state":{"type":"string","example":"CA"},"zip_code":{"type":"string","example":"90001"},"zip_plus_four_code":{"type":"string","nullable":true},"carrier_code":{"type":"string","nullable":true},"latitude":{"type":"number","example":34.052235},"longitude":{"type":"number","example":-118.243683},"geocoding_accuracy":{"type":"string","nullable":true},"census_tract":{"type":"string","nullable":true},"census_block":{"type":"string","nullable":true}}},"assessed_year":{"type":"number","nullable":true,"example":2023},"assessments":{"type":"object","properties":{"land_value":{"type":"number","nullable":true,"example":300000},"improvement_value":{"type":"number","nullable":true,"example":450000},"assessed_value":{"type":"number","nullable":true,"example":700000},"market_value":{"type":"number","nullable":true,"example":750000}}},"exemptions":{"type":"object","properties":{"homeowner":{"type":"boolean","nullable":true},"veteran":{"type":"boolean","nullable":true},"disabled":{"type":"boolean","nullable":true},"widow":{"type":"boolean","nullable":true},"senior":{"type":"boolean","nullable":true},"school":{"type":"boolean","nullable":true},"religious":{"type":"boolean","nullable":true},"welfare":{"type":"boolean","nullable":true},"public":{"type":"boolean","nullable":true},"cemetery":{"type":"boolean","nullable":true},"hospital":{"type":"boolean","nullable":true},"library":{"type":"boolean","nullable":true}}},"market_year":{"type":"number","nullable":true},"owner":{"type":"object","description":"Premium only","properties":{"owner_occupied":{"type":"boolean","nullable":true},"name":{"type":"string","nullable":true,"example":"Sample Owner LLC"},"second_name":{"type":"string","nullable":true},"formatted_street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip_code":{"type":"string","nullable":true},"zip_plus_four_code":{"type":"string","nullable":true},"corporate_owner":{"type":"boolean","nullable":true},"care_of_name":{"type":"string","nullable":true}}},"parcel":{"type":"object","properties":{"apn_original":{"type":"string","nullable":true},"fips_code":{"type":"string","nullable":true},"frontage_ft":{"type":"number","nullable":true},"depth_ft":{"type":"number","nullable":true},"area_acres":{"type":"number","nullable":true},"area_sq_ft":{"type":"number","nullable":true,"example":5500},"zoning":{"type":"string","nullable":true,"example":"R1"},"county_land_use_code":{"type":"string","nullable":true},"lot_number":{"type":"string","nullable":true},"subdivision":{"type":"string","nullable":true},"section_township_range":{"type":"string","nullable":true},"legal_description":{"type":"string","nullable":true},"state_land_use_code":{"type":"string","nullable":true},"building_count":{"type":"number","nullable":true}}},"school_tax_district_1":{"type":"string","nullable":true},"school_tax_district_2":{"type":"string","nullable":true},"school_tax_district_3":{"type":"string","nullable":true},"school_district_name":{"type":"string","nullable":true},"structure":{"type":"object","properties":{"total_area_sq_ft":{"type":"number","nullable":true,"example":1800},"year_built":{"type":"number","nullable":true,"example":1985},"effective_year_built":{"type":"number","nullable":true},"beds_count":{"type":"number","nullable":true,"example":3},"rooms_count":{"type":"number","nullable":true},"baths":{"type":"number","nullable":true,"example":2},"partial_baths_count":{"type":"number","nullable":true},"basement_type":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true},"construction_type":{"type":"string","nullable":true},"exterior_wall_type":{"type":"string","nullable":true},"fireplaces":{"type":"string","nullable":true},"heating_type":{"type":"string","nullable":true},"heating_fuel_type":{"type":"string","nullable":true},"parking_spaces_count":{"type":"number","nullable":true},"pool_type":{"type":"string","nullable":true},"quality":{"type":"string","nullable":true},"roof_material_type":{"type":"string","nullable":true},"roof_style_type":{"type":"string","nullable":true},"sewer_type":{"type":"string","nullable":true},"stories":{"type":"string","nullable":true},"units_count":{"type":"number","nullable":true},"water_type":{"type":"string","nullable":true},"living_area_sqft":{"type":"number","nullable":true,"example":1650},"ac_description":{"type":"string","nullable":true},"garage_description":{"type":"string","nullable":true},"building_class_description":{"type":"string","nullable":true},"sqft_description":{"type":"string","nullable":true}}},"tax_amount":{"type":"number","nullable":true,"example":8500},"tax_delinquent_year":{"type":"number","nullable":true},"tax_rate_code_area":{"type":"string","nullable":true},"tax_year":{"type":"number","nullable":true,"example":2023},"valuation":{"type":"object","properties":{"value":{"type":"number","nullable":true,"example":780000},"high":{"type":"number","nullable":true,"example":820000},"low":{"type":"number","nullable":true,"example":740000},"forecast_standard_deviation":{"type":"number","nullable":true},"date":{"type":"string","nullable":true,"example":"2023-06-01"}}},"property_class_description":{"type":"string","nullable":true},"vacant":{"type":"boolean","nullable":true,"description":"Premium only"},"pre_foreclosure":{"type":"object","description":"Premium only","properties":{"flag":{"type":"boolean","nullable":true},"ind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"doc_type":{"type":"string","nullable":true},"recording_date":{"type":"string","nullable":true}}},"last_sale":{"type":"object","properties":{"date":{"type":"string","nullable":true,"example":"2022-05-15"},"price":{"type":"number","nullable":true,"example":750000},"document_type":{"type":"string","nullable":true},"mtg_amount":{"type":"number","nullable":true,"example":600000},"mtg_type":{"type":"string","nullable":true},"lender":{"type":"string","nullable":true,"example":"Wells Fargo"},"mtg_interest_rate":{"type":"number","nullable":true},"mtg_term_months":{"type":"number","nullable":true},"mtg_1_est_remaining":{"type":"number","nullable":true,"example":320000},"mtg_2_est_remaining":{"type":"number","nullable":true},"mtg_3_est_remaining":{"type":"number","nullable":true},"mtg_4_est_remaining":{"type":"number","nullable":true}}},"current_sale":{"type":"object","properties":{"doc_num":{"type":"string","nullable":true},"buyer_1":{"type":"string","nullable":true},"buyer_2":{"type":"string","nullable":true},"seller_1":{"type":"string","nullable":true},"seller_2":{"type":"string","nullable":true}}},"msa":{"type":"string","nullable":true,"example":"Los Angeles-Long Beach-Anaheim"},"county":{"type":"string","nullable":true,"example":"Los Angeles"},"property_type":{"type":"string","nullable":true,"example":"Single Family Residential"},"hoa":{"type":"number","nullable":true,"description":"HOA fee amount for the period indicated by hoa_frequency. Uses the primary HOA fee when available; falls back to the secondary HOA fee amount."},"hoa_frequency":{"type":"string","nullable":true,"enum":["annual","monthly","quarterly","semi_annual"],"description":"Billing frequency for the returned HOA fee amount. Values are normalized from First American HOA fee frequency codes."},"owner_type":{"type":"string","nullable":true,"description":"Premium only"},"purchase_method":{"type":"string","nullable":true},"listing_status":{"type":"string","nullable":true},"months_owned":{"type":"number","nullable":true}}}}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]},"post":{"operationId":"PropertiesController_getPropertyByAddress","summary":"[DEPRECATED] Get property by address","description":"DEPRECATED: Use GET /properties/by-address instead. Returns comprehensive property information based on a full address. Premium subscribers receive additional data fields.","deprecated":true,"parameters":[],"requestBody":{"required":true,"description":"Property address query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPropertyDto"},"examples":{"complete":{"summary":"Complete address example","description":"A complete address with street, city, state, and zip","value":{"address":"123 Main St, Los Angeles, CA 90001"}},"minimal":{"summary":"Minimal address example","description":"A minimal address with just street and zip","value":{"address":"123 Main St, 90001"}}}}}},"responses":{"200":{"description":"Property information including details, valuation, features, and transaction history","content":{"application/json":{"example":{"address":"123 Main St, Los Angeles, CA 90001","propertyId":12345678,"latitude":34.052235,"longitude":-118.243683,"yearBuilt":1985,"bedrooms":3,"bathrooms":2,"buildingSqft":1800,"lotSqft":5500,"lastSaleDate":"2022-05-15","lastSalePrice":750000,"taxAssessedValue":700000,"estimatedValue":780000,"propertyType":"Single Family Residential","features":{"pool":true,"garage":true,"centralAC":true},"ownerInfo":{"name":"Sample Owner LLC","ownerType":"corporate","corporateOwned":true,"absenteeOwner":false},"recentTransactions":[{"date":"2022-05-15","price":750000,"seller":"Previous Owner","buyer":"Sample Owner LLC","transactionType":"sale"}]}}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/by-mailing-address":{"get":{"operationId":"sfr_get_properties_by_mailing_address","summary":"Get properties by shared mailing address","description":"Returns every property whose mailing address matches the matched property's owner-of-record mailing tuple — typically the rest of the same owner's portfolio at that mailing address. Requires a full address (street number, street, city, and zip) so the matched property is unambiguous. Premium subscribers receive additional data fields. Capped at 500 results.","parameters":[{"name":"address","required":true,"in":"query","description":"Full property address (e.g., \"123 Main St, Los Angeles, CA 90001\")","example":"123 Main St, Los Angeles, CA 90001","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"List of properties sharing the same mailing address","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"object","properties":{"formatted_street_address":{"type":"string","example":"123 Main St"},"street_number":{"type":"string","nullable":true,"example":"123"},"street_suffix":{"type":"string","nullable":true,"example":"St"},"street_pre_direction":{"type":"string","nullable":true},"street_name":{"type":"string","nullable":true,"example":"Main"},"street_post_direction":{"type":"string","nullable":true},"unit_type":{"type":"string","nullable":true},"unit_number":{"type":"string","nullable":true},"city":{"type":"string","example":"Los Angeles"},"state":{"type":"string","example":"CA"},"zip_code":{"type":"string","example":"90001"},"zip_plus_four_code":{"type":"string","nullable":true},"carrier_code":{"type":"string","nullable":true},"latitude":{"type":"number","example":34.052235},"longitude":{"type":"number","example":-118.243683},"geocoding_accuracy":{"type":"string","nullable":true},"census_tract":{"type":"string","nullable":true},"census_block":{"type":"string","nullable":true}}},"assessed_year":{"type":"number","nullable":true,"example":2023},"assessments":{"type":"object","properties":{"land_value":{"type":"number","nullable":true,"example":300000},"improvement_value":{"type":"number","nullable":true,"example":450000},"assessed_value":{"type":"number","nullable":true,"example":700000},"market_value":{"type":"number","nullable":true,"example":750000}}},"exemptions":{"type":"object","properties":{"homeowner":{"type":"boolean","nullable":true},"veteran":{"type":"boolean","nullable":true},"disabled":{"type":"boolean","nullable":true},"widow":{"type":"boolean","nullable":true},"senior":{"type":"boolean","nullable":true},"school":{"type":"boolean","nullable":true},"religious":{"type":"boolean","nullable":true},"welfare":{"type":"boolean","nullable":true},"public":{"type":"boolean","nullable":true},"cemetery":{"type":"boolean","nullable":true},"hospital":{"type":"boolean","nullable":true},"library":{"type":"boolean","nullable":true}}},"market_year":{"type":"number","nullable":true},"owner":{"type":"object","description":"Premium only","properties":{"owner_occupied":{"type":"boolean","nullable":true},"name":{"type":"string","nullable":true,"example":"Sample Owner LLC"},"second_name":{"type":"string","nullable":true},"formatted_street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip_code":{"type":"string","nullable":true},"zip_plus_four_code":{"type":"string","nullable":true},"corporate_owner":{"type":"boolean","nullable":true},"care_of_name":{"type":"string","nullable":true}}},"parcel":{"type":"object","properties":{"apn_original":{"type":"string","nullable":true},"fips_code":{"type":"string","nullable":true},"frontage_ft":{"type":"number","nullable":true},"depth_ft":{"type":"number","nullable":true},"area_acres":{"type":"number","nullable":true},"area_sq_ft":{"type":"number","nullable":true,"example":5500},"zoning":{"type":"string","nullable":true,"example":"R1"},"county_land_use_code":{"type":"string","nullable":true},"lot_number":{"type":"string","nullable":true},"subdivision":{"type":"string","nullable":true},"section_township_range":{"type":"string","nullable":true},"legal_description":{"type":"string","nullable":true},"state_land_use_code":{"type":"string","nullable":true},"building_count":{"type":"number","nullable":true}}},"school_tax_district_1":{"type":"string","nullable":true},"school_tax_district_2":{"type":"string","nullable":true},"school_tax_district_3":{"type":"string","nullable":true},"school_district_name":{"type":"string","nullable":true},"structure":{"type":"object","properties":{"total_area_sq_ft":{"type":"number","nullable":true,"example":1800},"year_built":{"type":"number","nullable":true,"example":1985},"effective_year_built":{"type":"number","nullable":true},"beds_count":{"type":"number","nullable":true,"example":3},"rooms_count":{"type":"number","nullable":true},"baths":{"type":"number","nullable":true,"example":2},"partial_baths_count":{"type":"number","nullable":true},"basement_type":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true},"construction_type":{"type":"string","nullable":true},"exterior_wall_type":{"type":"string","nullable":true},"fireplaces":{"type":"string","nullable":true},"heating_type":{"type":"string","nullable":true},"heating_fuel_type":{"type":"string","nullable":true},"parking_spaces_count":{"type":"number","nullable":true},"pool_type":{"type":"string","nullable":true},"quality":{"type":"string","nullable":true},"roof_material_type":{"type":"string","nullable":true},"roof_style_type":{"type":"string","nullable":true},"sewer_type":{"type":"string","nullable":true},"stories":{"type":"string","nullable":true},"units_count":{"type":"number","nullable":true},"water_type":{"type":"string","nullable":true},"living_area_sqft":{"type":"number","nullable":true,"example":1650},"ac_description":{"type":"string","nullable":true},"garage_description":{"type":"string","nullable":true},"building_class_description":{"type":"string","nullable":true},"sqft_description":{"type":"string","nullable":true}}},"tax_amount":{"type":"number","nullable":true,"example":8500},"tax_delinquent_year":{"type":"number","nullable":true},"tax_rate_code_area":{"type":"string","nullable":true},"tax_year":{"type":"number","nullable":true,"example":2023},"valuation":{"type":"object","properties":{"value":{"type":"number","nullable":true,"example":780000},"high":{"type":"number","nullable":true,"example":820000},"low":{"type":"number","nullable":true,"example":740000},"forecast_standard_deviation":{"type":"number","nullable":true},"date":{"type":"string","nullable":true,"example":"2023-06-01"}}},"property_class_description":{"type":"string","nullable":true},"vacant":{"type":"boolean","nullable":true,"description":"Premium only"},"pre_foreclosure":{"type":"object","description":"Premium only","properties":{"flag":{"type":"boolean","nullable":true},"ind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"doc_type":{"type":"string","nullable":true},"recording_date":{"type":"string","nullable":true}}},"last_sale":{"type":"object","properties":{"date":{"type":"string","nullable":true,"example":"2022-05-15"},"price":{"type":"number","nullable":true,"example":750000},"document_type":{"type":"string","nullable":true},"mtg_amount":{"type":"number","nullable":true,"example":600000},"mtg_type":{"type":"string","nullable":true},"lender":{"type":"string","nullable":true,"example":"Wells Fargo"},"mtg_interest_rate":{"type":"number","nullable":true},"mtg_term_months":{"type":"number","nullable":true},"mtg_1_est_remaining":{"type":"number","nullable":true,"example":320000},"mtg_2_est_remaining":{"type":"number","nullable":true},"mtg_3_est_remaining":{"type":"number","nullable":true},"mtg_4_est_remaining":{"type":"number","nullable":true}}},"current_sale":{"type":"object","properties":{"doc_num":{"type":"string","nullable":true},"buyer_1":{"type":"string","nullable":true},"buyer_2":{"type":"string","nullable":true},"seller_1":{"type":"string","nullable":true},"seller_2":{"type":"string","nullable":true}}},"msa":{"type":"string","nullable":true,"example":"Los Angeles-Long Beach-Anaheim"},"county":{"type":"string","nullable":true,"example":"Los Angeles"},"property_type":{"type":"string","nullable":true,"example":"Single Family Residential"},"hoa":{"type":"number","nullable":true,"description":"HOA fee amount for the period indicated by hoa_frequency. Uses the primary HOA fee when available; falls back to the secondary HOA fee amount."},"hoa_frequency":{"type":"string","nullable":true,"enum":["annual","monthly","quarterly","semi_annual"],"description":"Billing frequency for the returned HOA fee amount. Values are normalized from First American HOA fee frequency codes."},"owner_type":{"type":"string","nullable":true,"description":"Premium only"},"purchase_method":{"type":"string","nullable":true},"listing_status":{"type":"string","nullable":true},"months_owned":{"type":"number","nullable":true}}}}}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"422":{"description":"Address could not be parsed into number, street, city, and zip"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/transactions":{"get":{"operationId":"sfr_property_transactions","summary":"Get property transactions","description":"Returns the complete transaction history for a property. Provide either address or property_id. If both are provided, property_id takes precedence.","parameters":[{"name":"address","required":false,"in":"query","description":"Full property address (optional when property_id is provided)","example":"123 Main St, Los Angeles, CA 90001","schema":{"type":"string"}},{"name":"property_id","required":false,"in":"query","description":"Stable SFRA property identifier. Preferred over address when available.","example":12345678,"schema":{"type":"number"}}],"responses":{"200":{"description":"Property transaction history","content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"string","example":"123 Main St, Los Angeles, CA 90001","nullable":true},"transactions":{"type":"array","items":{"type":"object","properties":{"RECORDING_DATE":{"type":"string","nullable":true,"example":"2022-05-15"},"APN":{"type":"string","nullable":true,"example":"1234-567-890"},"BUYER_BORROWER1_NAME":{"type":"string","nullable":true,"example":"Current Owner LLC"},"BUYER_BORROWER2_NAME":{"type":"string","nullable":true},"SALE_DATE":{"type":"string","nullable":true,"example":"2022-05-10"},"TRANSACTION_TYPE":{"type":"string","nullable":true,"example":"Resale"},"SELLER1_NAME":{"type":"string","nullable":true,"example":"Previous Owner"},"SALE_AMT":{"type":"string","nullable":true,"example":"750000"},"FIRST_MTG_RECORDING_DATE":{"type":"string","nullable":true,"example":"2022-05-15"},"FIRST_MTG_AMT":{"type":"string","nullable":true,"example":"600000"},"FIRST_MTG_LENDER_NAME":{"type":"string","nullable":true,"example":"Sample Bank"},"FIRST_MTG_DUE_DATE":{"type":"string","nullable":true,"example":"2052-05-15"}}}}}}}}},"400":{"description":"Invalid request - either address or property_id is required. Address must be non-empty; property_id must be a positive integer."},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]},"post":{"operationId":"PropertiesController_getPropertyTransactions","summary":"[DEPRECATED] Get property transactions","description":"DEPRECATED: Use GET /properties/transactions instead. Returns the complete transaction history for a property based on its address","deprecated":true,"parameters":[],"requestBody":{"required":true,"description":"Property address query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTransactionsDto"},"examples":{"standard":{"summary":"Standard address","value":{"address":"123 Main St, Los Angeles, CA 90001"}}}}}},"responses":{"200":{"description":"Property transaction history","content":{"application/json":{"example":[{"date":"2022-05-15","price":750000,"seller":"Previous Owner","buyer":"Current Owner LLC","transactionType":"sale","documentNumber":"DOC1234567","lenderName":"Sample Bank","loanAmount":600000},{"date":"2010-07-22","price":450000,"seller":"Original Owner","buyer":"Previous Owner","transactionType":"sale","documentNumber":"DOC7654321","lenderName":"Another Bank","loanAmount":350000}]}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/nearby-sales":{"get":{"operationId":"sfr_property_comps","summary":"Get nearby sales","description":"Returns nearby sales history for a property based on its address, with optional radius, lot size, building sqft, recording date, and year built filters. Nearby sale records include assessor-derived bedrooms and bathrooms when available. Fields sourced from assessor data (BEDROOMS, BATHROOMS, LOT_SIZE_SQFT, YEAR_BUILT) return null when the source data is missing — consumers should not treat null as 0. Range filters (e.g., lot_size_min, sqft_max, year_built_max) exclude records with null values for the filtered field, following RESO/OData semantics. By default this endpoint returns the legacy bare array; pass include_meta=true to receive an envelope with data and pagination metadata. Pass include=enrichment,valuation to add by-address-style property, ownership, geo, and valuation fields to each record.","parameters":[{"name":"address","required":true,"in":"query","description":"Full property address (e.g., \"123 Main St, Los Angeles, CA 90001\")","example":"123 Main St, Los Angeles, CA 90001","schema":{"minLength":1,"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Number of results per page (min 20, max 500)","example":50,"schema":{"minimum":20,"maximum":500,"default":50,"type":"number"}},{"name":"include_meta","required":false,"in":"query","description":"When true, return { data, meta } instead of the default bare array. Meta includes pagination, has_more, and candidate-limit flags.","example":true,"schema":{"default":false,"type":"boolean"}},{"name":"include","required":false,"in":"query","description":"Comma-separated enrichment groups to add to each nearby-sale record. Supported values: enrichment, valuation.","example":"enrichment,valuation","schema":{"default":"","type":"string"}},{"name":"lot_size_min","required":false,"in":"query","description":"Minimum lot size in sqft","example":5000,"schema":{"type":"number"}},{"name":"lot_size_max","required":false,"in":"query","description":"Maximum lot size in sqft","example":10000,"schema":{"type":"number"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum building sqft","example":1200,"schema":{"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum building sqft","example":3000,"schema":{"type":"number"}},{"name":"year_built_min","required":false,"in":"query","description":"Minimum year built","example":1980,"schema":{"type":"number"}},{"name":"year_built_max","required":false,"in":"query","description":"Maximum year built","example":2024,"schema":{"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Minimum recording date for comparable sales (YYYY-MM-DD)","example":"2025-10-23","schema":{"type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Maximum recording date for comparable sales (YYYY-MM-DD)","example":"2026-04-23","schema":{"type":"string"}},{"name":"radius","required":false,"in":"query","description":"Search radius in miles (default 1, max 50)","example":2,"schema":{"minimum":0,"maximum":50,"exclusiveMinimum":true,"type":"number"}}],"responses":{"200":{"description":"Nearby sales. Default response is a bare array; include_meta=true returns the envelope form.","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"RECORDING_DATE":{"type":"string","example":"2025-04-15"},"PROPERTY_ID":{"type":"number","example":12314331},"FULL_STREET_ADDRESS":{"type":"string","example":"1206 W 54TH ST"},"CITY":{"type":"string","example":"LOS ANGELES"},"STATE":{"type":"string","example":"CA"},"ZIP_CODE":{"type":"string","example":"90037"},"LATITUDE":{"type":"number","example":34.0522},"LONGITUDE":{"type":"number","example":-118.2437},"ZIP_PLUS_FOUR_CODE":{"type":"string","example":"1234","nullable":true},"CENSUS_TRACT":{"type":"string","example":"231501","nullable":true},"GEOCODING_ACCURACY":{"type":"string","example":"Rooftop","nullable":true},"SALE_AMT":{"type":"string","example":"352000"},"SUM_BUILDING_SQFT":{"type":"number","example":2315},"LOT_SIZE_SQFT":{"type":"number","example":6100,"nullable":true},"BEDROOMS":{"type":"number","example":4,"nullable":true},"BATHROOMS":{"type":"number","example":2,"nullable":true},"YEAR_BUILT":{"type":"number","example":1987,"nullable":true},"QUALITY":{"type":"string","example":"Average","nullable":true},"CONDITION":{"type":"string","example":"Average","nullable":true},"EFFECTIVE_YEAR_BUILT":{"type":"number","example":1995,"nullable":true},"STORIES":{"type":"string","example":"1 Story","nullable":true},"PARKING_SPACES_COUNT":{"type":"number","example":2,"nullable":true},"GARAGE_DESCRIPTION":{"type":"string","example":"Attached Garage","nullable":true},"POOL_TYPE":{"type":"string","example":"Pool","nullable":true},"FIREPLACES":{"type":"number","example":1,"nullable":true},"HEATING_TYPE":{"type":"string","example":"Central","nullable":true},"AC_DESCRIPTION":{"type":"string","example":"Central","nullable":true},"CONSTRUCTION_TYPE":{"type":"string","example":"Frame","nullable":true},"ROOMS_COUNT":{"type":"number","example":7,"nullable":true},"PARTIAL_BATHS_COUNT":{"type":"number","example":1,"nullable":true},"LIVING_AREA_SQFT":{"type":"number","example":1800,"nullable":true},"UNITS_COUNT":{"type":"number","example":1,"nullable":true},"BUILDING_COUNT":{"type":"number","example":1,"nullable":true},"OWNER_TYPE":{"type":"string","example":"Corporate","nullable":true},"CORPORATE_OWNER":{"type":"boolean","example":true,"nullable":true},"MONTHS_OWNED":{"type":"number","example":24,"nullable":true},"VALUATION_VALUE":{"type":"number","example":780000,"nullable":true},"VALUATION_HIGH":{"type":"number","example":820000,"nullable":true},"VALUATION_LOW":{"type":"number","example":740000,"nullable":true},"VALUATION_DATE":{"type":"string","example":"2026-04-01","nullable":true},"FORECAST_STD_DEV":{"type":"number","example":0.12,"nullable":true},"LAND_USE_CODE":{"type":"string","example":"1101"},"SALE_DATE":{"type":"string","example":"2025-04-10"},"BUYER_BORROWER1_NAME":{"type":"string","example":"Buyer name"},"SELLER1_NAME":{"type":"string","example":"Seller name"}}}},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"RECORDING_DATE":{"type":"string","example":"2025-04-15"},"PROPERTY_ID":{"type":"number","example":12314331},"FULL_STREET_ADDRESS":{"type":"string","example":"1206 W 54TH ST"},"CITY":{"type":"string","example":"LOS ANGELES"},"STATE":{"type":"string","example":"CA"},"ZIP_CODE":{"type":"string","example":"90037"},"LATITUDE":{"type":"number","example":34.0522},"LONGITUDE":{"type":"number","example":-118.2437},"ZIP_PLUS_FOUR_CODE":{"type":"string","example":"1234","nullable":true},"CENSUS_TRACT":{"type":"string","example":"231501","nullable":true},"GEOCODING_ACCURACY":{"type":"string","example":"Rooftop","nullable":true},"SALE_AMT":{"type":"string","example":"352000"},"SUM_BUILDING_SQFT":{"type":"number","example":2315},"LOT_SIZE_SQFT":{"type":"number","example":6100,"nullable":true},"BEDROOMS":{"type":"number","example":4,"nullable":true},"BATHROOMS":{"type":"number","example":2,"nullable":true},"YEAR_BUILT":{"type":"number","example":1987,"nullable":true},"QUALITY":{"type":"string","example":"Average","nullable":true},"CONDITION":{"type":"string","example":"Average","nullable":true},"EFFECTIVE_YEAR_BUILT":{"type":"number","example":1995,"nullable":true},"STORIES":{"type":"string","example":"1 Story","nullable":true},"PARKING_SPACES_COUNT":{"type":"number","example":2,"nullable":true},"GARAGE_DESCRIPTION":{"type":"string","example":"Attached Garage","nullable":true},"POOL_TYPE":{"type":"string","example":"Pool","nullable":true},"FIREPLACES":{"type":"number","example":1,"nullable":true},"HEATING_TYPE":{"type":"string","example":"Central","nullable":true},"AC_DESCRIPTION":{"type":"string","example":"Central","nullable":true},"CONSTRUCTION_TYPE":{"type":"string","example":"Frame","nullable":true},"ROOMS_COUNT":{"type":"number","example":7,"nullable":true},"PARTIAL_BATHS_COUNT":{"type":"number","example":1,"nullable":true},"LIVING_AREA_SQFT":{"type":"number","example":1800,"nullable":true},"UNITS_COUNT":{"type":"number","example":1,"nullable":true},"BUILDING_COUNT":{"type":"number","example":1,"nullable":true},"OWNER_TYPE":{"type":"string","example":"Corporate","nullable":true},"CORPORATE_OWNER":{"type":"boolean","example":true,"nullable":true},"MONTHS_OWNED":{"type":"number","example":24,"nullable":true},"VALUATION_VALUE":{"type":"number","example":780000,"nullable":true},"VALUATION_HIGH":{"type":"number","example":820000,"nullable":true},"VALUATION_LOW":{"type":"number","example":740000,"nullable":true},"VALUATION_DATE":{"type":"string","example":"2026-04-01","nullable":true},"FORECAST_STD_DEV":{"type":"number","example":0.12,"nullable":true},"LAND_USE_CODE":{"type":"string","example":"1101"},"SALE_DATE":{"type":"string","example":"2025-04-10"},"BUYER_BORROWER1_NAME":{"type":"string","example":"Buyer name"},"SELLER1_NAME":{"type":"string","example":"Seller name"}}}},"meta":{"type":"object","properties":{"page":{"type":"number","example":1},"page_size":{"type":"number","example":500},"count":{"type":"number","example":500},"total":{"type":"number","example":1234,"description":"Total records matching the filter within the candidate scan window. When candidate_limit_hit is true, this is a lower bound (total_is_exact will be false)."},"total_is_exact":{"type":"boolean","example":true,"description":"False when candidate_limit_hit is true — total reflects only the first candidate_limit candidates."},"has_more":{"type":"boolean","example":true,"description":"True when page * page_size < total. When candidate_limit_hit is true, has_more: false does NOT guarantee there are no further records — additional matches may exist beyond the candidate scan window. Treat has_more: false combined with candidate_limit_hit: true as \"retry with a tighter radius or date range\" rather than \"end of results\"."},"candidate_limit_hit":{"type":"boolean","example":false,"description":"True when the ClickHouse candidate scan returned exactly candidate_limit rows. Indicates results may be incomplete; narrow the search to get a complete set."},"candidate_limit":{"type":"number","example":20000}}}}}]}}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]},"post":{"operationId":"PropertiesController_getNearbySales","summary":"[DEPRECATED] Get nearby sales","description":"DEPRECATED: Use GET /properties/nearby-sales instead. Returns nearby sales history for a property based on its address","deprecated":true,"parameters":[],"requestBody":{"required":true,"description":"Property address query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetNearbySalesDto"},"examples":{"standard":{"summary":"Standard address","value":{"address":"123 Main St, Los Angeles, CA 90001"}}}}}},"responses":{"200":{"description":"Nearby sales","content":{"application/json":{"example":[{"RECORDING_DATE":"2025-04-15","PROPERTY_ID":12314331,"FULL_STREET_ADDRESS":"1206 W 54TH ST","CITY":"LOS ANGELES","STATE":"CA","ZIP_CODE":"90037","LATITUDE":34.0522,"LONGITUDE":-118.2437,"SALE_AMT":"352000","SUM_BUILDING_SQFT":2315,"LOT_SIZE_SQFT":6100,"BEDROOMS":4,"BATHROOMS":2,"YEAR_BUILT":"1987","LAND_USE_CODE":"1101","SALE_DATE":"2025-04-10","BUYER_BORROWER1_NAME":"Buyer name","SELLER1_NAME":"Seller name"}]}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/nearby-sold-properties":{"get":{"operationId":"PropertiesController_getNearbySoldPropertiesGet","summary":"Get nearby sold properties","description":"Returns nearby sold properties with full property details (beds, baths, equity, valuation, etc.) based on a property address, with optional filters for radius, lot size, sqft, year built, beds, and baths. Range filters (e.g., beds_min, lot_size_max) exclude records where the underlying assessor value is missing (null) or a placeholder zero, following RESO/OData semantics.","parameters":[{"name":"address","required":true,"in":"query","description":"Full property address (e.g., \"123 Main St, Los Angeles, CA 90001\")","example":"123 Main St, Los Angeles, CA 90001","schema":{"minLength":1,"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Number of results per page (max 100)","example":50,"schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"lot_size_min","required":false,"in":"query","description":"Minimum lot size in sqft","example":5000,"schema":{"type":"number"}},{"name":"lot_size_max","required":false,"in":"query","description":"Maximum lot size in sqft","example":10000,"schema":{"type":"number"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum building sqft","example":1200,"schema":{"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum building sqft","example":3000,"schema":{"type":"number"}},{"name":"year_built_min","required":false,"in":"query","description":"Minimum year built","example":1980,"schema":{"type":"number"}},{"name":"year_built_max","required":false,"in":"query","description":"Maximum year built","example":2024,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1.5,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4.5,"schema":{"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Search radius in miles (default 1)","example":2,"schema":{"minimum":0,"maximum":50,"exclusiveMinimum":true,"type":"number"}}],"responses":{"200":{"description":"Full property objects including details, valuation, features, and transaction history"},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]},"post":{"operationId":"PropertiesController_getNearbySaleProperties","summary":"[DEPRECATED] Get nearby sold properties","description":"DEPRECATED: Use GET /properties/nearby-sold-properties instead. Returns nearby sold properties based on a property address","deprecated":true,"parameters":[],"requestBody":{"required":true,"description":"Property address query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTransactionsDto"},"examples":{"standard":{"summary":"Standard address","value":{"address":"123 Main St, Los Angeles, CA 90001"}}}}}},"responses":{"200":{"description":"Property information including details, valuation, features, and transaction history","content":{"application/json":{"example":[{"address":"123 Main St, Los Angeles, CA 90001","propertyId":12345678,"latitude":34.052235,"longitude":-118.243683,"yearBuilt":1985,"bedrooms":3,"bathrooms":2,"buildingSqft":1800,"lotSqft":5500,"lastSaleDate":"2022-05-15","lastSalePrice":750000,"taxAssessedValue":700000,"estimatedValue":780000,"propertyType":"Single Family Residential","features":{"pool":true,"garage":true,"centralAC":true},"ownerInfo":{"name":"Sample Owner LLC","ownerType":"corporate","corporateOwned":true,"absenteeOwner":false},"recentTransactions":[{"date":"2022-05-15","price":750000,"seller":"Previous Owner","buyer":"Sample Owner LLC","transactionType":"sale"}]}]}}},"400":{"description":"Invalid request - address not recognized or malformed"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/properties/batch":{"get":{"operationId":"sfr_property_batch","summary":"Batch property lookup","description":"Look up multiple properties by address in a single request. Returns partial results - properties that cannot be found will include an error message. Maximum 100 addresses per request. Premium subscribers receive additional data fields.","parameters":[{"name":"addresses","required":true,"in":"query","description":"Pipe-separated (|) list of addresses. Max 100 addresses.","example":"123 Main St, Los Angeles, CA 90001|456 Oak Ave, New York, NY 10001","schema":{"minLength":1,"type":"string"}},{"name":"include_suggestions","required":false,"in":"query","description":"When true, NOT_FOUND results include nearby same-street address suggestions.","example":true,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Array of property lookup results","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","example":"123 Main St, Los Angeles, CA 90001"},"property":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"object","properties":{"formatted_street_address":{"type":"string","example":"123 Main St"},"street_number":{"type":"string","nullable":true,"example":"123"},"street_suffix":{"type":"string","nullable":true,"example":"St"},"street_pre_direction":{"type":"string","nullable":true},"street_name":{"type":"string","nullable":true,"example":"Main"},"street_post_direction":{"type":"string","nullable":true},"unit_type":{"type":"string","nullable":true},"unit_number":{"type":"string","nullable":true},"city":{"type":"string","example":"Los Angeles"},"state":{"type":"string","example":"CA"},"zip_code":{"type":"string","example":"90001"},"zip_plus_four_code":{"type":"string","nullable":true},"carrier_code":{"type":"string","nullable":true},"latitude":{"type":"number","example":34.052235},"longitude":{"type":"number","example":-118.243683},"geocoding_accuracy":{"type":"string","nullable":true},"census_tract":{"type":"string","nullable":true},"census_block":{"type":"string","nullable":true}}},"assessed_year":{"type":"number","nullable":true,"example":2023},"assessments":{"type":"object","properties":{"land_value":{"type":"number","nullable":true,"example":300000},"improvement_value":{"type":"number","nullable":true,"example":450000},"assessed_value":{"type":"number","nullable":true,"example":700000},"market_value":{"type":"number","nullable":true,"example":750000}}},"exemptions":{"type":"object","properties":{"homeowner":{"type":"boolean","nullable":true},"veteran":{"type":"boolean","nullable":true},"disabled":{"type":"boolean","nullable":true},"widow":{"type":"boolean","nullable":true},"senior":{"type":"boolean","nullable":true},"school":{"type":"boolean","nullable":true},"religious":{"type":"boolean","nullable":true},"welfare":{"type":"boolean","nullable":true},"public":{"type":"boolean","nullable":true},"cemetery":{"type":"boolean","nullable":true},"hospital":{"type":"boolean","nullable":true},"library":{"type":"boolean","nullable":true}}},"market_year":{"type":"number","nullable":true},"owner":{"type":"object","description":"Premium only","properties":{"owner_occupied":{"type":"boolean","nullable":true},"name":{"type":"string","nullable":true,"example":"Sample Owner LLC"},"second_name":{"type":"string","nullable":true},"formatted_street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip_code":{"type":"string","nullable":true},"zip_plus_four_code":{"type":"string","nullable":true},"corporate_owner":{"type":"boolean","nullable":true},"care_of_name":{"type":"string","nullable":true}}},"parcel":{"type":"object","properties":{"apn_original":{"type":"string","nullable":true},"fips_code":{"type":"string","nullable":true},"frontage_ft":{"type":"number","nullable":true},"depth_ft":{"type":"number","nullable":true},"area_acres":{"type":"number","nullable":true},"area_sq_ft":{"type":"number","nullable":true,"example":5500},"zoning":{"type":"string","nullable":true,"example":"R1"},"county_land_use_code":{"type":"string","nullable":true},"lot_number":{"type":"string","nullable":true},"subdivision":{"type":"string","nullable":true},"section_township_range":{"type":"string","nullable":true},"legal_description":{"type":"string","nullable":true},"state_land_use_code":{"type":"string","nullable":true},"building_count":{"type":"number","nullable":true}}},"school_tax_district_1":{"type":"string","nullable":true},"school_tax_district_2":{"type":"string","nullable":true},"school_tax_district_3":{"type":"string","nullable":true},"school_district_name":{"type":"string","nullable":true},"structure":{"type":"object","properties":{"total_area_sq_ft":{"type":"number","nullable":true,"example":1800},"year_built":{"type":"number","nullable":true,"example":1985},"effective_year_built":{"type":"number","nullable":true},"beds_count":{"type":"number","nullable":true,"example":3},"rooms_count":{"type":"number","nullable":true},"baths":{"type":"number","nullable":true,"example":2},"partial_baths_count":{"type":"number","nullable":true},"basement_type":{"type":"string","nullable":true},"condition":{"type":"string","nullable":true},"construction_type":{"type":"string","nullable":true},"exterior_wall_type":{"type":"string","nullable":true},"fireplaces":{"type":"string","nullable":true},"heating_type":{"type":"string","nullable":true},"heating_fuel_type":{"type":"string","nullable":true},"parking_spaces_count":{"type":"number","nullable":true},"pool_type":{"type":"string","nullable":true},"quality":{"type":"string","nullable":true},"roof_material_type":{"type":"string","nullable":true},"roof_style_type":{"type":"string","nullable":true},"sewer_type":{"type":"string","nullable":true},"stories":{"type":"string","nullable":true},"units_count":{"type":"number","nullable":true},"water_type":{"type":"string","nullable":true},"living_area_sqft":{"type":"number","nullable":true,"example":1650},"ac_description":{"type":"string","nullable":true},"garage_description":{"type":"string","nullable":true},"building_class_description":{"type":"string","nullable":true},"sqft_description":{"type":"string","nullable":true}}},"tax_amount":{"type":"number","nullable":true,"example":8500},"tax_delinquent_year":{"type":"number","nullable":true},"tax_rate_code_area":{"type":"string","nullable":true},"tax_year":{"type":"number","nullable":true,"example":2023},"valuation":{"type":"object","properties":{"value":{"type":"number","nullable":true,"example":780000},"high":{"type":"number","nullable":true,"example":820000},"low":{"type":"number","nullable":true,"example":740000},"forecast_standard_deviation":{"type":"number","nullable":true},"date":{"type":"string","nullable":true,"example":"2023-06-01"}}},"property_class_description":{"type":"string","nullable":true},"vacant":{"type":"boolean","nullable":true,"description":"Premium only"},"pre_foreclosure":{"type":"object","description":"Premium only","properties":{"flag":{"type":"boolean","nullable":true},"ind":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"doc_type":{"type":"string","nullable":true},"recording_date":{"type":"string","nullable":true}}},"last_sale":{"type":"object","properties":{"date":{"type":"string","nullable":true,"example":"2022-05-15"},"price":{"type":"number","nullable":true,"example":750000},"document_type":{"type":"string","nullable":true},"mtg_amount":{"type":"number","nullable":true,"example":600000},"mtg_type":{"type":"string","nullable":true},"lender":{"type":"string","nullable":true,"example":"Wells Fargo"},"mtg_interest_rate":{"type":"number","nullable":true},"mtg_term_months":{"type":"number","nullable":true},"mtg_1_est_remaining":{"type":"number","nullable":true,"example":320000},"mtg_2_est_remaining":{"type":"number","nullable":true},"mtg_3_est_remaining":{"type":"number","nullable":true},"mtg_4_est_remaining":{"type":"number","nullable":true}}},"current_sale":{"type":"object","properties":{"doc_num":{"type":"string","nullable":true},"buyer_1":{"type":"string","nullable":true},"buyer_2":{"type":"string","nullable":true},"seller_1":{"type":"string","nullable":true},"seller_2":{"type":"string","nullable":true}}},"msa":{"type":"string","nullable":true,"example":"Los Angeles-Long Beach-Anaheim"},"county":{"type":"string","nullable":true,"example":"Los Angeles"},"property_type":{"type":"string","nullable":true,"example":"Single Family Residential"},"hoa":{"type":"number","nullable":true,"description":"HOA fee amount for the period indicated by hoa_frequency. Uses the primary HOA fee when available; falls back to the secondary HOA fee amount."},"hoa_frequency":{"type":"string","nullable":true,"enum":["annual","monthly","quarterly","semi_annual"],"description":"Billing frequency for the returned HOA fee amount. Values are normalized from First American HOA fee frequency codes."},"owner_type":{"type":"string","nullable":true,"description":"Premium only"},"purchase_method":{"type":"string","nullable":true},"listing_status":{"type":"string","nullable":true},"months_owned":{"type":"number","nullable":true}},"nullable":true,"description":"Full property data (same shape as GET /properties/by-address). Null when lookup failed."},"error":{"type":"object","nullable":true,"description":"Error details when lookup failed. Null on success.","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_ADDRESS","GEOCODER_ERROR","SEARCH_ERROR"],"example":"NOT_FOUND"},"message":{"type":"string","example":"Property not found"},"retryable":{"type":"boolean","example":false}}},"suggestions":{"type":"array","nullable":true,"description":"Nearby same-street address suggestions returned only when include_suggestions=true.","items":{"type":"object","properties":{"property_id":{"type":"number","example":29857317},"address":{"type":"string","example":"7429 MEAD DR","nullable":true},"street_number":{"type":"string","example":"7429","nullable":true},"city":{"type":"string","example":"SPRING HILL","nullable":true},"state":{"type":"string","example":"FL","nullable":true},"zip_code":{"type":"string","example":"34606","nullable":true},"distance":{"type":"number","example":2},"owner":{"type":"string","example":"MARY BAHMILLER","nullable":true,"description":"Present only for premium subscribers. Non-premium callers will not see this key at all."},"owner_2":{"type":"string","example":"PAUL BAHMILLER","nullable":true,"description":"Present only for premium subscribers. Non-premium callers will not see this key at all."}}}}}}}}}},"400":{"description":"Invalid request - addresses missing or exceeds maximum"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["properties"],"security":[{"api-key":[]}]},"post":{"operationId":"PropertiesController_batchPropertyLookup","summary":"[DEPRECATED] Batch property lookup","description":"DEPRECATED: Use GET /properties/batch instead. Look up multiple properties by address in a single request. Returns partial results - properties that cannot be found will include an error message. Maximum 100 addresses per request. Premium subscribers receive additional data fields.","deprecated":true,"parameters":[],"requestBody":{"required":true,"description":"Array of property addresses to look up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPropertyLookupDto"},"examples":{"multiple":{"summary":"Multiple addresses","description":"Look up several properties at once","value":{"include_suggestions":false,"addresses":["123 Main St, Los Angeles, CA 90001","456 Oak Ave, New York, NY 10001","789 Pine Blvd, Miami, FL 33101"]}}}}}},"responses":{"200":{"description":"Array of property lookup results","content":{"application/json":{"example":[{"address":"123 Main St, Los Angeles, CA 90001","property":{"property_id":12345678,"address":{"formatted_street_address":"123 Main St","city":"Los Angeles","state":"CA","zip_code":"90001"},"structure":{"beds_count":3,"baths":2,"total_area_sq_ft":1800},"valuation":{"value":780000}},"error":null},{"address":"456 Oak Ave, New York, NY 10001","property":null,"error":{"code":"NOT_FOUND","message":"Property not found","retryable":false},"suggestions":[]}]}}},"400":{"description":"Invalid request - addresses array missing, empty, or exceeds maximum"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["properties"],"security":[{"api-key":[]}]}},"/borrowers":{"get":{"operationId":"BorrowersController_getBorrowers","summary":"Search borrowers by name","description":"Search for borrowers (mortgage holders) by name across the database. Returns matching borrower records with loan and property information.\n\n**Note:** This endpoint requires partner authentication (external API tokens) rather than standard user API keys. Contact support for partner access.","parameters":[{"name":"buyer_borrower_name","required":true,"in":"query","description":"Buyer/borrower name to search","example":"BLACKSTONE","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","description":"2-letter state code","example":"CA","schema":{"type":"string"}},{"name":"similarity_score","required":false,"in":"query","description":"Minimum similarity score (0-100)","example":80,"schema":{"default":80,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","example":1,"schema":{"default":1,"type":"number"}}],"responses":{"200":{"description":"List of borrowers matching the search criteria"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["borrowers"],"security":[{"api-key":[]}]},"post":{"operationId":"BorrowersController_getBorrowersByName","summary":"[DEPRECATED] Search borrowers by name","description":"**DEPRECATED: Use GET /borrowers instead. This endpoint will be removed on December 31, 2026.**\n\nSearch for borrowers (mortgage holders) by name across the database. Returns matching borrower records with loan and property information.\n\n**Note:** This endpoint requires partner authentication (external API tokens) rather than standard user API keys. Contact support for partner access.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetBorrowersByNameDto"},"examples":{"basic":{"summary":"Search by name","value":{"name":"Smith"}},"withState":{"summary":"Search by name and state","value":{"name":"Johnson","state":"CA"}}}}}},"responses":{"200":{"description":"List of borrowers matching the search criteria"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["borrowers"],"security":[{"api-key":[]}]}},"/borrowers/buyers-by-name-state":{"get":{"operationId":"BorrowersController_getBuyersByNameAndState","summary":"Get buyers by name and state","description":"Search for real estate buyers by name within a specific state. Returns paginated buyer records with transaction history and portfolio information.\n\n**Note:** This endpoint requires partner authentication (external API tokens) rather than standard user API keys. Contact support for partner access.","parameters":[{"name":"pageSize","required":false,"in":"query","description":"Number of results per page (default: 20)","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (default: 1)","schema":{"type":"number"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (e.g., CA, TX, FL)","schema":{"type":"string"}},{"name":"name","required":true,"in":"query","description":"Buyer name to search for","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of buyers with transaction details"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["borrowers"],"security":[{"api-key":[]}]}},"/buyers/activity":{"get":{"operationId":"sfr_investor_activity","summary":"Get paginated buyer activity","description":"Returns a paginated list of buyer activity records based on specified filters.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"los-angeles-ca","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"90210,90211","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":34.0522,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-118.2437,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Min sales date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Max sales date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sales price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sales price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"minimum":0,"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":4,"schema":{"minimum":0,"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":3,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_min","required":false,"in":"query","description":"Minimum properties owned by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_max","required":false,"in":"query","description":"Maximum properties owned by buyer","example":10,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_min","required":false,"in":"query","description":"Minimum transactions by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_max","required":false,"in":"query","description":"Maximum transactions by buyer","example":20,"schema":{"minimum":0,"type":"number"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo/Townhouse","schema":{"minLength":1,"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name (partial match)","example":"Smith","schema":{"type":"string"}},{"name":"is_cash_buyer","required":false,"in":"query","description":"Filter for cash purchases only","example":true,"schema":{"type":"boolean"}},{"name":"exclude_homebuilders","required":false,"in":"query","description":"Exclude buyers classified as homebuilders","example":true,"schema":{"type":"boolean"}},{"name":"purchase_type","required":false,"in":"query","description":"Filter by purchase type: all, non-discount, discounted","schema":{"default":"all","enum":["all","non-discount","discounted"],"type":"string"}},{"name":"buyer_type","required":false,"in":"query","description":"Filter by buyer type: all, individual, corporate","schema":{"default":"all","enum":["all","individual","corporate"],"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page","example":20,"schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending (e.g., -recording_date)","example":"-recording_date","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of buyer activity records","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":12345},"propertyId":{"type":"number","example":67890},"recordingDate":{"type":"string","example":"2023-06-15"},"buyerName":{"type":"string","nullable":true,"example":"ACME INVESTMENTS LLC"},"formattedBuyerName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"lenderName":{"type":"string","nullable":true,"example":"Wells Fargo"},"address":{"type":"string","nullable":true,"example":"123 Main St"},"phone":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"example":"Los Angeles"},"state":{"type":"string","nullable":true,"example":"CA"},"zipCode":{"type":"string","nullable":true,"example":"90210"},"buildingArea":{"type":"number","nullable":true,"example":1800},"yearBuilt":{"type":"number","nullable":true,"example":1985},"avmValue":{"type":"number","nullable":true,"example":500000},"saleValue":{"type":"number","nullable":true,"example":450000},"saleDate":{"type":"string","nullable":true,"example":"2023-06-10"},"sellerName":{"type":"string","nullable":true,"example":"John Smith"},"latitude":{"type":"number","nullable":true,"example":34.0522},"longitude":{"type":"number","nullable":true,"example":-118.2437},"isCorporate":{"type":"boolean","example":true},"isDiscountedPurchase":{"type":"boolean","example":false},"isCashBuyer":{"type":"boolean","example":true},"isPrivateLender":{"type":"boolean","example":false},"buyerCategory":{"type":"string","nullable":true},"bedrooms":{"type":"number","nullable":true,"example":3},"bathrooms":{"type":"number","nullable":true,"example":2},"propertyType":{"type":"string","nullable":true,"example":"Single Family Residential"},"msa":{"type":"string","nullable":true,"example":"los-angeles-ca"},"loanAmount":{"type":"number","nullable":true,"example":350000},"buyerPropertiesCount":{"type":"number","nullable":true,"example":12},"buyerTransactionsCount":{"type":"number","nullable":true,"example":25},"hasProfilePage":{"type":"boolean","example":true},"exitDate":{"type":"string","nullable":true,"example":"2024-03-15"},"exitValue":{"type":"number","nullable":true,"example":520000},"exitBuyerName":{"type":"string","nullable":true,"example":"New Buyer LLC"},"holdDays":{"type":"number","nullable":true,"example":273},"profitLoss":{"type":"number","nullable":true,"example":70000}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/activity/count":{"get":{"operationId":"BuyersController_getBuyersActivityCountGet","summary":"Get buyer activity count","description":"Returns the total count of buyer activity records matching the specified filters.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"los-angeles-ca","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"90210,90211","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":34.0522,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-118.2437,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Min sales date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Max sales date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sales price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sales price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"minimum":0,"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":4,"schema":{"minimum":0,"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":3,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_min","required":false,"in":"query","description":"Minimum properties owned by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_max","required":false,"in":"query","description":"Maximum properties owned by buyer","example":10,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_min","required":false,"in":"query","description":"Minimum transactions by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_max","required":false,"in":"query","description":"Maximum transactions by buyer","example":20,"schema":{"minimum":0,"type":"number"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo/Townhouse","schema":{"minLength":1,"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name (partial match)","example":"Smith","schema":{"type":"string"}},{"name":"is_cash_buyer","required":false,"in":"query","description":"Filter for cash purchases only","example":true,"schema":{"type":"boolean"}},{"name":"exclude_homebuilders","required":false,"in":"query","description":"Exclude buyers classified as homebuilders","example":true,"schema":{"type":"boolean"}},{"name":"purchase_type","required":false,"in":"query","description":"Filter by purchase type: all, non-discount, discounted","schema":{"default":"all","enum":["all","non-discount","discounted"],"type":"string"}},{"name":"buyer_type","required":false,"in":"query","description":"Filter by buyer type: all, individual, corporate","schema":{"default":"all","enum":["all","individual","corporate"],"type":"string"}}],"responses":{"200":{"description":"Total count of buyer activity records","content":{"application/json":{"schema":{"type":"number","example":1542}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getBuyersActivityCount","summary":"[DEPRECATED] Get buyer activity count","description":"**DEPRECATED: Use GET /buyers/activity/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of buyer activity records matching the specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyersActivityFilterDto"}}}},"responses":{"200":{"description":"Total count of buyer activity records"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/activity/top-buyers":{"get":{"operationId":"sfr_top_buyers","summary":"Get top active buyers","description":"Returns analytics about the most active buyers in the specified time period and region.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"los-angeles-ca","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"90210,90211","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":34.0522,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-118.2437,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Min sales date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Max sales date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sales price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sales price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"minimum":0,"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":4,"schema":{"minimum":0,"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":3,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_min","required":false,"in":"query","description":"Minimum properties owned by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_max","required":false,"in":"query","description":"Maximum properties owned by buyer","example":10,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_min","required":false,"in":"query","description":"Minimum transactions by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_max","required":false,"in":"query","description":"Maximum transactions by buyer","example":20,"schema":{"minimum":0,"type":"number"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo/Townhouse","schema":{"minLength":1,"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name (partial match)","example":"Smith","schema":{"type":"string"}},{"name":"is_cash_buyer","required":false,"in":"query","description":"Filter for cash purchases only","example":true,"schema":{"type":"boolean"}},{"name":"exclude_homebuilders","required":false,"in":"query","description":"Exclude buyers classified as homebuilders","example":true,"schema":{"type":"boolean"}},{"name":"purchase_type","required":false,"in":"query","description":"Filter by purchase type: all, non-discount, discounted","schema":{"default":"all","enum":["all","non-discount","discounted"],"type":"string"}},{"name":"buyer_type","required":false,"in":"query","description":"Filter by buyer type: all, individual, corporate","schema":{"default":"all","enum":["all","individual","corporate"],"type":"string"}}],"responses":{"200":{"description":"List of top active buyers with purchase counts and total sales volume","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"ACME INVESTMENTS LLC"},"formattedName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"acquisitions":{"type":"number","example":47},"acquisitions90d":{"type":"number","example":12,"nullable":true},"hasProfilePage":{"type":"boolean","example":true},"hasContactInfo":{"type":"boolean","example":true}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getTopActiveBuyers","summary":"[DEPRECATED] Get top active buyers","description":"**DEPRECATED: Use GET /buyers/activity/top-buyers instead. This endpoint will be removed on December 31, 2026.**\n\nReturns analytics about the most active buyers in the specified time period and region.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyersActivityFilterDto"}}}},"responses":{"200":{"description":"List of top active buyers with purchase counts and total sales volume"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/activity/top-trailing-buyers":{"get":{"operationId":"BuyersController_getTopActiveTrailingBuyersGet","summary":"Get top trailing buyers","description":"Returns analytics about the most active trailing buyers in the specified time period and region.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"los-angeles-ca","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"90210,90211","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":34.0522,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-118.2437,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Min sales date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Max sales date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sales price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sales price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"minimum":0,"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":4,"schema":{"minimum":0,"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":3,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_sqft_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_min","required":false,"in":"query","description":"Minimum properties owned by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_properties_count_max","required":false,"in":"query","description":"Maximum properties owned by buyer","example":10,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_min","required":false,"in":"query","description":"Minimum transactions by buyer","example":1,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_transactions_count_max","required":false,"in":"query","description":"Maximum transactions by buyer","example":20,"schema":{"minimum":0,"type":"number"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo/Townhouse","schema":{"minLength":1,"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name (partial match)","example":"Smith","schema":{"type":"string"}},{"name":"is_cash_buyer","required":false,"in":"query","description":"Filter for cash purchases only","example":true,"schema":{"type":"boolean"}},{"name":"exclude_homebuilders","required":false,"in":"query","description":"Exclude buyers classified as homebuilders","example":true,"schema":{"type":"boolean"}},{"name":"purchase_type","required":false,"in":"query","description":"Filter by purchase type: all, non-discount, discounted","schema":{"default":"all","enum":["all","non-discount","discounted"],"type":"string"}},{"name":"buyer_type","required":false,"in":"query","description":"Filter by buyer type: all, individual, corporate","schema":{"default":"all","enum":["all","individual","corporate"],"type":"string"}}],"responses":{"200":{"description":"List of top trailing buyers with purchase counts and total sales volume","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"ACME INVESTMENTS LLC"},"formattedName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"acquisitions":{"type":"number","example":47},"acquisitions90d":{"type":"number","example":12,"nullable":true},"hasProfilePage":{"type":"boolean","example":true},"hasContactInfo":{"type":"boolean","example":true}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getTopActiveTrailingBuyers","summary":"[DEPRECATED] Get top trailing buyers","description":"**DEPRECATED: Use GET /buyers/activity/top-trailing-buyers instead. This endpoint will be removed on December 31, 2026.**\n\nReturns analytics about the most active trailing buyers in the specified time period and region.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyersActivityFilterDto"}}}},"responses":{"200":{"description":"List of top trailing buyers with purchase counts and total sales volume"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/activity/page":{"post":{"operationId":"BuyersController_getBuyersActivity","summary":"[DEPRECATED] Get paginated buyer activity","description":"**DEPRECATED: Use GET /buyers/activity instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of buyer activity records based on specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyersActivityPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of buyer activity records"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/transactions":{"get":{"operationId":"BuyersController_getBuyerTransactionsPageGet","summary":"Get paginated buyer transactions","description":"Returns a paginated list of transactions for a specific buyer.\n\n**This is the preferred endpoint.** The POST /transactions/page endpoint is deprecated.","parameters":[{"name":"sort","required":false,"in":"query","description":"Sort field with optional direction prefix. Use \"-\" for descending (e.g., \"-recording_date\")","schema":{}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default: 20, max: 100)","schema":{}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","schema":{}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","schema":{}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area","schema":{}},{"name":"buyer","required":true,"in":"query","description":"Canonical buyer name from SFRA buyer outputs.","schema":{}}],"responses":{"200":{"description":"Paginated list of buyer transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/transactions/count":{"get":{"operationId":"BuyersController_getBuyerTransactionsCountGet","summary":"Get buyer transactions count","description":"Returns the total count of transactions for a specific buyer.\n\n**This is the preferred endpoint.** The POST /transactions/count endpoint is deprecated.","parameters":[{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","schema":{}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","schema":{}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area","schema":{}},{"name":"buyer","required":true,"in":"query","description":"Canonical buyer name from SFRA buyer outputs.","schema":{}}],"responses":{"200":{"description":"Total count of buyer transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getBuyerTransactionsCount","summary":"[DEPRECATED] Get buyer transactions count","description":"**DEPRECATED: Use GET /buyers/transactions/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of transactions for a specific buyer.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerTransactionsFilterDto"}}}},"responses":{"200":{"description":"Total count of buyer transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/transactions/page":{"post":{"operationId":"BuyersController_getBuyerTransactionsPage","summary":"[DEPRECATED] Get paginated buyer transactions","description":"**DEPRECATED: Use GET /buyers/transactions instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of transactions for a specific buyer.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerTransactionsPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of buyer transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/transactions/{id}":{"get":{"operationId":"BuyersController_getTransaction","summary":"Get transaction by ID","description":"Returns detailed information about a specific transaction by its ID.","parameters":[{"name":"id","required":true,"in":"path","description":"Transaction ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Transaction details"},"404":{"description":"Transaction not found"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market":{"get":{"operationId":"sfr_activity_highlights","summary":"Get paginated market transactions","description":"Returns a paginated list of market transactions based on specified filters.\n\n**This is the preferred endpoint.** The POST /market/page endpoint is deprecated.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Number of results per page (max 100)","example":20,"schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field with optional direction prefix. Use \"-\" prefix for descending (e.g., \"-recording_date\")","example":"-recording_date","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of market transactions","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":12345},"propertyId":{"type":"number","example":67890},"recordingDate":{"type":"string","example":"2023-06-15"},"buyerName":{"type":"string","nullable":true,"example":"ACME INVESTMENTS LLC"},"formattedBuyerName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"lenderName":{"type":"string","nullable":true,"example":"Wells Fargo"},"address":{"type":"string","nullable":true,"example":"123 Main St"},"phone":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"example":"Los Angeles"},"state":{"type":"string","nullable":true,"example":"CA"},"zipCode":{"type":"string","nullable":true,"example":"90210"},"buildingArea":{"type":"number","nullable":true,"example":1800},"yearBuilt":{"type":"number","nullable":true,"example":1985},"avmValue":{"type":"number","nullable":true,"example":500000},"saleValue":{"type":"number","nullable":true,"example":450000},"saleDate":{"type":"string","nullable":true,"example":"2023-06-10"},"sellerName":{"type":"string","nullable":true,"example":"John Smith"},"latitude":{"type":"number","nullable":true,"example":34.0522},"longitude":{"type":"number","nullable":true,"example":-118.2437},"isCorporate":{"type":"boolean","example":true},"isDiscountedPurchase":{"type":"boolean","example":false},"isCashBuyer":{"type":"boolean","example":true},"isPrivateLender":{"type":"boolean","example":false},"buyerCategory":{"type":"string","nullable":true},"bedrooms":{"type":"number","nullable":true,"example":3},"bathrooms":{"type":"number","nullable":true,"example":2},"propertyType":{"type":"string","nullable":true,"example":"Single Family Residential"},"msa":{"type":"string","nullable":true,"example":"los-angeles-ca"},"loanAmount":{"type":"number","nullable":true,"example":350000},"buyerPropertiesCount":{"type":"number","nullable":true,"example":12},"buyerTransactionsCount":{"type":"number","nullable":true,"example":25},"hasProfilePage":{"type":"boolean","example":true},"exitDate":{"type":"string","nullable":true,"example":"2024-03-15"},"exitValue":{"type":"number","nullable":true,"example":520000},"exitBuyerName":{"type":"string","nullable":true,"example":"New Buyer LLC"},"holdDays":{"type":"number","nullable":true,"example":273},"profitLoss":{"type":"number","nullable":true,"example":70000}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/count":{"get":{"operationId":"BuyersController_getMarketTransactionsCountGet","summary":"Get market transactions count","description":"Returns the total count of market transactions matching the specified filters.\n\n**This is the preferred endpoint.** The POST /market/count endpoint is deprecated.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo","schema":{"type":"string"}}],"responses":{"200":{"description":"Total count of market transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getMarketTransactionsCount","summary":"[DEPRECATED] Get market transactions count","description":"**DEPRECATED: Use GET /buyers/market/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of market transactions matching the specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketTransactionsFilterDto"}}}},"responses":{"200":{"description":"Total count of market transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/top-buyers":{"get":{"operationId":"sfr_market_highlights","summary":"Get top market buyers","description":"Returns the most active buyers in a specific market based on specified filters.\n\n**This is the preferred endpoint.** The POST /market/top-buyers endpoint is deprecated.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated list of property types","example":"Single Family Residential,Condo","schema":{"type":"string"}}],"responses":{"200":{"description":"List of top market buyers with purchase counts and total sales volume","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"ACME INVESTMENTS LLC"},"formattedName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"acquisitions":{"type":"number","example":47},"acquisitions90d":{"type":"number","nullable":true,"example":12},"hasProfilePage":{"type":"boolean","example":true},"hasContactInfo":{"type":"boolean","example":true}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getMarketTopBuyers","summary":"[DEPRECATED] Get top market buyers","description":"**DEPRECATED: Use GET /buyers/market/top-buyers instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the most active buyers in a specific market based on specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketTransactionsFilterDto"}}}},"responses":{"200":{"description":"List of top market buyers with purchase counts and total sales volume"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/investor-activity":{"get":{"operationId":"sfr_market_investor_activity","summary":"Get market investor activity","description":"Returns yearly investor activity for a market summary chart. This public endpoint mirrors the internal market-summary surface.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}}],"responses":{"200":{"description":"Yearly investor activity with monthly counts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number","example":2023},"monthlyActivity":{"type":"array","items":{"type":"number"},"example":[120,135,142,158,167,175,180,172,165,155,140,130]}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/flip-activity":{"get":{"operationId":"sfr_market_flip_activity","summary":"Get market flip activity","description":"Returns yearly flip activity for a market summary chart. This public endpoint mirrors the internal market-summary surface.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}}],"responses":{"200":{"description":"Yearly flip activity with monthly counts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number","example":2023},"monthlyActivity":{"type":"array","items":{"type":"number"},"example":[45,52,48,61,55,63,58,50,47,42,38,35]}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/largest-owners":{"get":{"operationId":"sfr_market_largest_owners","summary":"Get market largest owners","description":"Returns the largest owners in a market summary view. This public endpoint mirrors the internal market-summary surface.","parameters":[{"name":"msa","required":true,"in":"query","description":"Metropolitan Statistical Area (required)","example":"los-angeles-ca","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive)","example":"Chicago","schema":{"minLength":1,"maxLength":255,"type":"string"}}],"responses":{"200":{"description":"List of largest owners in the selected market","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"ACME INVESTMENTS LLC"},"numCompletedFlips":{"type":"number","nullable":true,"example":15},"numPurchases":{"type":"number","nullable":true,"example":47}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/best-buyers":{"get":{"operationId":"sfr_best_buyers","summary":"Get best buyers for a property","description":"Returns a ranked list of the most relevant buyers for a specific property address based on their purchase history, activity level, and proximity.\n\n**This is the preferred endpoint.** The POST /best-buyers endpoint is deprecated.","parameters":[{"name":"address","required":true,"in":"query","description":"Full property address to find matching buyers for","example":"2930 W Beverly Blvd, Los Angeles, CA 90057","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"Ranked list of best buyers with match scores and reasons","content":{"application/json":{"schema":{"type":"object","properties":{"propertyAddress":{"type":"string","example":"2930 W Beverly Blvd, Los Angeles, CA 90057"},"buyers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"ACME INVESTMENTS LLC"},"formattedName":{"type":"string","nullable":true,"example":"Acme Investments Llc"},"matchScore":{"type":"number","example":92.5},"matchReasons":{"type":"array","items":{"type":"string"},"example":["Purchased 3 properties within 0.25 miles","Active buyer in last 90 days"]},"totalAcquisitions":{"type":"number","example":47},"purchasesWithinQuarterMile":{"type":"number","example":3},"purchasesWithinOneMile":{"type":"number","example":8},"recentPurchasesCount":{"type":"number","example":5}}}}}}}}}},"tags":["buyers"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyersController_getBestBuyers","summary":"[DEPRECATED] Get best buyers for a property","description":"**DEPRECATED: Use GET /buyers/best-buyers instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a ranked list of the most relevant buyers for a specific property address based on their purchase history, activity level, and proximity.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestBuyersRequestDto"}}}},"responses":{"200":{"description":"Ranked list of best buyers with match scores and reasons"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyers/market/page":{"post":{"operationId":"BuyersController_getMarketTransactionsPage","summary":"[DEPRECATED] Get paginated market transactions","description":"**DEPRECATED: Use GET /buyers/market instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of market transactions based on specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketTransactionsPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of market transactions"}},"tags":["buyers"],"security":[{"api-key":[]}]}},"/buyer-profiles":{"get":{"operationId":"BuyerProfilesController_getPortfoliosPageGet","summary":"Get paginated buyer portfolios","description":"Returns a paginated list of buyer portfolios based on filtering criteria. Includes portfolio metrics and growth data.","parameters":[{"name":"states","required":false,"in":"query","description":"Comma-separated 2-letter state codes (e.g., CA,NY,FL)","example":"CA,NY,FL","schema":{"type":"array","items":{"type":"string"}}},{"name":"msas","required":false,"in":"query","description":"Comma-separated MSA names","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"array","items":{"type":"string"}}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,10001","schema":{"type":"array","items":{"type":"string"}}},{"name":"cities","required":false,"in":"query","description":"Comma-separated city names","example":"Los Angeles,New York","schema":{"type":"array","items":{"type":"string"}}},{"name":"counties","required":false,"in":"query","description":"Comma-separated county names","example":"Los Angeles County","schema":{"type":"array","items":{"type":"string"}}},{"name":"properties_count_min","required":false,"in":"query","description":"Minimum property count","example":10,"schema":{"type":"number"}},{"name":"properties_count_max","required":false,"in":"query","description":"Maximum property count","example":100,"schema":{"type":"number"}},{"name":"portfolio_value_min","required":false,"in":"query","description":"Minimum portfolio value","example":1000000,"schema":{"type":"number"}},{"name":"portfolio_value_max","required":false,"in":"query","description":"Maximum portfolio value","example":10000000,"schema":{"type":"number"}},{"name":"annual_gross_yield_pct_min","required":false,"in":"query","description":"Minimum annual gross yield %","example":5,"schema":{"type":"number"}},{"name":"annual_gross_yield_pct_max","required":false,"in":"query","description":"Maximum annual gross yield %","example":12,"schema":{"type":"number"}},{"name":"portfolio_types","required":false,"in":"query","description":"Comma-separated portfolio types (buy_and_hold, fix_and_flip, mixed)","example":"buy_and_hold,fix_and_flip","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default: 20, max: 1000)","schema":{"maximum":1000,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending. Options: properties_count, portfolio_value, annual_gross_yield_pct, median_property_value, median_purchase_amount, buyer_name","example":"-properties_count","schema":{"default":"-properties_count","type":"string"}}],"responses":{"200":{"description":"Paginated list of buyer portfolios with property counts, valuation, and other portfolio metrics"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getPortfoliosPage","summary":"[DEPRECATED] Get paginated buyer portfolios","description":"DEPRECATED: Use GET /buyer-profiles instead. This endpoint will be removed on December 31, 2026.\n\nReturns a paginated list of buyer portfolios based on filtering criteria. Includes portfolio metrics and growth data.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfoliosPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of buyer portfolios with property counts, valuation, and other portfolio metrics"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/count":{"get":{"operationId":"BuyerProfilesController_getPortfoliosCountGet","summary":"Get buyer portfolios count","description":"Returns the total count of buyer portfolios matching the specified filters","parameters":[{"name":"states","required":false,"in":"query","description":"Comma-separated 2-letter state codes (e.g., CA,NY,FL)","example":"CA,NY,FL","schema":{"type":"array","items":{"type":"string"}}},{"name":"msas","required":false,"in":"query","description":"Comma-separated MSA names","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"array","items":{"type":"string"}}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,10001","schema":{"type":"array","items":{"type":"string"}}},{"name":"cities","required":false,"in":"query","description":"Comma-separated city names","example":"Los Angeles,New York","schema":{"type":"array","items":{"type":"string"}}},{"name":"counties","required":false,"in":"query","description":"Comma-separated county names","example":"Los Angeles County","schema":{"type":"array","items":{"type":"string"}}},{"name":"properties_count_min","required":false,"in":"query","description":"Minimum property count","example":10,"schema":{"type":"number"}},{"name":"properties_count_max","required":false,"in":"query","description":"Maximum property count","example":100,"schema":{"type":"number"}},{"name":"portfolio_value_min","required":false,"in":"query","description":"Minimum portfolio value","example":1000000,"schema":{"type":"number"}},{"name":"portfolio_value_max","required":false,"in":"query","description":"Maximum portfolio value","example":10000000,"schema":{"type":"number"}},{"name":"annual_gross_yield_pct_min","required":false,"in":"query","description":"Minimum annual gross yield %","example":5,"schema":{"type":"number"}},{"name":"annual_gross_yield_pct_max","required":false,"in":"query","description":"Maximum annual gross yield %","example":12,"schema":{"type":"number"}},{"name":"portfolio_types","required":false,"in":"query","description":"Comma-separated portfolio types (buy_and_hold, fix_and_flip, mixed)","example":"buy_and_hold,fix_and_flip","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Total count of buyer portfolios matching the criteria","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":125}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getPortfoliosCount","summary":"[DEPRECATED] Get buyer portfolios count","description":"DEPRECATED: Use GET /buyer-profiles/count instead. This endpoint will be removed on December 31, 2026.\n\nReturns the total count of buyer portfolios matching the specified filters","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfoliosFilterDto"}}}},"responses":{"200":{"description":"Total count of buyer portfolios matching the criteria","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":125}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/activity":{"get":{"operationId":"sfr_buyer_detail_activity_query","summary":"Get paginated buyer activity by name","description":"Returns a paginated list of transactions for a specific buyer matching the specified filters. Use this query-parameter endpoint for buyer names that contain path separators such as \"/\".","parameters":[{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2024-01-01","schema":{"type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2024-12-31","schema":{"type":"string"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default: 20, max: 1000)","schema":{"maximum":1000,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending. Options: current_sale_recording_date, current_sale_price, bedrooms, bathrooms","example":"-current_sale_recording_date","schema":{"default":"-current_sale_recording_date","type":"string"}},{"name":"name","required":true,"in":"query","description":"Buyer name","example":"M/I HOMES OF AUSTIN LLC","schema":{}}],"responses":{"200":{"description":"Paginated list of buyer activity records"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}":{"get":{"operationId":"sfr_buyer_profile","summary":"Get buyer profile by name","description":"Returns detailed information about a specific buyer's profile including portfolio statistics and investment patterns","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"responses":{"200":{"description":"Buyer profile with portfolio statistics","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"BLACKSTONE GROUP"},"portfolio":{"type":"object","nullable":true,"properties":{"propertiesCount":{"type":"number","example":47},"portfolioValue":{"type":"number","nullable":true,"example":18500000},"averagePurchasePrice":{"type":"number","nullable":true,"example":393617},"averagePropertyValue":{"type":"number","nullable":true,"example":425000},"averagePurchaseYear":{"type":"number","nullable":true,"example":2020},"averageYearBuilt":{"type":"number","nullable":true,"example":1985},"topZipCodes":{"type":"array","items":{"type":"string"},"example":["90210"]}}},"mostActiveMsa":{"type":"string","nullable":true,"example":"los-angeles-ca"},"relatedLLCs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"BLACKSTONE HOLDINGS LLC"},"formattedName":{"type":"string","example":"Blackstone Holdings Llc"},"address":{"type":"string","nullable":true,"example":"123 Main St"}}}},"investorProfile":{"type":"object","nullable":true,"properties":{"summary":{"type":"string","example":"Active fix-and-flip investor focused on the Phoenix metro area."},"businessModelStrategy":{"type":"object","properties":{"primaryStrategy":{"type":"string","example":"Fix and Flip"},"flipPercentage":{"type":"string","example":"85%"},"holdPercentage":{"type":"string","example":"15%"},"competitivePositioning":{"type":"string","example":"High-volume operator with strong local market knowledge"},"targetReturns":{"type":"object","properties":{"marginRange":{"type":"string","example":"15-30%"},"medianMargin":{"type":"string","example":"22%"}}}}},"dealParameters":{"type":"object","properties":{"acquisitionMethod":{"type":"object","properties":{"cash":{"type":"string","example":"60%"},"conventional":{"type":"string","example":"25%"},"privateLending":{"type":"string","example":"15%"}}},"priceRange":{"type":"object","properties":{"average":{"type":"string","example":"$350,000"},"maximum":{"type":"string","example":"$600,000"},"sweetSpot":{"type":"string","example":"$250,000 - $400,000"}}},"targetProperties":{"type":"object","properties":{"condition":{"type":"string","example":"Distressed or dated properties"},"configuration":{"type":"string","example":"3-4 bed, 2 bath SFR"},"pricePerSqft":{"type":"string","example":"$150-$200/sqft"},"size":{"type":"string","example":"1,200-2,500 sqft"}}}}},"geographicFocus":{"type":"object","properties":{"primaryMarket":{"type":"string","example":"Phoenix-Mesa-Chandler, AZ"},"targetZipCodes":{"type":"array","items":{"type":"string"},"example":["85001","85003","85006"]},"marketCharacteristics":{"type":"object","properties":{"concentration":{"type":"string","example":"High concentration in central Phoenix"},"marketDynamics":{"type":"string","example":"Strong appreciation, low inventory"},"medianIncome":{"type":"string","example":"$55,000"},"propertyAge":{"type":"string","example":"1960-1990 builds"}}}}},"keyCompetitiveAdvantages":{"type":"object","properties":{"capitalStructure":{"type":"string","example":"Primarily cash purchases enabling fast closes"},"dealSourcing":{"type":"string","example":"Strong network of wholesalers and direct-to-seller marketing"},"execution":{"type":"string","example":"Efficient rehab process with established contractor relationships"},"marketKnowledge":{"type":"string","example":"Deep familiarity with target neighborhoods and comps"}}}}}}}}}},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer profile not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/growth":{"get":{"operationId":"sfr_buyer_growth","summary":"Get buyer portfolio growth data","description":"Returns time-series data showing the growth of a specific buyer's portfolio over time","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"responses":{"200":{"description":"Historical time-series portfolio growth data for the buyer","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"year":{"type":"number","example":2023},"propertiesCount":{"type":"number","example":47}}}}}}},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer profile not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/portfolio/{id}":{"get":{"operationId":"BuyerProfilesController_getBuyerPortfolioById","summary":"Get buyer portfolio by ID","description":"Returns detailed portfolio information for a specific portfolio ID","parameters":[{"name":"id","required":true,"in":"path","description":"Portfolio ID","example":12345,"schema":{"type":"number"}}],"responses":{"200":{"description":"Portfolio details including properties, value, and metrics"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Portfolio not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/activity/{id}":{"get":{"operationId":"BuyerProfilesController_getBuyerActivityById","summary":"Get buyer activity by ID","description":"Returns detailed activity information for a specific activity ID","parameters":[{"name":"id","required":true,"in":"path","description":"Activity ID","example":12345,"schema":{"type":"number"}}],"responses":{"200":{"description":"Activity details including transaction information and property details"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Activity not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/portfolio/{name}/llc-properties":{"get":{"operationId":"BuyerProfilesController_getPortfolioLLCPropertiesCountsGet","summary":"Get portfolio LLC properties counts","description":"Returns counts of properties owned by specific LLCs within a buyer's portfolio","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Counts of properties owned by each LLC within the buyer's portfolio"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getPortfolioLLCPropertiesCounts","summary":"[DEPRECATED] Get portfolio LLC properties counts","description":"DEPRECATED: Use GET /buyer-profiles/portfolio/:name/llc-properties instead. This endpoint will be removed on December 31, 2026.\n\nReturns counts of properties owned by specific LLCs within a buyer's portfolio","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfilePortfolioFilterDto"}}}},"responses":{"200":{"description":"Counts of properties owned by each LLC within the buyer's portfolio"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/activity/{name}/llc-properties":{"get":{"operationId":"BuyerProfilesController_getActivityLLCPropertiesCountsGet","summary":"Get activity LLC properties counts","description":"Returns counts of transactions by specific LLCs within a buyer's activity history","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2024-01-01","schema":{"type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2024-12-31","schema":{"type":"string"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Counts of transactions by each LLC within the buyer's activity history"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getActivityLLCPropertiesCounts","summary":"[DEPRECATED] Get activity LLC properties counts","description":"DEPRECATED: Use GET /buyer-profiles/activity/:name/llc-properties instead. This endpoint will be removed on December 31, 2026.\n\nReturns counts of transactions by specific LLCs within a buyer's activity history","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfileActivityFilterDto"}}}},"responses":{"200":{"description":"Counts of transactions by each LLC within the buyer's activity history"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/activity/count":{"get":{"operationId":"BuyerProfilesController_getBuyerActivityCountGet","summary":"Get buyer activity count","description":"Returns the total count of transactions for a specific buyer matching the specified filters","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2024-01-01","schema":{"type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2024-12-31","schema":{"type":"string"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Total count of buyer activity records","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":153}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getBuyerActivityCount","summary":"[DEPRECATED] Get buyer activity count","description":"DEPRECATED: Use GET /buyer-profiles/:name/activity/count instead. This endpoint will be removed on December 31, 2026.\n\nReturns the total count of transactions for a specific buyer matching the specified filters","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfileActivityFilterDto"}}}},"responses":{"200":{"description":"Total count of buyer activity records","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":153}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/activity":{"get":{"operationId":"BuyerProfilesController_getBuyerActivityPageGet","summary":"Get paginated buyer activity","description":"Returns a paginated list of transactions for a specific buyer matching the specified filters","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"sales_date_min","required":false,"in":"query","description":"Minimum sale date (YYYY-MM-DD)","example":"2024-01-01","schema":{"type":"string"}},{"name":"sales_date_max","required":false,"in":"query","description":"Maximum sale date (YYYY-MM-DD)","example":"2024-12-31","schema":{"type":"string"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default: 20, max: 1000)","schema":{"maximum":1000,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending. Options: current_sale_recording_date, current_sale_price, bedrooms, bathrooms","example":"-current_sale_recording_date","schema":{"default":"-current_sale_recording_date","type":"string"}}],"responses":{"200":{"description":"Paginated list of buyer activity records"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/activity/page":{"post":{"operationId":"BuyerProfilesController_getBuyerActivityPage","summary":"[DEPRECATED] Get paginated buyer activity","description":"DEPRECATED: Use GET /buyer-profiles/:name/activity instead. This endpoint will be removed on December 31, 2026.\n\nReturns a paginated list of transactions for a specific buyer matching the specified filters","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfileActivityPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of buyer activity records"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/portfolio/count":{"get":{"operationId":"BuyerProfilesController_getBuyerPortfolioCountGet","summary":"Get buyer portfolio count","description":"Returns the total count of properties in a specific buyer's portfolio matching the specified filters","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Total count of properties in the buyer's portfolio","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":421}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]},"post":{"operationId":"BuyerProfilesController_getBuyerPortfolioCount","summary":"[DEPRECATED] Get buyer portfolio count","description":"DEPRECATED: Use GET /buyer-profiles/:name/portfolio/count instead. This endpoint will be removed on December 31, 2026.\n\nReturns the total count of properties in a specific buyer's portfolio matching the specified filters","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfilePortfolioFilterDto"}}}},"responses":{"200":{"description":"Total count of properties in the buyer's portfolio","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":421}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/portfolio":{"get":{"operationId":"BuyerProfilesController_getBuyerPortfolioPageGet","summary":"Get paginated buyer portfolio","description":"Returns a paginated list of properties in a specific buyer's portfolio matching the specified filters","parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}},{"name":"search_type","required":false,"in":"query","description":"Type of location search. Note: 'place' search type is only available via POST endpoint.","schema":{"enum":["none","state","city","zip","msa"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., CA)","example":"CA","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"LOS ANGELES","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","example":"90210,90211","schema":{"type":"array","items":{"type":"string"}}},{"name":"msa","required":false,"in":"query","description":"MSA name","example":"Los Angeles-Long Beach-Anaheim, CA","schema":{"type":"string"}},{"name":"sales_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"type":"number"}},{"name":"sales_price_max","required":false,"in":"query","description":"Maximum sale price","example":1000000,"schema":{"type":"number"}},{"name":"beds_min","required":false,"in":"query","description":"Minimum bedrooms","example":2,"schema":{"type":"number"}},{"name":"beds_max","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"type":"number"}},{"name":"baths_min","required":false,"in":"query","description":"Minimum bathrooms","example":1,"schema":{"type":"number"}},{"name":"baths_max","required":false,"in":"query","description":"Maximum bathrooms","example":4,"schema":{"type":"number"}},{"name":"llcs","required":false,"in":"query","description":"Comma-separated LLC names to filter by","schema":{"type":"array","items":{"type":"string"}}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (default: 20, max: 1000)","schema":{"maximum":1000,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending. Options: current_sale_recording_date, current_sale_price","example":"-current_sale_recording_date","schema":{"default":"-current_sale_recording_date","type":"string"}}],"responses":{"200":{"description":"Paginated list of properties in the buyer's portfolio"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/buyer-profiles/{name}/portfolio/page":{"post":{"operationId":"BuyerProfilesController_getBuyerPortfolioPage","summary":"[DEPRECATED] Get paginated buyer portfolio","description":"DEPRECATED: Use GET /buyer-profiles/:name/portfolio instead. This endpoint will be removed on December 31, 2026.\n\nReturns a paginated list of properties in a specific buyer's portfolio matching the specified filters","deprecated":true,"parameters":[{"name":"name","required":true,"in":"path","description":"Buyer name (URL-encoded)","example":"BLACKSTONE%20GROUP","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerProfilePortfolioPageFilterDto"}}}},"responses":{"200":{"description":"Paginated list of properties in the buyer's portfolio"},"400":{"description":"Invalid request parameters"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Buyer not found"}},"tags":["buyer-profiles"],"security":[{"api-key":[]}]}},"/rental-analytics":{"get":{"operationId":"RentalAnalyticsController_getTransactions","summary":"Get paginated rental transactions","description":"Returns a paginated list of rental transactions with detailed property, rent, and tenant information based on the specified filters.","parameters":[{"name":"search_type","required":true,"in":"query","description":"Type of location search","example":"state","schema":{"enum":["state","city","zip","county","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (required for state/city search)","example":"CA","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (required for city search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes (required for zip search)","example":"90210,90211","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name (required for county search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name (required for neighborhood search)","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum square footage","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum square footage","example":3000,"schema":{"maximum":100000,"type":"number"}},{"name":"price_min","required":false,"in":"query","description":"Minimum rent price","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Maximum rent price","example":5000,"schema":{"maximum":100000,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Number of bedrooms","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"bathrooms","required":false,"in":"query","description":"Number of bathrooms","example":2,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"building_types","required":false,"in":"query","description":"Comma-separated building types","schema":{"minLength":1,"type":"string"}},{"name":"look_back","required":false,"in":"query","description":"Number of days to look back","example":90,"schema":{"minimum":1,"maximum":365,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page","example":20,"schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending. Options: effective_date, price, livingarea, bedrooms, bathrooms","example":"-effective_date","schema":{"default":"-effective_date","type":"string"}}],"responses":{"200":{"description":"Paginated list of rental transactions with property and rent details"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/count":{"get":{"operationId":"RentalAnalyticsController_getCount","summary":"Get rental transaction count","description":"Returns the total count of rental transactions matching the specified filter criteria.","parameters":[{"name":"search_type","required":true,"in":"query","description":"Type of location search","example":"state","schema":{"enum":["state","city","zip","county","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (required for state/city search)","example":"CA","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (required for city search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes (required for zip search)","example":"90210,90211","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name (required for county search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name (required for neighborhood search)","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum square footage","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum square footage","example":3000,"schema":{"maximum":100000,"type":"number"}},{"name":"price_min","required":false,"in":"query","description":"Minimum rent price","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Maximum rent price","example":5000,"schema":{"maximum":100000,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Number of bedrooms","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"bathrooms","required":false,"in":"query","description":"Number of bathrooms","example":2,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"building_types","required":false,"in":"query","description":"Comma-separated building types","schema":{"minLength":1,"type":"string"}},{"name":"look_back","required":false,"in":"query","description":"Number of days to look back","example":90,"schema":{"minimum":1,"maximum":365,"type":"number"}}],"responses":{"200":{"description":"Total count of rental transactions"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"RentalAnalyticsController_getTransactionsCount","summary":"[DEPRECATED] Get rental transaction count","description":"DEPRECATED: Use GET /rental-analytics/count instead. Returns the total count of rental transactions matching the specified filter criteria.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalAnalyticsFilterDto"},"examples":{"byState":{"summary":"Count by state","value":{"search":{"type":"state","state":"CA"}}},"byCity":{"summary":"Count by city","value":{"search":{"type":"city","city":"LOS ANGELES","state":"CA"}}}}}}},"responses":{"200":{"description":"Total count of rental transactions"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/stats":{"get":{"operationId":"sfr_rental_stats","summary":"Get rental statistics","description":"Returns aggregate statistics for rental transactions including average rent, rent distribution, occupancy rates, and rental yields.","parameters":[{"name":"search_type","required":true,"in":"query","description":"Type of location search","example":"state","schema":{"enum":["state","city","zip","county","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (required for state/city search)","example":"CA","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (required for city search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes (required for zip search)","example":"90210,90211","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name (required for county search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name (required for neighborhood search)","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum square footage","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum square footage","example":3000,"schema":{"maximum":100000,"type":"number"}},{"name":"price_min","required":false,"in":"query","description":"Minimum rent price","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Maximum rent price","example":5000,"schema":{"maximum":100000,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Number of bedrooms","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"bathrooms","required":false,"in":"query","description":"Number of bathrooms","example":2,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"building_types","required":false,"in":"query","description":"Comma-separated building types","schema":{"minLength":1,"type":"string"}},{"name":"look_back","required":false,"in":"query","description":"Number of days to look back","example":90,"schema":{"minimum":1,"maximum":365,"type":"number"}},{"name":"max_buckets","required":false,"in":"query","description":"Maximum number of histogram buckets","example":10,"schema":{"minimum":1,"maximum":100,"type":"number"}}],"responses":{"200":{"description":"Rental statistics including averages, distributions, and yields","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"object","properties":{"average":{"type":"number","nullable":true,"example":2150},"median":{"type":"number","nullable":true,"example":1950},"p25":{"type":"number","nullable":true,"example":1500},"p75":{"type":"number","nullable":true,"example":2800},"min":{"type":"number","nullable":true,"example":800},"max":{"type":"number","nullable":true,"example":5500}}},"dates":{"type":"object","properties":{"min":{"type":"string","nullable":true,"example":"2022-01-15"},"max":{"type":"string","nullable":true,"example":"2023-06-30"}}},"prices":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number","example":2000},"count":{"type":"number","example":45}}}},"bucketsStep":{"type":"number","example":100}}},"floorplans":{"type":"array","items":{"type":"object","properties":{"bedrooms":{"type":"number","example":3},"bathrooms":{"type":"number","example":2},"average":{"type":"number","nullable":true,"example":3100},"median":{"type":"number","nullable":true,"example":2950},"p25":{"type":"number","nullable":true,"example":2600},"p75":{"type":"number","nullable":true,"example":3400},"min":{"type":"number","nullable":true,"example":2200},"max":{"type":"number","nullable":true,"example":4200},"count":{"type":"number","example":18},"medianSqft":{"type":"number","nullable":true,"example":1420},"medianPricePerSqft":{"type":"number","nullable":true,"example":2.14}}}},"priceVsSqft":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number","example":2500},"sqft":{"type":"number","example":1800},"street":{"type":"string","nullable":true,"example":"123 Main St"},"city":{"type":"string","nullable":true,"example":"Los Angeles"},"state":{"type":"string","nullable":true,"example":"CA"},"zipCode":{"type":"string","nullable":true,"example":"90001"}}}},"homeValueVsSqft":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number","example":780000},"price":{"type":"number","example":2500},"street":{"type":"string","nullable":true,"example":"123 Main St"},"city":{"type":"string","nullable":true,"example":"Los Angeles"},"state":{"type":"string","nullable":true,"example":"CA"},"zipCode":{"type":"string","nullable":true,"example":"90001"}}}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"RentalAnalyticsController_getTransactionsStats","summary":"[DEPRECATED] Get rental statistics","description":"DEPRECATED: Use GET /rental-analytics/stats instead. Returns aggregate statistics for rental transactions including average rent, rent distribution, occupancy rates, and rental yields.","deprecated":true,"parameters":[{"name":"maxBuckets","required":false,"in":"query","description":"Maximum number of histogram buckets for distribution data","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalAnalyticsFilterDto"}}}},"responses":{"200":{"description":"Rental statistics including averages, distributions, and yields"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/ownership":{"get":{"operationId":"RentalAnalyticsController_getOwnership","summary":"Get ownership statistics","description":"Returns statistics about rental property ownership, including owner types, portfolio sizes, and institutional vs individual ownership breakdown.","parameters":[{"name":"search_type","required":true,"in":"query","description":"Type of location search","example":"state","schema":{"enum":["state","city","zip","county","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (required for state/city search)","example":"CA","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (required for city search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes (required for zip search)","example":"90210,90211","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name (required for county search)","example":"LOS ANGELES","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name (required for neighborhood search)","schema":{"minLength":1,"maxLength":255,"type":"string"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum square footage","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum square footage","example":3000,"schema":{"maximum":100000,"type":"number"}},{"name":"price_min","required":false,"in":"query","description":"Minimum rent price","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Maximum rent price","example":5000,"schema":{"maximum":100000,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Number of bedrooms","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"bathrooms","required":false,"in":"query","description":"Number of bathrooms","example":2,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"building_types","required":false,"in":"query","description":"Comma-separated building types","schema":{"minLength":1,"type":"string"}},{"name":"look_back","required":false,"in":"query","description":"Number of days to look back","example":90,"schema":{"minimum":1,"maximum":365,"type":"number"}}],"responses":{"200":{"description":"Ownership statistics including owner type distribution and portfolio analysis"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"RentalAnalyticsController_getTransactionsOwnershipStats","summary":"[DEPRECATED] Get ownership statistics","description":"DEPRECATED: Use GET /rental-analytics/ownership instead. Returns statistics about rental property ownership, including owner types, portfolio sizes, and institutional vs individual ownership breakdown.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalAnalyticsFilterDto"}}}},"responses":{"200":{"description":"Ownership statistics including owner type distribution and portfolio analysis"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/market-analysis":{"get":{"operationId":"sfr_rental_market_analysis","summary":"Get rental market analysis","description":"Returns comprehensive rental market analysis including rent trends, vacancy rates, rent-to-price ratios, and market comparisons.","parameters":[{"name":"geography_type","required":false,"in":"query","description":"Type of geography to analyze","example":"city","schema":{"enum":["city","county","msa","state","zipCode"],"type":"string"}},{"name":"geography_values","required":false,"in":"query","description":"Comma-separated geography values (max 10)","example":"LOS ANGELES,SAN FRANCISCO,SAN DIEGO","schema":{"type":"array","items":{"type":"string"}}},{"name":"state","required":false,"in":"query","description":"Optional 2-letter state code for city geography disambiguation","example":"CA","schema":{"type":"string"}},{"name":"time_range_start","required":false,"in":"query","description":"Start date for analysis (YYYY-MM-DD)","example":"2024-01-01","schema":{"type":"string"}},{"name":"time_range_end","required":false,"in":"query","description":"End date for analysis (YYYY-MM-DD)","example":"2024-12-31","schema":{"type":"string"}},{"name":"property_types","required":false,"in":"query","description":"Comma-separated property types to filter","schema":{"type":"array","items":{"type":"string"}}},{"name":"bedrooms","required":false,"in":"query","description":"Comma-separated bedroom counts (0-10)","example":"2,3,4","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Market analysis data including trends, comparisons, and forecasts","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"geography":{"type":"string","example":"Los Angeles"},"metrics":{"type":"object","properties":{"averageRent":{"type":"number","example":2850},"medianRent":{"type":"number","example":2500},"rentGrowthYoY":{"type":"number","nullable":true,"example":5.2},"totalListings":{"type":"number","example":1250},"averageRentPerSqft":{"type":"number","nullable":true,"example":2.15},"priceDistribution":{"type":"object","properties":{"p10":{"type":"number","nullable":true,"example":1200},"p25":{"type":"number","nullable":true,"example":1800},"p50":{"type":"number","nullable":true,"example":2500},"p75":{"type":"number","nullable":true,"example":3200},"p90":{"type":"number","nullable":true,"example":4500}}}}},"trends":{"type":"object","properties":{"monthly":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2023-06"},"avgRent":{"type":"number","example":2850},"volume":{"type":"number","example":105}}}}}}}}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"RentalAnalyticsController_getMarketAnalysis","summary":"[DEPRECATED] Get rental market analysis","description":"DEPRECATED: Use GET /rental-analytics/market-analysis instead. Returns comprehensive rental market analysis including rent trends, vacancy rates, rent-to-price ratios, and market comparisons.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketAnalysisFilterDto"},"examples":{"byCity":{"summary":"Analyze by city","value":{"geography":{"type":"city","values":["LOS ANGELES"],"state":"CA"}}},"byMultipleCities":{"summary":"Compare multiple cities within one state","value":{"geography":{"type":"city","values":["LOS ANGELES","SAN FRANCISCO","SAN DIEGO"],"state":"CA"}}},"byState":{"summary":"Analyze by state","value":{"geography":{"type":"state","values":["CA"]}}},"byZipCodes":{"summary":"Analyze specific zip codes","value":{"geography":{"type":"zipCode","values":["90210","90211","90212"]}}},"withTimeRange":{"summary":"With time range filter","value":{"geography":{"type":"city","values":["LOS ANGELES"]},"timeRange":{"start":"2024-01-01","end":"2024-12-31"}}}}}}},"responses":{"200":{"description":"Market analysis data including trends, comparisons, and forecasts"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/comparables":{"get":{"operationId":"sfr_rental_comparables","summary":"Get rental comparables","description":"Returns comparable rental properties for a given property or location, useful for rent estimation and market positioning.","parameters":[{"name":"street","required":false,"in":"query","description":"Street address","example":"123 Main St","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City","example":"Los Angeles","schema":{"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code","example":"CA","schema":{"type":"string"}},{"name":"zip_code","required":false,"in":"query","description":"5-digit zip code","example":"90001","schema":{"type":"string"}},{"name":"search_radius","required":false,"in":"query","description":"Search radius in miles","schema":{"minimum":0.1,"maximum":50,"default":1.5,"type":"number"}},{"name":"lookback_months","required":false,"in":"query","description":"Months to look back for comparables","schema":{"minimum":1,"maximum":24,"default":6,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of comparables to return","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Match specific bedroom count","schema":{"minimum":0,"maximum":10,"type":"number"}},{"name":"bathrooms","required":false,"in":"query","description":"Match specific bathroom count","schema":{"minimum":0,"maximum":10,"type":"number"}},{"name":"sqft_min","required":false,"in":"query","description":"Minimum square footage","schema":{"minimum":0,"type":"number"}},{"name":"sqft_max","required":false,"in":"query","description":"Maximum square footage","schema":{"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type to match","schema":{"type":"string"}}],"responses":{"200":{"description":"List of comparable rental properties with rent and property details","content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"object","properties":{"address":{"type":"string","example":"123 Main St, Los Angeles, CA 90001"},"attributes":{"type":"object","properties":{"bedrooms":{"type":"number","nullable":true,"example":3},"bathrooms":{"type":"number","nullable":true,"example":2},"sqft":{"type":"number","nullable":true,"example":1800},"propertyType":{"type":"string","nullable":true,"example":"Single Family Residential"}}}}},"comparables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":12345},"address":{"type":"string","example":"456 Oak Ave, Los Angeles, CA 90001"},"distance":{"type":"number","example":0.8},"rent":{"type":"number","example":2500},"rentPerSqft":{"type":"number","nullable":true,"example":1.39},"effectiveDate":{"type":"string","example":"2023-06-15"},"similarity":{"type":"number","example":0.85},"attributes":{"type":"object","properties":{"bedrooms":{"type":"number","nullable":true,"example":3},"bathrooms":{"type":"number","nullable":true,"example":2},"sqft":{"type":"number","nullable":true,"example":1750},"propertyType":{"type":"string","nullable":true,"example":"Single Family Residential"}}}}}},"analysis":{"type":"object","properties":{"suggestedRentRange":{"type":"object","properties":{"low":{"type":"number","example":2200},"mid":{"type":"number","example":2500},"high":{"type":"number","example":2800}}},"confidenceScore":{"type":"number","example":0.82},"comparableCount":{"type":"number","example":15}}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"RentalAnalyticsController_getRentalComparables","summary":"[DEPRECATED] Get rental comparables","description":"DEPRECATED: Use GET /rental-analytics/comparables instead. Returns comparable rental properties for a given property or location, useful for rent estimation and market positioning.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalComparablesFilterDto"},"examples":{"basic":{"summary":"Find comparables for address","value":{"address":{"street":"123 Main St","city":"Los Angeles","state":"CA","zipCode":"90001"}}},"withRadius":{"summary":"Specify search radius","value":{"address":{"street":"456 Oak Ave","city":"Beverly Hills","state":"CA","zipCode":"90210"},"searchRadius":2.5}},"withAttributes":{"summary":"Match specific attributes","value":{"address":{"street":"789 Palm Dr","city":"San Diego","state":"CA","zipCode":"92101"},"searchRadius":1.5,"attributes":{"bedrooms":3,"bathrooms":2,"sqftRange":{"min":1500,"max":2500}},"lookbackMonths":12,"limit":50}}}}}},"responses":{"200":{"description":"List of comparable rental properties with rent and property details"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/page":{"post":{"operationId":"RentalAnalyticsController_getTransactionsPage","summary":"[DEPRECATED] Get paginated rental transactions","description":"DEPRECATED: Use GET /rental-analytics instead. Returns a paginated list of rental transactions with detailed property, rent, and tenant information based on the specified filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalAnalyticsPageFilterDto"},"examples":{"byState":{"summary":"Search by state","value":{"search":{"type":"state","state":"CA"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"effective_date","direction":"desc"}}},"byCity":{"summary":"Search by city","value":{"search":{"type":"city","city":"LOS ANGELES","state":"CA"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"price","direction":"desc"}}},"byZip":{"summary":"Search by zip codes","value":{"search":{"type":"zip","zips":["90210","90211"]},"pagination":{"page":1,"pageSize":20},"sort":{"field":"effective_date","direction":"desc"}}}}}}},"responses":{"200":{"description":"Paginated list of rental transactions with property and rent details"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/data-summary":{"get":{"operationId":"RentalAnalyticsController_getDataSummary","summary":"Get data summary","description":"Returns a summary of available rental analytics data including coverage areas and date ranges.","parameters":[],"responses":{"200":{"description":"Summary of available rental data"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/rental-analytics/{id}":{"get":{"operationId":"RentalAnalyticsController_getTransaction","summary":"Get rental transaction by ID","description":"Returns detailed information about a specific rental transaction by its unique ID.","parameters":[{"name":"id","required":true,"in":"path","description":"Rental transaction ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Rental transaction details including property and rent information"},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Rental transaction not found"}},"tags":["rental-analytics"],"security":[{"api-key":[]}]}},"/locations":{"get":{"operationId":"LocationsController_getLocations","summary":"Search locations","description":"Search for geographic locations by name for autocomplete functionality. Returns matching cities, zip codes, counties, and MSAs across the United States.","parameters":[{"name":"search","required":true,"in":"query","description":"Search query string","example":"Los Angeles","schema":{"type":"string"}},{"name":"types","required":true,"in":"query","description":"Comma-separated location types to search. Valid values: zip, city, state, msa, county, neighborhood","example":"city,state,zip","schema":{"enum":["zip","city","state","msa","county","neighborhood"],"type":"string"}},{"name":"search_for_msas","required":false,"in":"query","description":"Whether to search for MSAs","example":"false","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"List of matching locations with type and geographic details"},"400":{"description":"Invalid search parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["locations"],"security":[{"api-key":[]}]},"post":{"operationId":"LocationsController_getMatchingLocations","summary":"[DEPRECATED] Search locations","description":"**DEPRECATED: Use GET /locations instead. This endpoint will be removed on December 31, 2026.**\n\nSearch for geographic locations by name for autocomplete functionality. Returns matching cities, zip codes, counties, and MSAs across the United States.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchingLocationsFilterDto"},"examples":{"city":{"summary":"Search for a city","value":{"search":"Los Angeles","types":["city"],"searchForMsas":false}},"zipCode":{"summary":"Search for a zip code","value":{"search":"90210","types":["zip"],"searchForMsas":false}},"msa":{"summary":"Search for MSAs","value":{"search":"Phoenix","types":["msa"],"searchForMsas":true}}}}}},"responses":{"200":{"description":"List of matching locations with type and geographic details"},"400":{"description":"Invalid search parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["locations"],"security":[{"api-key":[]}]}},"/geo-analytics/flips":{"get":{"operationId":"sfr_flip_activity","summary":"Get paginated flip transactions","description":"Returns a paginated list of flip transactions (properties bought and sold) in the specified geographic area with detailed property and transaction information.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Min recording date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Max recording date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_min","required":false,"in":"query","description":"Min sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_max","required":false,"in":"query","description":"Max sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sale_price_max","required":false,"in":"query","description":"Maximum sale price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_name","required":false,"in":"query","description":"Filter by buyer/flipper name","example":"Acme Investments","schema":{"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name","example":"Smith","schema":{"type":"string"}},{"name":"is_interfamily","required":false,"in":"query","description":"Filter for interfamily transfers","example":true,"schema":{"type":"boolean"}},{"name":"is_foreclosure","required":false,"in":"query","description":"Filter for foreclosure sales","example":true,"schema":{"type":"boolean"}},{"name":"is_reo_sale","required":false,"in":"query","description":"Filter for REO sales","example":true,"schema":{"type":"boolean"}},{"name":"is_new_construction","required":false,"in":"query","description":"Filter for new construction","example":true,"schema":{"type":"boolean"}},{"name":"is_resale","required":false,"in":"query","description":"Filter for resales","example":true,"schema":{"type":"boolean"}},{"name":"is_cash_purchase","required":false,"in":"query","description":"Filter for cash purchases","example":true,"schema":{"type":"boolean"}},{"name":"is_private_lender","required":false,"in":"query","description":"Filter for private lender transactions","example":true,"schema":{"type":"boolean"}},{"name":"is_corporate_purchase","required":false,"in":"query","description":"Filter for corporate purchases","example":true,"schema":{"type":"boolean"}},{"name":"page","required":false,"in":"query","description":"Page number","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page","example":20,"schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending (e.g., -recording_date)","example":"-recording_date","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of flip transactions with property details","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":12345},"transactionType":{"type":"string","nullable":true},"recordingDate":{"type":"string","nullable":true,"example":"2023-06-15"},"prevRecordingDate":{"type":"string","nullable":true,"example":"2022-01-10"},"buyerName":{"type":"string","nullable":true,"example":"ACME INVESTMENTS LLC"},"prevBuyer":{"type":"string","nullable":true},"mortgageAmount":{"type":"number","nullable":true,"example":360000},"mortgageLender":{"type":"string","nullable":true},"mortgageLoan":{"type":"string","nullable":true},"isBuyerCorporate":{"type":"boolean","example":true},"buyerOwnershipCode":{"type":"string","nullable":true},"fips":{"type":"string","nullable":true},"msa":{"type":"string","nullable":true,"example":"phoenix-az"},"address":{"type":"string","nullable":true,"example":"123 Main St"},"city":{"type":"string","nullable":true,"example":"Phoenix"},"zipCode":{"type":"string","nullable":true,"example":"85001"},"state":{"type":"string","nullable":true,"example":"AZ"},"buildingArea":{"type":"number","nullable":true,"example":1800},"landUseCode":{"type":"string","nullable":true},"yearBuilt":{"type":"number","nullable":true,"example":1985},"multiApn":{"type":"string","nullable":true},"avmValue":{"type":"number","nullable":true,"example":480000},"saleValue":{"type":"number","nullable":true,"example":450000},"prevSaleValue":{"type":"number","nullable":true,"example":320000},"saleDate":{"type":"string","nullable":true,"example":"2023-06-15"},"prevSaleDate":{"type":"string","nullable":true,"example":"2022-01-10"},"sellerName":{"type":"string","nullable":true,"example":"John Smith"},"sellerCorp":{"type":"boolean","example":false},"mailingZip":{"type":"string","nullable":true},"mortgageTerm":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true,"example":33.4484},"longitude":{"type":"number","nullable":true,"example":-112.074},"documentType":{"type":"string","nullable":true},"isInterfamily":{"type":"boolean","example":false},"isForeclosure":{"type":"boolean","example":false},"isReoSale":{"type":"boolean","example":false},"isNewConstruction":{"type":"boolean","example":false},"isResale":{"type":"boolean","example":true},"lender":{"type":"string","nullable":true},"isCashPurchase":{"type":"boolean","example":true},"isPrivateLender":{"type":"boolean","example":false},"isCorporatePurchase":{"type":"boolean","example":true},"daysDiff":{"type":"number","nullable":true,"example":521},"saleAmountDiff":{"type":"number","nullable":true,"example":130000},"isZeroDollarPurchase":{"type":"boolean","example":false},"flipMortgage":{"type":"string","nullable":true},"buyerNames":{"type":"string","nullable":true},"mailingAddress":{"type":"string","nullable":true},"isBase1YearExitedFlip":{"type":"boolean","example":false},"ownerFullName":{"type":"string","nullable":true},"saleRecordingDate":{"type":"string","nullable":true},"isCorporateOwner":{"type":"boolean","example":false},"isOwnerOccupied":{"type":"boolean","nullable":true},"propertyClass":{"type":"string","nullable":true},"isSameMailingAddress":{"type":"boolean","example":false},"transactionClassify":{"type":"string","nullable":true},"grossMargin":{"type":"number","nullable":true,"example":40.6},"sellerNameFormatted":{"type":"string","nullable":true,"example":"John Smith"},"sellerHasProfilePage":{"type":"boolean","example":true}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/page":{"post":{"operationId":"GeoAnalyticsController_getFlipsPage","summary":"[DEPRECATED] Get paginated flip transactions","description":"**DEPRECATED: Use GET /geo-analytics/flips instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of flip transactions (properties bought and sold) in the specified geographic area with detailed property and transaction information.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAnalyticsPageFilterDto"},"examples":{"byState":{"summary":"Search by state","value":{"search":{"type":"state","state":"AZ"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"recording_date","direction":"desc"}}},"byCity":{"summary":"Search by city","value":{"search":{"type":"city","city":"PHOENIX","state":"AZ"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"sale_amt","direction":"desc"}}},"withFilters":{"summary":"With price and date filters","value":{"search":{"type":"state","state":"AZ"},"salePrice":{"min":200000,"max":500000},"isCashPurchase":"true","pagination":{"page":1,"pageSize":20},"sort":{"field":"recording_date","direction":"desc"}}}}}}},"responses":{"200":{"description":"Paginated list of flip transactions with property details"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/flips/count":{"get":{"operationId":"GeoAnalyticsController_getFlipsCountGet","summary":"Get flip transaction count","description":"Returns the total count of flip transactions matching the specified filter criteria.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Min recording date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Max recording date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_min","required":false,"in":"query","description":"Min sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_max","required":false,"in":"query","description":"Max sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sale_price_max","required":false,"in":"query","description":"Maximum sale price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_name","required":false,"in":"query","description":"Filter by buyer/flipper name","example":"Acme Investments","schema":{"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name","example":"Smith","schema":{"type":"string"}},{"name":"is_interfamily","required":false,"in":"query","description":"Filter for interfamily transfers","example":true,"schema":{"type":"boolean"}},{"name":"is_foreclosure","required":false,"in":"query","description":"Filter for foreclosure sales","example":true,"schema":{"type":"boolean"}},{"name":"is_reo_sale","required":false,"in":"query","description":"Filter for REO sales","example":true,"schema":{"type":"boolean"}},{"name":"is_new_construction","required":false,"in":"query","description":"Filter for new construction","example":true,"schema":{"type":"boolean"}},{"name":"is_resale","required":false,"in":"query","description":"Filter for resales","example":true,"schema":{"type":"boolean"}},{"name":"is_cash_purchase","required":false,"in":"query","description":"Filter for cash purchases","example":true,"schema":{"type":"boolean"}},{"name":"is_private_lender","required":false,"in":"query","description":"Filter for private lender transactions","example":true,"schema":{"type":"boolean"}},{"name":"is_corporate_purchase","required":false,"in":"query","description":"Filter for corporate purchases","example":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Total count of flip transactions"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/count":{"post":{"operationId":"GeoAnalyticsController_getFlipsCount","summary":"[DEPRECATED] Get flip transaction count","description":"**DEPRECATED: Use GET /geo-analytics/flips/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of flip transactions matching the specified filter criteria.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAnalyticsFilterDto"}}}},"responses":{"200":{"description":"Total count of flip transactions"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/flips/hold-time":{"get":{"operationId":"GeoAnalyticsController_getFlipsHoldTimeGet","summary":"Get flip hold time statistics","description":"Returns analytics about how long properties are held before being flipped, including average, median, and distribution of hold times.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Min recording date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Max recording date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_min","required":false,"in":"query","description":"Min sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_max","required":false,"in":"query","description":"Max sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sale_price_max","required":false,"in":"query","description":"Maximum sale price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_name","required":false,"in":"query","description":"Filter by buyer/flipper name","example":"Acme Investments","schema":{"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name","example":"Smith","schema":{"type":"string"}},{"name":"is_interfamily","required":false,"in":"query","description":"Filter for interfamily transfers","example":true,"schema":{"type":"boolean"}},{"name":"is_foreclosure","required":false,"in":"query","description":"Filter for foreclosure sales","example":true,"schema":{"type":"boolean"}},{"name":"is_reo_sale","required":false,"in":"query","description":"Filter for REO sales","example":true,"schema":{"type":"boolean"}},{"name":"is_new_construction","required":false,"in":"query","description":"Filter for new construction","example":true,"schema":{"type":"boolean"}},{"name":"is_resale","required":false,"in":"query","description":"Filter for resales","example":true,"schema":{"type":"boolean"}},{"name":"is_cash_purchase","required":false,"in":"query","description":"Filter for cash purchases","example":true,"schema":{"type":"boolean"}},{"name":"is_private_lender","required":false,"in":"query","description":"Filter for private lender transactions","example":true,"schema":{"type":"boolean"}},{"name":"is_corporate_purchase","required":false,"in":"query","description":"Filter for corporate purchases","example":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Hold time statistics including average, median, and distribution","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2023-06"},"daysDiff":{"type":"number","example":180}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getFlipsHoldTime","summary":"[DEPRECATED] Get flip hold time statistics","description":"**DEPRECATED: Use GET /geo-analytics/flips/hold-time instead. This endpoint will be removed on December 31, 2026.**\n\nReturns analytics about how long properties are held before being flipped, including average, median, and distribution of hold times.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAnalyticsFilterDto"}}}},"responses":{"200":{"description":"Hold time statistics including average, median, and distribution"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/flips/gross-margin":{"get":{"operationId":"GeoAnalyticsController_getFlipsGrossMarginGet","summary":"Get flip gross margin analytics","description":"Returns gross margin analytics for flipped properties, including average profit margins, ROI distribution, and price appreciation data.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Min recording date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Max recording date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_min","required":false,"in":"query","description":"Min sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_max","required":false,"in":"query","description":"Max sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sale_price_max","required":false,"in":"query","description":"Maximum sale price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_name","required":false,"in":"query","description":"Filter by buyer/flipper name","example":"Acme Investments","schema":{"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name","example":"Smith","schema":{"type":"string"}},{"name":"is_interfamily","required":false,"in":"query","description":"Filter for interfamily transfers","example":true,"schema":{"type":"boolean"}},{"name":"is_foreclosure","required":false,"in":"query","description":"Filter for foreclosure sales","example":true,"schema":{"type":"boolean"}},{"name":"is_reo_sale","required":false,"in":"query","description":"Filter for REO sales","example":true,"schema":{"type":"boolean"}},{"name":"is_new_construction","required":false,"in":"query","description":"Filter for new construction","example":true,"schema":{"type":"boolean"}},{"name":"is_resale","required":false,"in":"query","description":"Filter for resales","example":true,"schema":{"type":"boolean"}},{"name":"is_cash_purchase","required":false,"in":"query","description":"Filter for cash purchases","example":true,"schema":{"type":"boolean"}},{"name":"is_private_lender","required":false,"in":"query","description":"Filter for private lender transactions","example":true,"schema":{"type":"boolean"}},{"name":"is_corporate_purchase","required":false,"in":"query","description":"Filter for corporate purchases","example":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Gross margin statistics including average, median, and distribution","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2023-06"},"grossMargin":{"type":"number","example":45000}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getFlipsGrossMargin","summary":"[DEPRECATED] Get flip gross margin analytics","description":"**DEPRECATED: Use GET /geo-analytics/flips/gross-margin instead. This endpoint will be removed on December 31, 2026.**\n\nReturns gross margin analytics for flipped properties, including average profit margins, ROI distribution, and price appreciation data.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAnalyticsFilterDto"}}}},"responses":{"200":{"description":"Gross margin statistics including average, median, and distribution"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/flips/charts":{"get":{"operationId":"GeoAnalyticsController_getFlipsCharts","summary":"Get combined flip chart data (hold time + gross margin)","description":"Returns both hold time and gross margin analytics in a single response. This is significantly faster than calling `/flips/hold-time` and `/flips/gross-margin` separately because it executes a single database scan instead of two.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"recording_date_min","required":false,"in":"query","description":"Min recording date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"recording_date_max","required":false,"in":"query","description":"Max recording date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_min","required":false,"in":"query","description":"Min sale date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_date_max","required":false,"in":"query","description":"Max sale date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"sale_price_min","required":false,"in":"query","description":"Minimum sale price","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"sale_price_max","required":false,"in":"query","description":"Maximum sale price","example":500000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_min","required":false,"in":"query","description":"Minimum building area (sq ft)","example":1000,"schema":{"minimum":0,"type":"number"}},{"name":"building_area_max","required":false,"in":"query","description":"Maximum building area (sq ft)","example":3000,"schema":{"minimum":0,"type":"number"}},{"name":"buyer_name","required":false,"in":"query","description":"Filter by buyer/flipper name","example":"Acme Investments","schema":{"type":"string"}},{"name":"seller_name","required":false,"in":"query","description":"Filter by seller name","example":"Smith","schema":{"type":"string"}},{"name":"is_interfamily","required":false,"in":"query","description":"Filter for interfamily transfers","example":true,"schema":{"type":"boolean"}},{"name":"is_foreclosure","required":false,"in":"query","description":"Filter for foreclosure sales","example":true,"schema":{"type":"boolean"}},{"name":"is_reo_sale","required":false,"in":"query","description":"Filter for REO sales","example":true,"schema":{"type":"boolean"}},{"name":"is_new_construction","required":false,"in":"query","description":"Filter for new construction","example":true,"schema":{"type":"boolean"}},{"name":"is_resale","required":false,"in":"query","description":"Filter for resales","example":true,"schema":{"type":"boolean"}},{"name":"is_cash_purchase","required":false,"in":"query","description":"Filter for cash purchases","example":true,"schema":{"type":"boolean"}},{"name":"is_private_lender","required":false,"in":"query","description":"Filter for private lender transactions","example":true,"schema":{"type":"boolean"}},{"name":"is_corporate_purchase","required":false,"in":"query","description":"Filter for corporate purchases","example":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Combined chart data with hold time and gross margin per month","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2023-06"},"daysDiff":{"type":"number","nullable":true,"example":180},"grossMargin":{"type":"number","nullable":true,"example":45000}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/seller-names":{"get":{"operationId":"GeoAnalyticsController_getSellerNamesGet","summary":"Search seller names","description":"Returns a list of seller names matching the search query for autocomplete functionality.","parameters":[{"name":"search","required":false,"in":"query","description":"Search query for seller name (partial match)","example":"Blackstone","schema":{}}],"responses":{"200":{"description":"List of matching seller names"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getSellerNames","summary":"[DEPRECATED] Search seller names","description":"**DEPRECATED: Use GET /geo-analytics/seller-names instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a list of seller names matching the search query for autocomplete functionality.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Search query for seller name","example":"Blackstone"}}}}}},"responses":{"200":{"description":"List of matching seller names"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/institutional-ownership/owner-names":{"get":{"operationId":"GeoAnalyticsController_getOwnerNames","summary":"Get institutional owner names","description":"Returns a list of all known institutional property owner names for filtering and selection.","parameters":[],"responses":{"200":{"description":"List of institutional owner names"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/institutional-ownership/largest-owners":{"get":{"operationId":"sfr_institutional_owners","summary":"Get largest institutional owners","description":"Returns a ranked list of the largest institutional property owners based on portfolio size, property count, or total value.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `county`: Search by county (requires `county` and `state` params)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","county","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name","example":"Maricopa","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"fund_name","required":false,"in":"query","description":"Filter by fund/owner name","example":"Blackstone","schema":{"minLength":1,"type":"string"}},{"name":"purchase_date_min","required":false,"in":"query","description":"Min purchase date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"purchase_date_max","required":false,"in":"query","description":"Max purchase date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"purchase_price_min","required":false,"in":"query","description":"Minimum purchase price","schema":{"minimum":0,"type":"number"}},{"name":"purchase_price_max","required":false,"in":"query","description":"Maximum purchase price","schema":{"minimum":0,"type":"number"}},{"name":"avm_value_min","required":false,"in":"query","description":"Minimum AVM value","schema":{"minimum":0,"type":"number"}},{"name":"avm_value_max","required":false,"in":"query","description":"Maximum AVM value","schema":{"minimum":0,"type":"number"}},{"name":"gross_yield_min","required":false,"in":"query","description":"Minimum gross yield (%)","schema":{"minimum":0,"type":"number"}},{"name":"gross_yield_max","required":false,"in":"query","description":"Maximum gross yield (%)","schema":{"minimum":0,"type":"number"}}],"responses":{"200":{"description":"List of largest institutional owners with portfolio metrics","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"fundName":{"type":"string","example":"INVITATION HOMES"},"totalHomes":{"type":"number","example":1250},"formattedFundName":{"type":"string","example":"Invitation Homes"}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getInstLargestOwners","summary":"[DEPRECATED] Get largest institutional owners","description":"**DEPRECATED: Use GET /geo-analytics/institutional-ownership/largest-owners instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a ranked list of the largest institutional property owners based on portfolio size, property count, or total value.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoInstitutionalOwnershipFilterDto"}}}},"responses":{"200":{"description":"List of largest institutional owners with portfolio metrics"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/institutional-ownership/count":{"get":{"operationId":"GeoAnalyticsController_getInstitutionalOwnershipCountGet","summary":"Get institutional ownership count","description":"Returns the total count of institutional ownership records matching the specified filter criteria.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `county`: Search by county (requires `county` and `state` params)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"search_type","required":true,"in":"query","description":"Location search type","example":"state","schema":{"enum":["state","city","zip","msa","county","address","neighborhood"],"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., AZ, CA)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name","example":"Phoenix","schema":{"minLength":1,"type":"string"}},{"name":"county","required":false,"in":"query","description":"County name","example":"Maricopa","schema":{"minLength":1,"type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Neighborhood name","example":"Downtown","schema":{"minLength":1,"type":"string"}},{"name":"msa","required":false,"in":"query","description":"Metropolitan Statistical Area code","example":"phoenix-az","schema":{"minLength":1,"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of 5-digit zip codes","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"latitude","required":false,"in":"query","description":"Latitude for radius search (-90 to 90)","example":33.4484,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"longitude","required":false,"in":"query","description":"Longitude for radius search (-180 to 180)","example":-112.074,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius","required":false,"in":"query","description":"Radius in miles for place search (max 1000)","example":10,"schema":{"minimum":0,"maximum":1000,"exclusiveMinimum":true,"type":"number"}},{"name":"fund_name","required":false,"in":"query","description":"Filter by fund/owner name","example":"Blackstone","schema":{"minLength":1,"type":"string"}},{"name":"purchase_date_min","required":false,"in":"query","description":"Min purchase date (YYYY-MM-DD)","example":"2022-01-01","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"purchase_date_max","required":false,"in":"query","description":"Max purchase date (YYYY-MM-DD)","example":"2022-12-31","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string"}},{"name":"purchase_price_min","required":false,"in":"query","description":"Minimum purchase price","schema":{"minimum":0,"type":"number"}},{"name":"purchase_price_max","required":false,"in":"query","description":"Maximum purchase price","schema":{"minimum":0,"type":"number"}},{"name":"avm_value_min","required":false,"in":"query","description":"Minimum AVM value","schema":{"minimum":0,"type":"number"}},{"name":"avm_value_max","required":false,"in":"query","description":"Maximum AVM value","schema":{"minimum":0,"type":"number"}},{"name":"gross_yield_min","required":false,"in":"query","description":"Minimum gross yield (%)","schema":{"minimum":0,"type":"number"}},{"name":"gross_yield_max","required":false,"in":"query","description":"Maximum gross yield (%)","schema":{"minimum":0,"type":"number"}}],"responses":{"200":{"description":"Total count of institutional ownership records"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getInstitutionalOwnershipCount","summary":"[DEPRECATED] Get institutional ownership count","description":"**DEPRECATED: Use GET /geo-analytics/institutional-ownership/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of institutional ownership records matching the specified filter criteria.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoInstitutionalOwnershipFilterDto"}}}},"responses":{"200":{"description":"Total count of institutional ownership records"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/institutional-ownership":{"get":{"operationId":"GeoAnalyticsController_getInstitutionalOwnershipPageGet","summary":"Get paginated institutional ownership","description":"Returns a paginated list of institutional ownership records with details about property holdings and owner information.\n\n**Location Search Types:**\n- `state`: Search by state (requires `state` param)\n- `city`: Search by city (requires `city` and `state` params)\n- `zip`: Search by zip codes (requires `zips` param, comma-separated)\n- `msa`: Search by MSA (requires `msa` param)\n- `county`: Search by county (requires `county` and `state` params)\n- `address`: Radius search (requires `latitude`, `longitude`, `radius` params)\n- `neighborhood`: Search by neighborhood (requires `neighborhood`, `city`, `state` params)","parameters":[{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending (e.g., -purchase_date)","example":"-purchase_date","schema":{}},{"name":"page_size","required":false,"in":"query","description":"Results per page (max 100)","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"gross_yield_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"gross_yield_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"avm_value_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"avm_value_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"purchase_price_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"purchase_price_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"purchase_date_max","required":false,"in":"query","description":"Max purchase date (YYYY-MM-DD)","schema":{}},{"name":"purchase_date_min","required":false,"in":"query","description":"Min purchase date (YYYY-MM-DD)","schema":{}},{"name":"fund_name","required":false,"in":"query","description":"Filter by fund/owner name","schema":{}},{"name":"neighborhood","required":false,"in":"query","schema":{}},{"name":"radius","required":false,"in":"query","schema":{"type":"number"}},{"name":"longitude","required":false,"in":"query","schema":{"type":"number"}},{"name":"latitude","required":false,"in":"query","schema":{"type":"number"}},{"name":"msa","required":false,"in":"query","description":"MSA code","schema":{}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes","schema":{}},{"name":"county","required":false,"in":"query","description":"County name","schema":{}},{"name":"city","required":false,"in":"query","description":"City name","schema":{}},{"name":"state","required":false,"in":"query","description":"2-letter state code","schema":{}},{"name":"search_type","required":true,"in":"query","schema":{"enum":["state","city","zip","msa","county","address","neighborhood"],"type":"string"}}],"responses":{"200":{"description":"Paginated list of institutional ownership records"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/institutional-ownership/page":{"post":{"operationId":"GeoAnalyticsController_getInstitutionalOwnershipPage","summary":"[DEPRECATED] Get paginated institutional ownership","description":"**DEPRECATED: Use GET /geo-analytics/institutional-ownership instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of institutional ownership records with details about property holdings and owner information.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoInstitutionalOwnershipPageFilterDto"},"examples":{"byState":{"summary":"Search by state","value":{"search":{"type":"state","state":"AZ"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"purchase_date","direction":"desc"}}},"byFundName":{"summary":"Sort by fund name","value":{"search":{"type":"state","state":"CA"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"fund_name","direction":"asc"}}},"byValue":{"summary":"Sort by property value","value":{"search":{"type":"city","city":"PHOENIX","state":"AZ"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"current_avm_value","direction":"desc"}}}}}}},"responses":{"200":{"description":"Paginated list of institutional ownership records"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/zip-finder/count":{"get":{"operationId":"GeoAnalyticsController_getZipFinderCountGet","summary":"Get zip finder count","description":"Returns the total count of zip codes matching the specified investment criteria filters.\n\n**Search Types:**\n- `all`: Search all zip codes\n- `zip`: Filter to specific zip codes (requires `zips` param, comma-separated)","parameters":[{"name":"relative_income_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"relative_income_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"gross_yield_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"gross_yield_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"inst_own_percentage_max","required":false,"in":"query","description":"Max institutional ownership (%)","schema":{"type":"number"}},{"name":"inst_own_percentage_min","required":false,"in":"query","description":"Min institutional ownership (%)","schema":{"type":"number"}},{"name":"median_rent_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"median_rent_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"median_home_value_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"median_home_value_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"median_household_income_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"median_household_income_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"population_density_max","required":false,"in":"query","schema":{"type":"number"}},{"name":"population_density_min","required":false,"in":"query","schema":{"type":"number"}},{"name":"population_max","required":false,"in":"query","description":"Maximum population","schema":{"type":"number"}},{"name":"population_min","required":false,"in":"query","description":"Minimum population","schema":{"type":"number"}},{"name":"state","required":false,"in":"query","description":"2-letter state code (e.g., TX, CA). Case-insensitive.","schema":{"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated zip codes (required when search_type=zip)","schema":{}},{"name":"search_type","required":false,"in":"query","description":"Search type (default: all)","schema":{"enum":["all","zip"],"type":"string"}}],"responses":{"200":{"description":"Total count of matching zip codes"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]},"post":{"operationId":"GeoAnalyticsController_getZipFinderCount","summary":"[DEPRECATED] Get zip finder count","description":"**DEPRECATED: Use GET /geo-analytics/zip-finder/count instead. This endpoint will be removed on December 31, 2026.**\n\nReturns the total count of zip codes matching the specified investment criteria filters.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoZipFinderFilterDto"},"examples":{"allZips":{"summary":"Count all zip codes","value":{"search":{"type":"all"}}},"specificZips":{"summary":"Count specific zip codes","value":{"search":{"type":"zip","zips":["85001","85002","85003"]}}},"withFilters":{"summary":"With investment criteria","value":{"search":{"type":"all"},"medianHomeValue":{"min":200000,"max":500000},"grossYield":{"min":5,"max":10}}}}}}},"responses":{"200":{"description":"Total count of matching zip codes"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/zip-finder":{"get":{"operationId":"sfr_zip_finder","summary":"Get paginated zip finder results","description":"Returns a paginated list of zip codes with investment metrics, including transaction volume, price trends, and market activity.\n\n**Search Types:**\n- `all`: Search all zip codes\n- `zip`: Filter to specific zip codes (requires `zips` param, comma-separated)","parameters":[{"name":"search_type","required":false,"in":"query","description":"Search type: \"all\" for all zips, \"zip\" for specific zips","schema":{"default":"all","enum":["all","zip"],"type":"string"}},{"name":"zips","required":false,"in":"query","description":"Comma-separated list of zip codes (required when search_type=zip)","example":"85001,85002","schema":{"minLength":1,"pattern":"^\\d{5}(,\\d{5})*$","type":"string"}},{"name":"state","required":false,"in":"query","description":"Filter by 2-letter state code (e.g., TX, CA). Case-insensitive.","example":"TX","schema":{"pattern":"^[a-zA-Z]{2}$","type":"string"}},{"name":"population_min","required":false,"in":"query","description":"Minimum population","example":10000,"schema":{"minimum":0,"type":"number"}},{"name":"population_max","required":false,"in":"query","description":"Maximum population","example":100000,"schema":{"minimum":0,"type":"number"}},{"name":"population_density_min","required":false,"in":"query","description":"Minimum population density","schema":{"minimum":0,"type":"number"}},{"name":"population_density_max","required":false,"in":"query","description":"Maximum population density","schema":{"minimum":0,"type":"number"}},{"name":"median_household_income_min","required":false,"in":"query","description":"Minimum median household income","schema":{"minimum":0,"type":"number"}},{"name":"median_household_income_max","required":false,"in":"query","description":"Maximum median household income","schema":{"minimum":0,"type":"number"}},{"name":"median_home_value_min","required":false,"in":"query","description":"Minimum median home value","schema":{"minimum":0,"type":"number"}},{"name":"median_home_value_max","required":false,"in":"query","description":"Maximum median home value","schema":{"minimum":0,"type":"number"}},{"name":"median_rent_min","required":false,"in":"query","description":"Minimum median rent","schema":{"minimum":0,"type":"number"}},{"name":"median_rent_max","required":false,"in":"query","description":"Maximum median rent","schema":{"minimum":0,"type":"number"}},{"name":"inst_own_percentage_min","required":false,"in":"query","description":"Minimum institutional ownership (%)","schema":{"minimum":0,"maximum":100,"type":"number"}},{"name":"inst_own_percentage_max","required":false,"in":"query","description":"Maximum institutional ownership (%)","schema":{"minimum":0,"maximum":100,"type":"number"}},{"name":"gross_yield_min","required":false,"in":"query","description":"Minimum gross yield (%)","schema":{"minimum":0,"type":"number"}},{"name":"gross_yield_max","required":false,"in":"query","description":"Maximum gross yield (%)","schema":{"minimum":0,"type":"number"}},{"name":"relative_income_min","required":false,"in":"query","description":"Minimum relative income (vs MSA)","schema":{"type":"number"}},{"name":"relative_income_max","required":false,"in":"query","description":"Maximum relative income (vs MSA)","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","example":1,"schema":{"minimum":1,"default":1,"type":"number"}},{"name":"page_size","required":false,"in":"query","description":"Results per page (max 100)","example":20,"schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Prefix with - for descending (e.g., -population)","example":"-population","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of zip codes with investment metrics","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"zipCode":{"type":"string","example":"85001"},"state":{"type":"string","nullable":true,"example":"AZ"},"population":{"type":"number","nullable":true,"example":45000},"populationDensity":{"type":"number","nullable":true,"example":3200},"medianHouseholdIncome":{"type":"number","nullable":true,"example":65000},"medianHomeValue":{"type":"number","nullable":true,"example":350000},"medianRent":{"type":"number","nullable":true,"example":1800},"instOwnPercentage":{"type":"number","nullable":true,"example":12.5},"grossYield":{"type":"number","nullable":true,"example":6.2},"incomeRelativeToMsa":{"type":"number","nullable":true,"example":1.05}}}}}}},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/zip-finder/page":{"post":{"operationId":"GeoAnalyticsController_getZipFinderPage","summary":"[DEPRECATED] Get paginated zip finder results","description":"**DEPRECATED: Use GET /geo-analytics/zip-finder instead. This endpoint will be removed on December 31, 2026.**\n\nReturns a paginated list of zip codes with investment metrics, including transaction volume, price trends, and market activity.","deprecated":true,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoZipFinderPageFilterDto"},"examples":{"allZips":{"summary":"Get all zip codes sorted by population","value":{"search":{"type":"all"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"population","direction":"desc"}}},"byYield":{"summary":"Sort by gross yield","value":{"search":{"type":"all"},"pagination":{"page":1,"pageSize":20},"sort":{"field":"gross_yield","direction":"desc"}}},"withFilters":{"summary":"With investment criteria","value":{"search":{"type":"all"},"medianHomeValue":{"min":200000,"max":500000},"grossYield":{"min":5,"max":10},"instOwnPercentage":{"min":0,"max":20},"pagination":{"page":1,"pageSize":20},"sort":{"field":"median_home_value","direction":"asc"}}}}}}},"responses":{"200":{"description":"Paginated list of zip codes with investment metrics"},"400":{"description":"Invalid filter parameters"},"401":{"description":"Unauthorized - invalid API key"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/zip-finder/zip/{zipCode}":{"get":{"operationId":"sfr_zip_detail","summary":"Get zip data by zip code","description":"Returns detailed investment metrics and market data for a specific zip code, including demographics, property values, and transaction trends.","parameters":[{"name":"zipCode","required":true,"in":"path","description":"5-digit US zip code","example":"90210","schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed zip code data with investment metrics","content":{"application/json":{"schema":{"type":"object","nullable":true,"properties":{"zipCode":{"type":"string","example":"90210"},"population":{"type":"number","nullable":true,"example":45000},"populationDensity":{"type":"number","nullable":true,"example":3200},"populationGrowthForecast":{"type":"string","nullable":true},"housingUnits":{"type":"string","nullable":true},"medianHouseholdIncome":{"type":"number","nullable":true,"example":65000},"medianHomeValue":{"type":"number","nullable":true,"example":350000},"medianRent":{"type":"number","nullable":true,"example":1800},"instOwnPercentage":{"type":"number","nullable":true,"example":12.5},"grossYield":{"type":"number","nullable":true,"example":6.2},"incomeRelativeToMsa":{"type":"number","nullable":true,"example":1.05}}}}}},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Zip code not found"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/geo-analytics/{id}":{"get":{"operationId":"GeoAnalyticsController_getFlip","summary":"Get flip transaction by ID","description":"Returns detailed information about a specific flip transaction by its unique ID.","parameters":[{"name":"id","required":true,"in":"path","description":"Flip transaction ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Flip transaction details including property info and profit metrics"},"401":{"description":"Unauthorized - invalid API key"},"404":{"description":"Flip transaction not found"}},"tags":["geo-analytics"],"security":[{"api-key":[]}]}},"/property-types":{"get":{"operationId":"PropertyTypesController_getPropertyTypes","summary":"Get available property types","description":"Returns a list of all valid property type values that can be used for filtering in other endpoints like /buyers/activity/page. Property types are ordered by frequency (most common first).","parameters":[],"responses":{"200":{"description":"List of property type strings ordered by frequency","content":{"application/json":{"example":["Single Family Residential","Condo/Townhouse","Multi-Family (2-4 units)","Manufactured/Mobile Home","Vacant Land"]}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["property-types"],"security":[{"api-key":[]}]}},"/zip-profiles/{zipCode}":{"get":{"operationId":"sfr_zip_profile","summary":"Get ZIP code profile","description":"Returns census demographics, housing stock, and geographic metadata for a ZIP code.","parameters":[{"name":"zipCode","required":true,"in":"path","description":"5-digit ZIP code","example":"85004","schema":{"type":"string","pattern":"^\\d{5}$"}}],"responses":{"200":{"description":"ZIP code profile with demographics, housing, and metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZipProfileResponse"}}}},"400":{"description":"Invalid ZIP code format"},"401":{"description":"Unauthorized"},"404":{"description":"ZIP code profile not found"}},"tags":["zip-profiles"],"security":[{"api-key":[]}]}},"/assessor-comps":{"get":{"operationId":"sfr_assessor_sale_comps","summary":"Get pre-computed sale comps for a property","description":"Returns up to 10 pre-computed comparable sales for any SFR property from the assessor comps cache","parameters":[{"name":"property_id","required":false,"in":"query","description":"First American property_id — preferred input","example":12345678,"schema":{"type":"number"}},{"name":"address","required":false,"in":"query","description":"Street address (fallback if no property_id). Requires zip_code.","example":"332 E Windsor Ave","schema":{"type":"string"}},{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code — required when address is provided","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}}],"responses":{"200":{"description":"Sale comps with enrichment. If the property exists but has no cached comps, comps[] is empty and the metadata fields are null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessorCompsResponse"}}}},"400":{"description":"Invalid request — missing property_id and address"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Could not resolve property from address + zip_code"}},"tags":["assessor-comps"],"security":[{"api-key":[]}]}},"/builders/profile":{"get":{"operationId":"sfr_builder_profile","summary":"Get builder profile","description":"Profile a home builder across their entire active footprint: states/cities/ZIPs, total listing count, price range and median, typical bed/bath/sqft, spec vs to-be-built mix, and top subdivisions.","parameters":[{"name":"builder_name","required":true,"in":"query","description":"Builder name (partial match, case-insensitive). E.g. 'Lennar', 'D.R. Horton'","example":"Lennar","schema":{"minLength":1,"type":"string"}},{"name":"state","required":false,"in":"query","description":"2-letter state code to narrow results","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}}],"responses":{"200":{"description":"Builder profile with summary aggregates and breakdowns by state, city, subdivision, NC type, and property type. The matched_names array shows the actual builder name variants found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuilderProfileResponse"}}}},"400":{"description":"Invalid request - builder_name missing or state malformed"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["builders"],"security":[{"api-key":[]}]}},"/hvi-trend/{zipCode}":{"get":{"operationId":"sfr_hvi_trend","summary":"Get HVI/RVI trend for a ZIP code","description":"Returns monthly Blended Home Value Index (HVI) and Blended Rental Value Index (RVI) for a single ZIP code, ordered chronologically.","parameters":[{"name":"zipCode","required":true,"in":"path","description":"5-digit ZIP code","example":"85004","schema":{"type":"string","pattern":"^\\d{5}$"}},{"name":"months","required":false,"in":"query","description":"Months of history to return (1-120)","example":24,"schema":{"minimum":1,"maximum":120,"default":24,"type":"number"}}],"responses":{"200":{"description":"Monthly HVI/RVI series for the ZIP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HviTrendResponse"}}}},"400":{"description":"Invalid ZIP code or months value"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["hvi-trend"],"security":[{"api-key":[]}]}},"/zip-investor-activity/{zipCode}":{"get":{"operationId":"sfr_zip_investor_activity","summary":"Get investor activity for a ZIP code","description":"Returns a comprehensive investor analysis for a single ZIP code","parameters":[{"name":"zipCode","required":true,"in":"path","description":"5-digit ZIP code","example":"85004","schema":{"type":"string","pattern":"^\\d{5}$"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (required — used as a query filter)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"years_back","required":false,"in":"query","description":"Years of transaction history to include (1-20)","example":2,"schema":{"minimum":1,"maximum":20,"default":2,"type":"number"}}],"responses":{"200":{"description":"Investor activity for the ZIP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZipInvestorActivityResponse"}}}},"400":{"description":"Invalid ZIP code, missing state, or invalid years_back"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["zip-investor-activity"],"security":[{"api-key":[]}]}},"/lender-underwrite":{"get":{"operationId":"sfr_lender_underwrite","summary":"Get full lender underwriting package for a property","description":"Returns a comprehensive underwriting package for an investment lender evaluating a bridge or fix-and-flip loan","parameters":[{"name":"property_id","required":false,"in":"query","description":"First American property_id — preferred input (fastest path)","example":12345678,"schema":{"type":"number"}},{"name":"address","required":false,"in":"query","description":"Street address (fallback if no property_id). Requires zip_code.","example":"332 E Windsor Ave","schema":{"type":"string"}},{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code — required when address is provided","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"target_price","required":false,"in":"query","description":"Target price / ARV (USD) for liquidity analysis","example":475000,"schema":{"minimum":0,"type":"number"}}],"responses":{"200":{"description":"Full underwriting package","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LenderUnderwriteResponse"}}}},"400":{"description":"Invalid input or unresolvable property ZIP"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property could not be resolved"}},"tags":["lender-underwrite"],"security":[{"api-key":[]}]}},"/markets/snapshot":{"get":{"operationId":"sfr_market_snapshot","summary":"Get the latest Redfin market snapshot for a ZIP or city","description":"Returns the most recent Redfin market snapshot for a single location plus a 12-month trend when sourced from REDFIN_ZIP_MARKET.","parameters":[{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code (use this OR city)","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (use this OR zip_code)","example":"Austin","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter","example":"Single Family Residential","schema":{"default":"All Residential","enum":["All Residential","Single Family Residential","Condo/Co-op","Townhouse","Multi-Family (2-4 Unit)"],"type":"string"}}],"responses":{"200":{"description":"Latest market snapshot for the requested location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSnapshotResponse"}}}},"400":{"description":"Invalid request — missing zip_code/city or state"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["markets"],"security":[{"api-key":[]}]}},"/markets/trends/{zipCode}":{"get":{"operationId":"sfr_market_trends","summary":"Get Redfin price/DOM/inventory trend for a ZIP","description":"Returns historical Redfin market data for a single ZIP code.","parameters":[{"name":"zipCode","required":true,"in":"path","description":"5-digit ZIP code","example":"85004","schema":{"type":"string","pattern":"^\\d{5}$"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (required — used as a query filter)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"months","required":false,"in":"query","description":"Months of history to return (1-60)","example":12,"schema":{"minimum":1,"maximum":60,"default":12,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter","example":"Single Family Residential","schema":{"default":"All Residential","enum":["All Residential","Single Family Residential","Condo/Co-op","Townhouse","Multi-Family (2-4 Unit)"],"type":"string"}}],"responses":{"200":{"description":"Monthly market series for the ZIP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketTrendsResponse"}}}},"400":{"description":"Invalid ZIP code, missing state, or invalid months"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["markets"],"security":[{"api-key":[]}]}},"/markets/comparison":{"post":{"operationId":"sfr_compare_markets","summary":"Compare 2-4 markets side-by-side","description":"Compares 2-4 ZIP codes or cities side-by-side using the latest Redfin snapshot.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketComparisonRequestDto"},"examples":{"zipsOnly":{"summary":"Compare three ZIPs (single-family)","value":{"locations":[{"zip_code":"85004","state":"AZ"},{"zip_code":"78704","state":"TX"},{"zip_code":"90210","state":"CA"}],"property_type":"Single Family Residential"}},"mixed":{"summary":"Mix of ZIP and city","value":{"locations":[{"zip_code":"85004","state":"AZ"},{"city":"Austin","state":"TX"}]}}}}}},"responses":{"200":{"description":"Comparison results — one entry per requested location, in the same order as the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketComparisonResponse"}}}},"400":{"description":"Invalid request — fewer than 2 or more than 4 locations"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["markets"],"security":[{"api-key":[]}]}},"/markets/zip-rankings":{"get":{"operationId":"sfr_rank_zips","summary":"Rank ZIP codes within a metro area by Redfin sale-market metrics","description":"Ranks ZIP codes inside a metro area.","parameters":[{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"metro","required":true,"in":"query","description":"Metro/MSA name (fuzzy LIKE match against PARENT_METRO_REGION)","example":"Phoenix","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field with optional \"-\" prefix for descending. Fields: median_price, dom, inventory, price_growth, homes_sold, sale_to_list.","example":"-price_growth","schema":{"default":"-price_growth","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max ZIPs to return (1-50)","example":10,"schema":{"minimum":1,"maximum":50,"default":10,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter","example":"Single Family Residential","schema":{"default":"All Residential","enum":["All Residential","Single Family Residential","Condo/Co-op","Townhouse","Multi-Family (2-4 Unit)"],"type":"string"}}],"responses":{"200":{"description":"ZIP rankings sorted by the requested sale-market metric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketZipRankingsResponse"}}}},"400":{"description":"Invalid request — missing state, metro, or sort"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["markets"],"security":[{"api-key":[]}]}},"/new-constructions/nearby":{"get":{"operationId":"sfr_new_construction_nearby","summary":"Find new construction listings near an address or coordinates","description":"Geospatial search across new-construction listings.","parameters":[{"name":"address","required":false,"in":"query","description":"Full property address to resolve to coordinates (alternative to lat/lon)","example":"332 E Windsor Ave, Phoenix, AZ 85004","schema":{"type":"string"}},{"name":"lat","required":false,"in":"query","description":"Latitude of search center (use with lon)","example":33.4632,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"lon","required":false,"in":"query","description":"Longitude of search center (use with lat)","example":-112.0712,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"radius_miles","required":false,"in":"query","description":"Search radius in miles (max 25)","example":5,"schema":{"minimum":0,"maximum":25,"default":5,"type":"number"}},{"name":"min_price","required":false,"in":"query","description":"Minimum listing price (USD)","example":250000,"schema":{"minimum":0,"type":"number"}},{"name":"max_price","required":false,"in":"query","description":"Maximum listing price (USD)","example":750000,"schema":{"minimum":0,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter (e.g. 'singleFamily', 'condo', 'townhome', 'multiFamily', 'manufactured', 'land')","example":"singleFamily","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max results (1-100)","example":25,"schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"Listings within the radius, sorted by distance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewConstructionNearbyResponse"}}}},"400":{"description":"Invalid request — missing address+coords, mismatched lat/lon, or invalid filter ranges"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Could not resolve coordinates from the provided address"}},"tags":["new-constructions"],"security":[{"api-key":[]}]}},"/new-constructions/search":{"get":{"operationId":"sfr_new_construction_search","summary":"Search new construction listings by location, builder, price","description":"Filter new-construction listings by state (required), plus optional city, ZIP, builder, price range, bedrooms, sqft, property type, and listing type.","parameters":[{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name filter (case-insensitive exact match)","example":"Phoenix","schema":{"type":"string"}},{"name":"zip","required":false,"in":"query","description":"5-digit ZIP code filter","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"builder_name","required":false,"in":"query","description":"Builder name filter (partial, case-insensitive)","example":"Lennar","schema":{"type":"string"}},{"name":"min_price","required":false,"in":"query","description":"Minimum listing price (USD)","example":250000,"schema":{"minimum":0,"type":"number"}},{"name":"max_price","required":false,"in":"query","description":"Maximum listing price (USD)","example":750000,"schema":{"minimum":0,"type":"number"}},{"name":"min_beds","required":false,"in":"query","description":"Minimum bedrooms","example":3,"schema":{"minimum":0,"type":"number"}},{"name":"min_sqft","required":false,"in":"query","description":"Minimum square footage","example":1500,"schema":{"minimum":0,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter (e.g. 'singleFamily', 'condo', 'townhome')","example":"singleFamily","schema":{"type":"string"}},{"name":"nc_type","required":false,"in":"query","description":"Listing type: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'","example":"builderSpec","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field with optional \"-\" prefix for descending. Fields: price, price_per_sqft, sqft, days_on_zillow, beds.","example":"-price","schema":{"default":"price","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max results (1-100)","example":25,"schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":"Filtered listings + total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewConstructionSearchResponse"}}}},"400":{"description":"Invalid request — missing state or invalid filter ranges"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["new-constructions"],"security":[{"api-key":[]}]}},"/new-constructions/stats":{"get":{"operationId":"sfr_new_construction_stats","summary":"Get market-level new construction stats","description":"Aggregate stats for new-construction listings.","parameters":[{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name filter (case-insensitive exact match)","example":"Phoenix","schema":{"type":"string"}},{"name":"zip","required":false,"in":"query","description":"5-digit ZIP code filter","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"property_type","required":false,"in":"query","description":"Property type filter (e.g. 'singleFamily', 'condo', 'townhome')","example":"singleFamily","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate stats and breakdowns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewConstructionStatsResponse"}}}},"400":{"description":"Invalid request — missing state or invalid filter values"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["new-constructions"],"security":[{"api-key":[]}]}},"/new-constructions/subdivisions":{"get":{"operationId":"sfr_subdivision_search","summary":"Search new construction subdivisions","description":"Two modes in one endpoint: (1) when ?subdivision is provided, returns a detailed view (top-matching subdivision summary, its top builders, and up to 50 individual listings); (2) when ?subdivision is omitted, returns the top subdivisions by listing count in the requested area. Callers can detect which mode ran by checking whether `detail` or `top_subdivisions` is populated.","parameters":[{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"TX","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"subdivision","required":false,"in":"query","description":"Subdivision/community name (partial, case-insensitive). When provided, returns detailed view; when omitted, returns top subdivisions.","example":"Bridgeland","schema":{"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name filter (case-insensitive exact match)","example":"Cypress","schema":{"type":"string"}},{"name":"zip","required":false,"in":"query","description":"5-digit ZIP code filter","example":"77433","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"min_price","required":false,"in":"query","description":"Minimum listing price (USD)","example":250000,"schema":{"minimum":0,"type":"number"}},{"name":"max_price","required":false,"in":"query","description":"Maximum listing price (USD)","example":750000,"schema":{"minimum":0,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Max subdivisions to return in top-list mode (1-50). Ignored in detail mode.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"Subdivision detail (when name provided) or top subdivisions list (when omitted)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubdivisionSearchResponse"}}}},"400":{"description":"Invalid request — missing state or invalid filter ranges"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["new-constructions"],"security":[{"api-key":[]}]}},"/rent/market":{"get":{"operationId":"sfr_rental_market_sf","summary":"Get rental market stats for a ZIP or city","description":"Returns aggregate rental pricing stats.","parameters":[{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code (use this OR city)","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (use this OR zip_code)","example":"Phoenix","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"bedrooms","required":false,"in":"query","description":"Filter to listings with this exact bedroom count","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Filter by Zillow HOMETYPE (e.g. 'SINGLE_FAMILY', 'CONDO', 'APARTMENT')","example":"SINGLE_FAMILY","schema":{"type":"string"}},{"name":"lookback_months","required":false,"in":"query","description":"Months of history to include (1-60)","example":12,"schema":{"minimum":1,"maximum":60,"default":12,"type":"number"}}],"responses":{"200":{"description":"Aggregate rental market stats and property-type breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalMarketResponse"}}}},"400":{"description":"Invalid request — missing zip_code/city or state"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["rent"],"security":[{"api-key":[]}]}},"/rent/yield":{"get":{"operationId":"sfr_rental_yield","summary":"Get rental yield analysis (market yield + matched-pair acquisition yield)","description":"Two-part yield analysis: (1) market yield — median rent vs current home values, and (2) matched-pair acquisition yield — median rent vs sale price for the same properties. Acquisition stats are only populated when zip_code is provided. Computes market_yield and rent_to_price server-side from the underlying medians.","parameters":[{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code (required for matched-pair acquisition yield)","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (market yield only — no acquisition data)","example":"Phoenix","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"bedrooms","required":false,"in":"query","description":"Filter to listings with this exact bedroom count","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Filter by Zillow HOMETYPE (e.g. 'SINGLE_FAMILY')","example":"SINGLE_FAMILY","schema":{"type":"string"}}],"responses":{"200":{"description":"Rent stats, optional acquisition stats, and computed yield ratios","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalYieldResponse"}}}},"400":{"description":"Invalid request — missing zip_code/city or state"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["rent"],"security":[{"api-key":[]}]}},"/rent/zip-rankings":{"get":{"operationId":"sfr_rank_rental_zips","summary":"Rank ZIP codes within a state by rental metrics","description":"Aggregates rent listings into per-ZIP rows and ranks them by median rent, gross yield, rent/sqft, or listing count.","parameters":[{"name":"state","required":true,"in":"query","description":"2-letter state code (required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"metro","required":false,"in":"query","description":"Metro/MSA name filter (fuzzy LIKE match)","example":"Phoenix","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field with optional \"-\" prefix for descending. Fields: median_rent, gross_yield, rent_per_sqft, total_listings.","example":"-gross_yield","schema":{"default":"-gross_yield","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max ZIPs to return (1-50)","example":15,"schema":{"minimum":1,"maximum":50,"default":15,"type":"number"}},{"name":"bedrooms","required":false,"in":"query","description":"Filter to listings with this exact bedroom count","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Filter by Zillow HOMETYPE","example":"SINGLE_FAMILY","schema":{"type":"string"}},{"name":"min_listings","required":false,"in":"query","description":"Minimum listing count per ZIP for inclusion in the ranking","example":10,"schema":{"minimum":1,"maximum":1000,"default":10,"type":"number"}}],"responses":{"200":{"description":"ZIP rankings sorted by the requested metric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentalZipRankingsResponse"}}}},"400":{"description":"Invalid request — missing state or sort_by"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["rent"],"security":[{"api-key":[]}]}},"/listings/search":{"get":{"operationId":"redfin_search_listings","summary":"Search active Redfin listings","description":"Browse for-sale (or delisted) listings.","parameters":[{"name":"state","required":false,"in":"query","description":"2-letter state code (one of state/city/zip_code is required)","example":"AZ","schema":{"minLength":2,"maxLength":2,"type":"string"}},{"name":"city","required":false,"in":"query","description":"City name (case-insensitive exact match)","example":"Phoenix","schema":{"type":"string"}},{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP code","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"min_price","required":false,"in":"query","description":"Minimum listing price (USD)","example":250000,"schema":{"minimum":0,"type":"number"}},{"name":"max_price","required":false,"in":"query","description":"Maximum listing price (USD)","example":750000,"schema":{"minimum":0,"type":"number"}},{"name":"min_beds","required":false,"in":"query","description":"Minimum bedrooms","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"max_beds","required":false,"in":"query","description":"Maximum bedrooms","example":5,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"min_sqft","required":false,"in":"query","description":"Minimum square footage","example":1500,"schema":{"minimum":0,"type":"number"}},{"name":"max_sqft","required":false,"in":"query","description":"Maximum square footage","example":3500,"schema":{"minimum":0,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Redfin property_type code: '6'=SFH, '3'=Condo, '13'=Townhouse, '4'=Multi-Family, '8'=Land, '10'=Mobile","example":"6","schema":{"type":"string"}},{"name":"max_dom","required":false,"in":"query","description":"Maximum days on market","example":90,"schema":{"minimum":0,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Listing status","example":"active","schema":{"default":"active","enum":["active","delisted"],"type":"string"}},{"name":"sort_by","required":false,"in":"query","description":"Sort field","example":"price","schema":{"default":"price","enum":["price","price_desc","dom","sqft","newest"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max results (1-100)","example":25,"schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset","example":0,"schema":{"minimum":0,"default":0,"type":"number"}}],"responses":{"200":{"description":"Filtered listings + total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearchResponse"}}}},"400":{"description":"Invalid request — missing location filter or invalid range"},"401":{"description":"Unauthorized - invalid or missing API key"}},"tags":["listings"],"security":[{"api-key":[]}]}},"/listings/property-details/{propertyId}":{"get":{"operationId":"redfin_property_detail","summary":"Get full Redfin property detail by property_id","description":"Returns complete details for a single property by property_id. Returns 404 only when ALL three tables miss.","parameters":[{"name":"propertyId","required":true,"in":"path","description":"Property ID from LISTINGS or SOLD_PROPERTIES table","example":12345678,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Property detail with separate listing/sold/detail sections (any of which may be null)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDetailResponse"}}}},"400":{"description":"Invalid propertyId"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Property not found in any of the three tables"}},"tags":["listings"],"security":[{"api-key":[]}]}},"/listings/sold-comps":{"get":{"operationId":"redfin_sold_comps","summary":"Find sold comparable properties near a location","description":"Geospatial sold-comp search across.","parameters":[{"name":"property_id","required":false,"in":"query","description":"Look up this listing as the subject (auto-fills lat/lon/beds/sqft/year)","example":12345678,"schema":{"type":"number"}},{"name":"lat","required":false,"in":"query","description":"Subject property latitude (use with lon)","example":33.4632,"schema":{"minimum":-90,"maximum":90,"type":"number"}},{"name":"lon","required":false,"in":"query","description":"Subject property longitude (use with lat)","example":-112.0712,"schema":{"minimum":-180,"maximum":180,"type":"number"}},{"name":"address","required":false,"in":"query","description":"Address to geocode from listings table","example":"332 E Windsor Ave","schema":{"type":"string"}},{"name":"zip_code","required":false,"in":"query","description":"5-digit ZIP — used with address for geocoding, or alone for ZIP centroid mode","example":"85004","schema":{"pattern":"^\\d{5}$","type":"string"}},{"name":"beds","required":false,"in":"query","description":"Subject beds (auto-filled if property_id provided). Comps filtered ±1 bed.","example":3,"schema":{"minimum":0,"maximum":20,"type":"number"}},{"name":"sqft","required":false,"in":"query","description":"Subject sqft (auto-filled if property_id provided). Comps filtered ±30%.","example":1750,"schema":{"minimum":0,"type":"number"}},{"name":"year_built","required":false,"in":"query","description":"Subject year built. Comps filtered ±15 years.","example":1962,"schema":{"minimum":1700,"maximum":2100,"type":"number"}},{"name":"property_type","required":false,"in":"query","description":"Redfin property_type code: '6'=SFH, '3'=Condo, '13'=Townhouse","example":"6","schema":{"default":"6","type":"string"}},{"name":"radius_miles","required":false,"in":"query","description":"Search radius in miles (max 10)","example":1,"schema":{"minimum":0,"maximum":10,"default":1,"type":"number"}},{"name":"days_back","required":false,"in":"query","description":"Only comps sold within last N days","example":180,"schema":{"minimum":1,"maximum":3650,"default":180,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Max comps to return (1-50)","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"Subject info, search context, summary stats, and ranked comps array (empty when no matches)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoldCompsResponse"}}}},"400":{"description":"Invalid request — missing all locator inputs or mismatched lat/lon"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Could not resolve subject location from the provided inputs"}},"tags":["listings"],"security":[{"api-key":[]}]}}},"info":{"title":"SFR Analytics API","description":"\n## API Overview\nThe SFR Analytics API provides comprehensive data analytics for real estate investors, lenders, and market analysts. Access detailed property information, buyer behavior trends, market analytics, and investment insights.\n\n## Authentication\nAll API requests require authentication using an API key. Include your API key in the X-API-TOKEN header with every request.\n\n```\nX-API-TOKEN: your-api-key\n```\n\n## Rate Limiting\nAPI calls are limited to 200 requests per 60-second window. Rate limit headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`) are included in every response.\n\n## Response Format\nAll API responses are returned in JSON format. Successful responses include data with the requested information, while error responses include details about what went wrong.\n\n## Common Parameters\n- **Pagination**: Many endpoints support pagination via `page` and `page_size` query parameters.\n- **Sorting**: Sort results using the `sort` query parameter. Prefix with `-` for descending (e.g. `sort=-recording_date`).\n- **Filtering**: Apply filters to narrow down results based on specific criteria.\n\n## Migrating from POST to GET\nAll POST endpoints are deprecated. Use the equivalent GET endpoints with query parameters instead. See the [API Guide](/api-guide) for details.\n\n## Comprehensive Guide\nFor a detailed API guide, see the [SFR Analytics API Guide](/api-guide) section.\n\n## Support\nFor technical support or questions about the API, please contact support@sfranalytics.com.\n","version":"1.0","contact":{}},"tags":[{"name":"buyers","description":"Buyer activity and transactions data"},{"name":"buyer-profiles","description":"Detailed buyer portfolio and investment profiles"},{"name":"properties","description":"Property information and search"},{"name":"locations","description":"Location search and geographic data"},{"name":"geo-analytics","description":"Geographic analytics and insights"},{"name":"rental-analytics","description":"Rental market analytics"},{"name":"property-types","description":"Get available property type values for filtering"},{"name":"borrowers","description":"Borrower/mortgage holder search (partner access)"},{"name":"health-check","description":"API health check"},{"name":"new-constructions","description":"New construction listings"},{"name":"zip-profiles","description":"Demographics and metadata for a ZIP code"},{"name":"assessor-comps","description":"Pre-computed sale comparables for properties"},{"name":"builders","description":"Home builder profiles"},{"name":"markets","description":"Market data"},{"name":"hvi-trend","description":"ZIP code trend"},{"name":"zip-investor-activity","description":"Investor activity for a ZIP"},{"name":"lender-underwrite","description":"Full underwriting package for an investment property"},{"name":"rent","description":"Rental information and statistics"},{"name":"listings","description":"Per-property Redfin data"}],"servers":[],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-TOKEN"}},"schemas":{"GetPropertyDto":{"type":"object","properties":{"address":{"type":"string","minLength":1}},"required":["address"]},"GetTransactionsDto":{"type":"object","properties":{"address":{"type":"string","minLength":1}},"required":["address"]},"GetNearbySalesDto":{"type":"object","properties":{"address":{"type":"string","minLength":1},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"],"default":{"page":1,"pageSize":50}}},"required":["address"]},"BatchPropertyLookupDto":{"type":"object","properties":{"addresses":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1}},"include_suggestions":{"type":"boolean","default":false}},"required":["addresses"]},"GetBorrowersByNameDto":{"type":"object","properties":{"buyerBorrowerName":{"type":"string","minLength":3,"maxLength":255},"state":{"type":"string"},"similarityScore":{"type":"number","minimum":0,"exclusiveMinimum":false,"maximum":100,"exclusiveMaximum":false,"default":80},"page":{"type":"number","minimum":1,"exclusiveMinimum":false,"maximum":200,"exclusiveMaximum":false,"default":1},"pageSize":{"type":"number","minimum":200,"maximum":200,"default":200}},"required":["buyerBorrowerName","state"]},"BuyersActivityFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buyerPropertiesCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buyerTransactionsCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buildingSqft":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"propertyTypes":{"type":"array","minItems":1,"items":{"type":"string"},"nullable":true,"default":null},"purchaseType":{"type":"string","enum":["non-discount","discounted","all"],"x-enumNames":["NonDiscount","Discounted","All"],"default":"all"},"buyerType":{"type":"string","enum":["individual","corporate","all"],"x-enumNames":["Individual","Corporate","All"],"default":"all"},"isCashBuyer":{"type":"boolean"},"excludeHomebuilders":{"type":"boolean"},"sellerName":{"type":"string"}},"required":["search"]},"BuyersActivityPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buyerPropertiesCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buyerTransactionsCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"buildingSqft":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"propertyTypes":{"type":"array","minItems":1,"items":{"type":"string"},"nullable":true,"default":null},"purchaseType":{"type":"string","enum":["non-discount","discounted","all"],"x-enumNames":["NonDiscount","Discounted","All"],"default":"all"},"buyerType":{"type":"string","enum":["individual","corporate","all"],"x-enumNames":["Individual","Corporate","All"],"default":"all"},"isCashBuyer":{"type":"boolean"},"excludeHomebuilders":{"type":"boolean"},"sellerName":{"type":"string"},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["recording_date","sale_amt","sale_date","bedrooms","bathrooms","current_avm_value","year_built","sum_building_sqft","city","zip_code","buyer_borrower1_name","buyer_properties_count","buyer_transactions_count"],"x-enumNames":["RecordingDate","SaleValue","SaleDate","Bedrooms","Bathrooms","AvmValue","YearBuilt","BuildingArea","City","ZipCode","BuyerName","BuyerPropertiesCount","BuyerTransactionsCount"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"BuyerTransactionsFilterDto":{"type":"object","properties":{"buyer":{"type":"string","minLength":1,"maxLength":255},"msa":{"type":"string","maxLength":255,"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null}},"required":["buyer"]},"BuyerTransactionsPageFilterDto":{"type":"object","properties":{"buyer":{"type":"string","minLength":1,"maxLength":255},"msa":{"type":"string","maxLength":255,"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["recording_date","sale_amt","sale_date","bedrooms","bathrooms","current_avm_value","year_built","sum_building_sqft","city","zip_code","buyer_borrower1_name","buyer_properties_count","buyer_transactions_count"],"x-enumNames":["RecordingDate","SaleValue","SaleDate","Bedrooms","Bathrooms","AvmValue","YearBuilt","BuildingArea","City","ZipCode","BuyerName","BuyerPropertiesCount","BuyerTransactionsCount"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["buyer","pagination","sort"]},"MarketTransactionsPageFilterDto":{"type":"object","properties":{"msa":{"type":"string","minLength":1,"maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255,"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null},"propertyTypes":{"type":"array","items":{"type":"string"},"nullable":true,"default":null},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["recording_date","sale_amt","sale_date","bedrooms","bathrooms","current_avm_value","year_built","sum_building_sqft","city","zip_code","buyer_borrower1_name","buyer_properties_count","buyer_transactions_count"],"x-enumNames":["RecordingDate","SaleValue","SaleDate","Bedrooms","Bathrooms","AvmValue","YearBuilt","BuildingArea","City","ZipCode","BuyerName","BuyerPropertiesCount","BuyerTransactionsCount"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["msa","pagination","sort"]},"MarketTransactionsFilterDto":{"type":"object","properties":{"msa":{"type":"string","minLength":1,"maxLength":255},"city":{"type":"string","minLength":1,"maxLength":255,"nullable":true,"default":null},"salesDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"],"nullable":true,"default":null},"propertyTypes":{"type":"array","items":{"type":"string"},"nullable":true,"default":null}},"required":["msa"]},"BestBuyersRequestDto":{"type":"object","properties":{"address":{"type":"string","minLength":1}},"required":["address"]},"PortfoliosPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"propertyTypes":{"type":"array","items":{"type":"string"},"default":[]},"averageYearBuilt":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"averageYearsOfOwnership":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"averagePropertyValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"portfolioValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"propertiesCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["properties_count"],"x-enumNames":["PropertiesCount"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"PortfoliosFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"propertyTypes":{"type":"array","items":{"type":"string"},"default":[]},"averageYearBuilt":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"averageYearsOfOwnership":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"averagePropertyValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"portfolioValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"propertiesCount":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null}},"required":["search"]},"BuyerProfilePortfolioFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"llcs":{"type":"array","items":{"type":"string"}}},"required":["search"]},"BuyerProfileActivityFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"llcs":{"type":"array","items":{"type":"string"}},"salesDate":{"type":"object","properties":{"min":{"type":"string","format":"date-time"},"max":{"type":"string","format":"date-time"}},"required":["min","max"],"nullable":true,"default":null}},"required":["search"]},"BuyerProfileActivityPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"llcs":{"type":"array","items":{"type":"string"}},"salesDate":{"type":"object","properties":{"min":{"type":"string","format":"date-time"},"max":{"type":"string","format":"date-time"}},"required":["min","max"],"nullable":true,"default":null},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["current_sale_recording_date","current_sale_price","bedrooms","bathrooms"],"x-enumNames":["RecordingDate","SaleValue","Bedrooms","Bathrooms"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"BuyerProfilePortfolioPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]}]},"salesPrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"beds":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"baths":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"llcs":{"type":"array","items":{"type":"string"}},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["current_sale_recording_date","current_sale_price"],"x-enumNames":["RecordingDate","SaleValue"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"RentalAnalyticsPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]}]},"sqft":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"price":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"bedrooms":{"type":"number","nullable":true,"default":null},"bathrooms":{"type":"number","nullable":true,"default":null},"buildingTypes":{"type":"array","minItems":1,"items":{"type":"string"},"nullable":true,"default":null},"lookBack":{"type":"number","nullable":true,"default":null},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["effective_date","price","livingarea","bedrooms","bathrooms"],"x-enumNames":["EffectiveDate","Price","LivingArea","Bedrooms","Bathrooms"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"RentalAnalyticsFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]}]},"sqft":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"price":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"nullable":true,"default":null},"bedrooms":{"type":"number","nullable":true,"default":null},"bathrooms":{"type":"number","nullable":true,"default":null},"buildingTypes":{"type":"array","minItems":1,"items":{"type":"string"},"nullable":true,"default":null},"lookBack":{"type":"number","nullable":true,"default":null}},"required":["search"]},"MarketAnalysisFilterDto":{"type":"object","properties":{"geography":{"type":"object","properties":{"type":{"type":"string","enum":["city","county","msa","state","zipCode"]},"values":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"state":{"type":"string"}},"required":["type","values"]},"timeRange":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["start","end"]},"propertyType":{"type":"array","items":{"type":"string"}},"bedrooms":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":false,"maximum":10,"exclusiveMaximum":false}}},"required":["geography"]},"RentalComparablesFilterDto":{"type":"object","properties":{"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"}},"required":["street","city","state","zipCode"]},"searchRadius":{"type":"number","minimum":0.1,"exclusiveMinimum":false,"maximum":50,"exclusiveMaximum":false,"default":1.5},"attributes":{"type":"object","properties":{"bedrooms":{"type":"integer","minimum":0,"exclusiveMinimum":false,"maximum":10,"exclusiveMaximum":false},"bathrooms":{"type":"number","minimum":0,"exclusiveMinimum":false,"maximum":10,"exclusiveMaximum":false},"sqftRange":{"type":"object","properties":{"min":{"type":"number","minimum":0,"exclusiveMinimum":false},"max":{"type":"number","minimum":0,"exclusiveMinimum":false}},"required":["min","max"]},"propertyType":{"type":"string"}}},"lookbackMonths":{"type":"integer","minimum":1,"exclusiveMinimum":false,"maximum":24,"exclusiveMaximum":false,"default":6},"limit":{"type":"integer","minimum":1,"exclusiveMinimum":false,"maximum":100,"exclusiveMaximum":false,"default":20}},"required":["address"]},"MatchingLocationsFilterDto":{"type":"object","properties":{"search":{"type":"string","minLength":1},"types":{"type":"array","minItems":1,"maxItems":6,"items":{"type":"string","enum":["zip","city","state","msa","county","neighborhood"],"x-enumNames":["Zip","City","State","Msa","County","Neighborhood"]}},"searchForMsas":{"type":"boolean"}},"required":["search","types","searchForMsas"]},"GeoAnalyticsPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]}]},"recordingDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"salePrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"saleDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"buildingArea":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"buyerName":{"type":"string"},"sellerName":{"type":"string"},"isInterfamily":{"type":"string"},"isForeclosure":{"type":"string"},"isReoSale":{"type":"string"},"isNewConstruction":{"type":"string"},"isResale":{"type":"string"},"isCashPurchase":{"type":"string"},"isPrivateLender":{"type":"string"},"isCorporatePurchase":{"type":"string"},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["recording_date","city","sale_amt","sale_date","current_avm_value","sum_building_sqft","year_built"],"x-enumNames":["RecordingDate","City","SaleValue","SaleDate","Avm","BuildingArea","YearBuilt"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"GeoAnalyticsFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]}]},"recordingDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"salePrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"saleDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"buildingArea":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"buyerName":{"type":"string"},"sellerName":{"type":"string"},"isInterfamily":{"type":"string"},"isForeclosure":{"type":"string"},"isReoSale":{"type":"string"},"isNewConstruction":{"type":"string"},"isResale":{"type":"string"},"isCashPurchase":{"type":"string"},"isPrivateLender":{"type":"string"},"isCorporatePurchase":{"type":"string"}},"required":["search"]},"GeoInstitutionalOwnershipFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]}]},"fundName":{"type":"string"},"purchaseDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"purchasePrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"avmValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"grossYield":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]}},"required":["search"]},"GeoInstitutionalOwnershipPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"radius":{"type":"number"}},"required":["type","latitude","longitude","radius"]},{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["neighborhood"]},"neighborhood":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","neighborhood","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["city"]},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}},"required":["type","city","state"]},{"type":"object","properties":{"type":{"type":"string","enum":["county"]},"county":{"type":"string","minLength":1}},"required":["type","county"]},{"type":"object","properties":{"type":{"type":"string","enum":["msa"]},"msa":{"type":"string","minLength":1}},"required":["type","msa"]},{"type":"object","properties":{"type":{"type":"string","enum":["state"]},"state":{"type":"string","minLength":1}},"required":["type","state"]}]},"fundName":{"type":"string"},"purchaseDate":{"type":"object","properties":{"min":{"type":"string"},"max":{"type":"string"}},"required":["min","max"]},"purchasePrice":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"avmValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"grossYield":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["fund_name","city","neighborhood","purchase_date","purchase_price","current_avm_value","gross_yield"],"x-enumNames":["FundName","City","Neighborhood","PurchaseDate","PurchasePrice","Avm","GrossYield"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"GeoZipFinderFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]}]},"state":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"population":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"populationDensity":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianHouseholdIncome":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianHomeValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianRent":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"instOwnPercentage":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"grossYield":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"relativeIncome":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]}},"required":["search"]},"GeoZipFinderPageFilterDto":{"type":"object","properties":{"search":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["zip"]},"zips":{"type":"array","minItems":1,"items":{"type":"string","minLength":1,"maxLength":255}}},"required":["type","zips"]},{"type":"object","properties":{"type":{"type":"string","enum":["all"]}},"required":["type"]}]},"state":{"type":"string","pattern":"^[a-zA-Z]{2}$"},"population":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"populationDensity":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianHouseholdIncome":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianHomeValue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"medianRent":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"instOwnPercentage":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"grossYield":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"relativeIncome":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"pagination":{"type":"object","properties":{"page":{"type":"number","minimum":1,"exclusiveMinimum":false},"pageSize":{"type":"number","minimum":20,"exclusiveMinimum":false,"maximum":1000,"exclusiveMaximum":false}},"required":["page","pageSize"]},"sort":{"type":"object","properties":{"field":{"type":"string","enum":["zip_code","population","population_density","median_household_income","median_home_value","median_rent","institutional_ownership_percentage","gross_yield","income_relative_to_msa"],"x-enumNames":["ZipCode","Population","PopulationDensity","MedianHouseholdIncome","MedianHomeValue","MedianRent","InstitutionalOwnership","GrossYield","RelativeIncome"]},"direction":{"type":"string","enum":["asc","desc"],"x-enumNames":["Asc","Desc"]}},"required":["field","direction"]}},"required":["search","pagination","sort"]},"ZipProfileDemographics":{"type":"object","properties":{"ZIP_CODE":{"type":"string","example":"85004"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"TOTAL_POPULATION":{"type":"number","nullable":true,"example":10548},"POPULATION_PER_SQM":{"type":"number","nullable":true,"example":5139.0987},"PCT_MALE":{"type":"number","nullable":true,"example":0.4812},"PCT_FEMALE":{"type":"number","nullable":true,"example":0.5188},"PCT_AGE_UNDER_5":{"type":"number","nullable":true,"example":0.0421},"PCT_AGE_5_TO_9":{"type":"number","nullable":true,"example":0.0498},"PCT_AGE_10_TO_14":{"type":"number","nullable":true,"example":0.0567},"PCT_AGE_15_TO_19":{"type":"number","nullable":true,"example":0.0612},"PCT_AGE_20_TO_24":{"type":"number","nullable":true,"example":0.0489},"PCT_AGE_25_TO_34":{"type":"number","nullable":true,"example":0.1234},"PCT_AGE_35_TO_44":{"type":"number","nullable":true,"example":0.1456},"PCT_AGE_45_TO_54":{"type":"number","nullable":true,"example":0.1389},"PCT_AGE_55_TO_59":{"type":"number","nullable":true,"example":0.0712},"PCT_AGE_60_TO_64":{"type":"number","nullable":true,"example":0.0689},"PCT_AGE_65_TO_74":{"type":"number","nullable":true,"example":0.1023},"PCT_AGE_75_TO_84":{"type":"number","nullable":true,"example":0.0598},"PCT_AGE_OVER_84":{"type":"number","nullable":true,"example":0.0312},"MEDIAN_AGE":{"type":"number","nullable":true,"example":46.2},"PCT_RACE_AFRICAN_AMERICAN":{"type":"number","nullable":true,"example":0.0234},"PCT_RACE_ASIAN":{"type":"number","nullable":true,"example":0.1156},"PCT_RACE_HISPANIC":{"type":"number","nullable":true,"example":0.0567},"PCT_RACE_NATIVE_AMERICAN":{"type":"number","nullable":true,"example":0.0021},"PCT_RACE_PACIFIC_ISLANDER":{"type":"number","nullable":true,"example":0.0008},"PCT_RACE_WHITE":{"type":"number","nullable":true,"example":0.7823},"PCT_RACE_OTHER":{"type":"number","nullable":true,"example":0.0191},"PCT_HS_GRAD":{"type":"number","nullable":true,"example":0.9712},"PCT_ASSOCIATES_DEG":{"type":"number","nullable":true,"example":0.7234},"PCT_BACHELORS_DEG":{"type":"number","nullable":true,"example":0.6489},"PCT_GRADUATE_DEG":{"type":"number","nullable":true,"example":0.3567},"AVG_HH_INCOME":{"type":"number","nullable":true,"example":245678},"MED_HH_INCOME":{"type":"number","nullable":true,"example":156432},"AVG_HH_NET_WORTH":{"type":"number","nullable":true,"example":1842500},"AVG_HH_LENGTH_RES":{"type":"number","nullable":true,"example":12.4},"AVG_HH_SIZE":{"type":"number","nullable":true,"example":2.6},"PCT_HH_SINGLE_PARENT":{"type":"number","nullable":true,"example":0.0823},"PCT_HH_VETERAN":{"type":"number","nullable":true,"example":0.0512},"PCT_HH_CC_USAGE":{"type":"number","nullable":true,"example":0.6734},"PCT_HH_HEAVY_INT":{"type":"number","nullable":true,"example":0.4123},"PCT_HH_HEAVY_RADIO":{"type":"number","nullable":true,"example":0.2845},"PCT_HH_HEAVY_NEWSPAPER":{"type":"number","nullable":true,"example":0.1234},"PCT_HH_HEAVY_TV":{"type":"number","nullable":true,"example":0.3567},"PCT_HH_SOCIAL_FB":{"type":"number","nullable":true,"example":0.5234},"PCT_HH_SOCIAL_IG":{"type":"number","nullable":true,"example":0.3845},"PCT_HH_SOCIAL_LI":{"type":"number","nullable":true,"example":0.4521},"PCT_HH_SOCIAL_PINT":{"type":"number","nullable":true,"example":0.2134},"PCT_HH_SOCIAL_X":{"type":"number","nullable":true,"example":0.1876},"PCT_HH_SOCIAL_YT":{"type":"number","nullable":true,"example":0.4923},"PCT_HH_STREAM_NFLX":{"type":"number","nullable":true,"example":0.6234},"PCT_HH_STREAM_HULU":{"type":"number","nullable":true,"example":0.3456},"PCT_HH_STREAM_PRIME":{"type":"number","nullable":true,"example":0.5678},"PCT_HH_PHONE_ANDROID":{"type":"number","nullable":true,"example":0.3245},"PCT_HH_PHONE_IPHONE":{"type":"number","nullable":true,"example":0.6512},"PCT_HH_POLITICS_DEM":{"type":"number","nullable":true,"example":0.4823},"PCT_HH_POLITICS_REP":{"type":"number","nullable":true,"example":0.2945},"PCT_HH_POLITICS_IND":{"type":"number","nullable":true,"example":0.2232},"PCT_HH_DONOR_ARTS":{"type":"number","nullable":true,"example":0.1845},"PCT_HH_DONOR_EDU":{"type":"number","nullable":true,"example":0.2456},"PCT_HH_DONOR_ENV":{"type":"number","nullable":true,"example":0.1923},"PCT_HH_DONOR_HEALTH":{"type":"number","nullable":true,"example":0.1567},"PCT_HH_DONOR_NPR":{"type":"number","nullable":true,"example":0.1234},"PCT_HH_DONOR_PBS":{"type":"number","nullable":true,"example":0.1456},"PCT_HH_DONOR_POL":{"type":"number","nullable":true,"example":0.0789},"PCT_HH_DONOR_SOC":{"type":"number","nullable":true,"example":0.0623}},"required":["ZIP_CODE","STATE","TOTAL_POPULATION","POPULATION_PER_SQM","PCT_MALE","PCT_FEMALE","PCT_AGE_UNDER_5","PCT_AGE_5_TO_9","PCT_AGE_10_TO_14","PCT_AGE_15_TO_19","PCT_AGE_20_TO_24","PCT_AGE_25_TO_34","PCT_AGE_35_TO_44","PCT_AGE_45_TO_54","PCT_AGE_55_TO_59","PCT_AGE_60_TO_64","PCT_AGE_65_TO_74","PCT_AGE_75_TO_84","PCT_AGE_OVER_84","MEDIAN_AGE","PCT_RACE_AFRICAN_AMERICAN","PCT_RACE_ASIAN","PCT_RACE_HISPANIC","PCT_RACE_NATIVE_AMERICAN","PCT_RACE_PACIFIC_ISLANDER","PCT_RACE_WHITE","PCT_RACE_OTHER","PCT_HS_GRAD","PCT_ASSOCIATES_DEG","PCT_BACHELORS_DEG","PCT_GRADUATE_DEG","AVG_HH_INCOME","MED_HH_INCOME","AVG_HH_NET_WORTH","AVG_HH_LENGTH_RES","AVG_HH_SIZE","PCT_HH_SINGLE_PARENT","PCT_HH_VETERAN","PCT_HH_CC_USAGE","PCT_HH_HEAVY_INT","PCT_HH_HEAVY_RADIO","PCT_HH_HEAVY_NEWSPAPER","PCT_HH_HEAVY_TV","PCT_HH_SOCIAL_FB","PCT_HH_SOCIAL_IG","PCT_HH_SOCIAL_LI","PCT_HH_SOCIAL_PINT","PCT_HH_SOCIAL_X","PCT_HH_SOCIAL_YT","PCT_HH_STREAM_NFLX","PCT_HH_STREAM_HULU","PCT_HH_STREAM_PRIME","PCT_HH_PHONE_ANDROID","PCT_HH_PHONE_IPHONE","PCT_HH_POLITICS_DEM","PCT_HH_POLITICS_REP","PCT_HH_POLITICS_IND","PCT_HH_DONOR_ARTS","PCT_HH_DONOR_EDU","PCT_HH_DONOR_ENV","PCT_HH_DONOR_HEALTH","PCT_HH_DONOR_NPR","PCT_HH_DONOR_PBS","PCT_HH_DONOR_POL","PCT_HH_DONOR_SOC"]},"ZipProfileHousing":{"type":"object","properties":{"ZIP_CODE":{"type":"string","example":"85004"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"TOTAL_HOUSING_UNITS":{"type":"number","nullable":true,"example":23456},"PCT_HOUSING_TO_POPULATION":{"type":"number","nullable":true,"example":0.487},"TOTAL_OCCUPIED_HOUSING":{"type":"number","nullable":true,"example":21893},"PCT_OCC_HOUSING_TO_POPULATION":{"type":"number","nullable":true,"example":0.456},"OCC_HOUSING_PUB_ASSISTANCE":{"type":"number","nullable":true,"example":187},"PCT_OCC_HOUSING_PUB_ASSISTANCE":{"type":"number","nullable":true,"example":0.0085},"TOTAL_OWNER_OCCUPIED_HOUSING":{"type":"number","nullable":true,"example":11234},"PCT_OWNER_OCC":{"type":"number","nullable":true,"example":0.5131},"TOTAL_RENTER_OCCUPIED":{"type":"number","nullable":true,"example":10659},"PCT_RENTER_OCC":{"type":"number","nullable":true,"example":0.4869},"TOTAL_VACANT_HOUSING":{"type":"number","nullable":true,"example":1563},"VACANT_SEASONAL_RECREATIONAL":{"type":"number","nullable":true,"example":412},"PCT_VACANT_SEASONAL_REC":{"type":"number","nullable":true,"example":0.2636},"MEDIAN_REAL_ESTATE_TAX":{"type":"number","nullable":true,"example":8456},"BLENDED_HVI":{"type":"number","nullable":true,"example":687500},"BLENDED_RVI":{"type":"number","nullable":true,"example":2845},"SFH_UNITS":{"type":"number","nullable":true,"example":8234},"SFH_OWNER_OCC":{"type":"number","nullable":true,"example":6712},"SFH_HVI":{"type":"number","nullable":true,"example":745000},"SFH_AVG_BEDS":{"type":"number","nullable":true,"example":3.2},"SFH_AVG_SQFT":{"type":"number","nullable":true,"example":1956},"SFH_AVG_LOT_SIZE":{"type":"number","nullable":true,"example":7234},"SFH_AVG_TAX_AMOUNT":{"type":"number","nullable":true,"example":9234},"SFH_AVG_YEAR_BUILT":{"type":"number","nullable":true,"example":1978},"SFH_AVG_LTV":{"type":"number","nullable":true,"example":0.42},"SFH_PCT_FREE_AND_CLEAR":{"type":"number","nullable":true,"example":0.3245},"SFH_PCT_MTG_1_PRESENT":{"type":"number","nullable":true,"example":0.6755},"SFH_AVG_MTG_1_RATE":{"type":"number","nullable":true,"example":5.23},"SFH_PCT_MTG_2_PRESENT":{"type":"number","nullable":true,"example":0.1145},"SFH_PCT_HOA_PRESENT":{"type":"number","nullable":true,"example":0.2834},"SFH_PCT_POOL_PRESENT":{"type":"number","nullable":true,"example":0.1923},"SFH_PCT_LISTED":{"type":"number","nullable":true,"example":0.0312},"SFH_PCT_PRE_FORECLOSURE":{"type":"number","nullable":true,"example":0.0045},"CONDO_UNITS":{"type":"number","nullable":true,"example":2156},"CONDO_OWNER_OCC":{"type":"number","nullable":true,"example":1234},"CONDO_HVI":{"type":"number","nullable":true,"example":425000},"CONDO_AVG_BEDS":{"type":"number","nullable":true,"example":2.1},"CONDO_AVG_SQFT":{"type":"number","nullable":true,"example":1345},"CONDO_AVG_LOT_SIZE":{"type":"number","nullable":true,"example":0},"CONDO_AVG_TAX_AMOUNT":{"type":"number","nullable":true,"example":5234},"CONDO_AVG_YEAR_BUILT":{"type":"number","nullable":true,"example":2003},"CONDO_AVG_LTV":{"type":"number","nullable":true,"example":0.48},"CONDO_PCT_FREE_AND_CLEAR":{"type":"number","nullable":true,"example":0.2734},"CONDO_PCT_MTG_1_PRESENT":{"type":"number","nullable":true,"example":0.7266},"CONDO_AVG_MTG_1_RATE":{"type":"number","nullable":true,"example":5.45},"CONDO_PCT_MTG_2_PRESENT":{"type":"number","nullable":true,"example":0.0823},"CONDO_PCT_HOA_PRESENT":{"type":"number","nullable":true,"example":0.9456},"CONDO_PCT_POOL_PRESENT":{"type":"number","nullable":true,"example":0.6234},"CONDO_PCT_LISTED":{"type":"number","nullable":true,"example":0.0567},"CONDO_PCT_PRE_FORECLOSURE":{"type":"number","nullable":true,"example":0.0089},"TOWNHOUSE_UNITS":{"type":"number","nullable":true,"example":945},"TOWNHOUSE_OWNER_OCC":{"type":"number","nullable":true,"example":678},"TOWNHOUSE_HVI":{"type":"number","nullable":true,"example":535000},"TOWNHOUSE_AVG_BEDS":{"type":"number","nullable":true,"example":3},"TOWNHOUSE_AVG_SQFT":{"type":"number","nullable":true,"example":1789},"TOWNHOUSE_AVG_LOT_SIZE":{"type":"number","nullable":true,"example":2456},"TOWNHOUSE_AVG_TAX_AMOUNT":{"type":"number","nullable":true,"example":6789},"TOWNHOUSE_AVG_YEAR_BUILT":{"type":"number","nullable":true,"example":1998},"TOWNHOUSE_AVG_LTV":{"type":"number","nullable":true,"example":0.45},"TOWNHOUSE_PCT_FREE_AND_CLEAR":{"type":"number","nullable":true,"example":0.3012},"TOWNHOUSE_PCT_MTG_1_PRESENT":{"type":"number","nullable":true,"example":0.6988},"TOWNHOUSE_AVG_MTG_1_RATE":{"type":"number","nullable":true,"example":5.12},"TOWNHOUSE_PCT_MTG_2_PRESENT":{"type":"number","nullable":true,"example":0.0945},"TOWNHOUSE_PCT_HOA_PRESENT":{"type":"number","nullable":true,"example":0.8723},"TOWNHOUSE_PCT_POOL_PRESENT":{"type":"number","nullable":true,"example":0.0834},"TOWNHOUSE_PCT_LISTED":{"type":"number","nullable":true,"example":0.0423},"TOWNHOUSE_PCT_PRE_FORECLOSURE":{"type":"number","nullable":true,"example":0.0023},"MULTI_FAMILY_UNITS":{"type":"number","nullable":true,"example":8456},"RURAL_RES_UNITS":{"type":"number","nullable":true,"example":234},"DUPLEX_RES_UNITS":{"type":"number","nullable":true,"example":567},"MANUFACTURED_RES_UNITS":{"type":"number","nullable":true,"example":89}},"required":["ZIP_CODE","STATE","TOTAL_HOUSING_UNITS","PCT_HOUSING_TO_POPULATION","TOTAL_OCCUPIED_HOUSING","PCT_OCC_HOUSING_TO_POPULATION","OCC_HOUSING_PUB_ASSISTANCE","PCT_OCC_HOUSING_PUB_ASSISTANCE","TOTAL_OWNER_OCCUPIED_HOUSING","PCT_OWNER_OCC","TOTAL_RENTER_OCCUPIED","PCT_RENTER_OCC","TOTAL_VACANT_HOUSING","VACANT_SEASONAL_RECREATIONAL","PCT_VACANT_SEASONAL_REC","MEDIAN_REAL_ESTATE_TAX","BLENDED_HVI","BLENDED_RVI","SFH_UNITS","SFH_OWNER_OCC","SFH_HVI","SFH_AVG_BEDS","SFH_AVG_SQFT","SFH_AVG_LOT_SIZE","SFH_AVG_TAX_AMOUNT","SFH_AVG_YEAR_BUILT","SFH_AVG_LTV","SFH_PCT_FREE_AND_CLEAR","SFH_PCT_MTG_1_PRESENT","SFH_AVG_MTG_1_RATE","SFH_PCT_MTG_2_PRESENT","SFH_PCT_HOA_PRESENT","SFH_PCT_POOL_PRESENT","SFH_PCT_LISTED","SFH_PCT_PRE_FORECLOSURE","CONDO_UNITS","CONDO_OWNER_OCC","CONDO_HVI","CONDO_AVG_BEDS","CONDO_AVG_SQFT","CONDO_AVG_LOT_SIZE","CONDO_AVG_TAX_AMOUNT","CONDO_AVG_YEAR_BUILT","CONDO_AVG_LTV","CONDO_PCT_FREE_AND_CLEAR","CONDO_PCT_MTG_1_PRESENT","CONDO_AVG_MTG_1_RATE","CONDO_PCT_MTG_2_PRESENT","CONDO_PCT_HOA_PRESENT","CONDO_PCT_POOL_PRESENT","CONDO_PCT_LISTED","CONDO_PCT_PRE_FORECLOSURE","TOWNHOUSE_UNITS","TOWNHOUSE_OWNER_OCC","TOWNHOUSE_HVI","TOWNHOUSE_AVG_BEDS","TOWNHOUSE_AVG_SQFT","TOWNHOUSE_AVG_LOT_SIZE","TOWNHOUSE_AVG_TAX_AMOUNT","TOWNHOUSE_AVG_YEAR_BUILT","TOWNHOUSE_AVG_LTV","TOWNHOUSE_PCT_FREE_AND_CLEAR","TOWNHOUSE_PCT_MTG_1_PRESENT","TOWNHOUSE_AVG_MTG_1_RATE","TOWNHOUSE_PCT_MTG_2_PRESENT","TOWNHOUSE_PCT_HOA_PRESENT","TOWNHOUSE_PCT_POOL_PRESENT","TOWNHOUSE_PCT_LISTED","TOWNHOUSE_PCT_PRE_FORECLOSURE","MULTI_FAMILY_UNITS","RURAL_RES_UNITS","DUPLEX_RES_UNITS","MANUFACTURED_RES_UNITS"]},"ZipProfileMeta":{"type":"object","properties":{"ZIP_CODE":{"type":"string","example":"85004"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"COUNTY":{"type":"string","nullable":true,"example":"MARICOPA COUNTY, ARIZONA"},"CBSA":{"type":"string","nullable":true,"example":"PHOENIX-MESA-CHANDLER, AZ"},"FIPS":{"type":"string","nullable":true,"example":"04013"},"DMA_NAME":{"type":"string","nullable":true,"example":"PHOENIX (PRESCOTT)"},"LAND_SQ_MILES":{"type":"number","nullable":true,"example":2.0525},"LATITUDE":{"type":"number","nullable":true,"example":33.4516094},"LONGITUDE":{"type":"number","nullable":true,"example":-112.0698796}},"required":["ZIP_CODE","CITY","STATE","COUNTY","CBSA","FIPS","DMA_NAME","LAND_SQ_MILES","LATITUDE","LONGITUDE"]},"ZipProfileResponse":{"type":"object","properties":{"zip_code":{"type":"string","example":"85004"},"demographics":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ZipProfileDemographics"}]},"housing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ZipProfileHousing"}]},"meta":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ZipProfileMeta"}]}},"required":["zip_code","demographics","housing","meta"]},"AssessorComp":{"type":"object","properties":{"propertyId":{"type":"number","example":14523891},"address":{"type":"string","nullable":true,"example":"1245 N 7TH AVE, PHOENIX, AZ 85007"},"salePrice":{"type":"number","nullable":true,"example":485000},"sqft":{"type":"number","nullable":true,"example":1842},"distanceMiles":{"type":"number","nullable":true,"example":0.4},"beds":{"type":"number","nullable":true,"example":3},"baths":{"type":"number","nullable":true,"example":2},"yearBuilt":{"type":"number","nullable":true,"example":1956},"saleDate":{"type":"string","nullable":true,"example":"2024-08-15"},"buyerIsCorp":{"type":"boolean","example":false},"sellerIsCorp":{"type":"boolean","example":false},"isCash":{"type":"boolean","nullable":true,"example":false,"description":"true = no first mortgage on the deed; null = deed not joined"},"isHardMoney":{"type":"boolean","example":false,"description":"Sale recorded same day as a private/hard-money loan"},"isFlipExit":{"type":"boolean","example":false,"description":"Sale matched against the flips dataset (MCP_GEO_FLIPS)"},"buyerName":{"type":"string","nullable":true,"example":"SMITH JOHN & MARY"},"sellerName":{"type":"string","nullable":true,"example":"JONES INVESTMENTS LLC"},"lender":{"type":"string","nullable":true,"example":"WELLS FARGO BANK NA"},"mtgAmt":{"type":"number","nullable":true,"example":388000}},"required":["propertyId","address","salePrice","sqft","distanceMiles","beds","baths","yearBuilt","saleDate","buyerIsCorp","sellerIsCorp","isCash","isHardMoney","isFlipExit","buyerName","sellerName","lender","mtgAmt"]},"AssessorCompsResponse":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"address":{"type":"string","nullable":true,"example":"332 E WINDSOR AVE, PHOENIX, AZ 85004"},"beds":{"type":"number","nullable":true,"example":3},"baths":{"type":"number","nullable":true,"example":2},"sqft":{"type":"number","nullable":true,"example":1750},"year_built":{"type":"number","nullable":true,"example":1962},"comp_count":{"type":"number","example":10},"median_comp_price":{"type":"number","nullable":true,"example":472500},"median_ppsf":{"type":"number","nullable":true,"example":268.4},"ppsf_value":{"type":"number","nullable":true,"example":469700},"enhanced_value":{"type":"number","nullable":true,"example":471100,"description":"Average of median_comp_price and ppsf_value, rounded"},"comps":{"type":"array","items":{"$ref":"#/components/schemas/AssessorComp"}}},"required":["property_id","address","beds","baths","sqft","year_built","comp_count","median_comp_price","median_ppsf","ppsf_value","enhanced_value","comps"]},"BuilderProfileSummary":{"type":"object","properties":{"TOTAL":{"type":"number","example":4823},"STATE_COUNT":{"type":"number","nullable":true,"example":28},"CITY_COUNT":{"type":"number","nullable":true,"example":412},"ZIP_COUNT":{"type":"number","nullable":true,"example":689},"MED_PRICE":{"type":"number","nullable":true,"example":425000},"AVG_PRICE":{"type":"number","nullable":true,"example":467823},"MIN_PRICE":{"type":"number","nullable":true,"example":189000},"MAX_PRICE":{"type":"number","nullable":true,"example":1875000},"MED_PPSF":{"type":"number","nullable":true,"example":218},"MED_SQFT":{"type":"number","nullable":true,"example":1956},"MED_BEDS":{"type":"number","nullable":true,"example":4},"MED_BATHS":{"type":"number","nullable":true,"example":2.5},"MED_DOM":{"type":"number","nullable":true,"example":47},"PREMIER_COUNT":{"type":"number","nullable":true,"example":1234,"description":"Number of listings flagged as Premier Builder on Zillow"}},"required":["TOTAL","STATE_COUNT","CITY_COUNT","ZIP_COUNT","MED_PRICE","AVG_PRICE","MIN_PRICE","MAX_PRICE","MED_PPSF","MED_SQFT","MED_BEDS","MED_BATHS","MED_DOM","PREMIER_COUNT"]},"BuilderNameRow":{"type":"object","properties":{"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"CNT":{"type":"number","example":2456}},"required":["BUILDER_NAME","CNT"]},"BuilderStateRow":{"type":"object","properties":{"STATE":{"type":"string","nullable":true,"example":"TX"},"CNT":{"type":"number","example":1245},"MED_PRICE":{"type":"number","nullable":true,"example":389000}},"required":["STATE","CNT","MED_PRICE"]},"BuilderCityRow":{"type":"object","properties":{"CITY":{"type":"string","nullable":true,"example":"HOUSTON"},"STATE":{"type":"string","nullable":true,"example":"TX"},"CNT":{"type":"number","example":234},"MED_PRICE":{"type":"number","nullable":true,"example":365000}},"required":["CITY","STATE","CNT","MED_PRICE"]},"BuilderSubdivisionRow":{"type":"object","properties":{"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"CITY":{"type":"string","nullable":true,"example":"CYPRESS"},"STATE":{"type":"string","nullable":true,"example":"TX"},"CNT":{"type":"number","example":87},"MED_PRICE":{"type":"number","nullable":true,"example":412000}},"required":["SUBDIVISION","CITY","STATE","CNT","MED_PRICE"]},"BuilderNcTypeRow":{"type":"object","properties":{"NC_TYPE":{"type":"string","nullable":true,"example":"builderSpec","description":"Listing source type. Common values: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'"},"CNT":{"type":"number","example":3245}},"required":["NC_TYPE","CNT"]},"BuilderPropertyTypeRow":{"type":"object","properties":{"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"SINGLE_FAMILY"},"CNT":{"type":"number","example":4123},"MED_PRICE":{"type":"number","nullable":true,"example":435000}},"required":["PROPERTY_TYPE","CNT","MED_PRICE"]},"BuilderProfileResponse":{"type":"object","properties":{"builder_name_query":{"type":"string","example":"Lennar","description":"The original (un-normalized) builder name from the request"},"state_filter":{"type":"string","nullable":true,"example":"AZ","description":"2-letter state filter, or null if no state was provided"},"summary":{"description":"Aggregate stats. summary.TOTAL is 0 when no listings matched.","allOf":[{"$ref":"#/components/schemas/BuilderProfileSummary"}]},"matched_names":{"description":"Top 5 actual builder name variants matching the partial search","type":"array","items":{"$ref":"#/components/schemas/BuilderNameRow"}},"states":{"type":"array","items":{"$ref":"#/components/schemas/BuilderStateRow"}},"top_cities":{"type":"array","items":{"$ref":"#/components/schemas/BuilderCityRow"}},"top_subdivisions":{"type":"array","items":{"$ref":"#/components/schemas/BuilderSubdivisionRow"}},"nc_types":{"type":"array","items":{"$ref":"#/components/schemas/BuilderNcTypeRow"}},"property_types":{"type":"array","items":{"$ref":"#/components/schemas/BuilderPropertyTypeRow"}}},"required":["builder_name_query","state_filter","summary","matched_names","states","top_cities","top_subdivisions","nc_types","property_types"]},"HviTrendPoint":{"type":"object","properties":{"ZIP_CODE":{"type":"string","example":"85004","description":"5-digit ZIP code"},"STATE":{"type":"string","nullable":true,"example":"AZ","description":"2-letter state code"},"YM":{"type":"string","example":"2024-08-01","description":"Year-month bucket as ISO date (always the 1st of the month)"},"BLENDED_HVI":{"type":"number","nullable":true,"example":487500,"description":"Blended Home Value Index across SFH/condo/townhouse for this ZIP-month"},"BLENDED_RVI":{"type":"number","nullable":true,"example":2845,"description":"Blended Rental Value Index across all property types for this ZIP-month"}},"required":["ZIP_CODE","STATE","YM","BLENDED_HVI","BLENDED_RVI"]},"HviTrendResponse":{"type":"object","properties":{"zip_code":{"type":"string","example":"85004"},"months":{"type":"number","example":24,"description":"Number of months of history actually returned (may be less than requested if data is sparse)"},"points":{"description":"Monthly HVI/RVI series, ordered chronologically (oldest first). Empty if no data.","type":"array","items":{"$ref":"#/components/schemas/HviTrendPoint"}}},"required":["zip_code","months","points"]},"InvestorTxStats":{"type":"object","properties":{"TOTAL_TX":{"type":"number","example":487,"description":"Total transactions in the window"},"INVESTOR_TX":{"type":"number","example":156,"description":"Subset of TOTAL_TX where TX_CLASSIFY starts with 'Investor'"},"CASH_TX":{"type":"number","example":94,"description":"Cash purchases (no first mortgage)"},"CORP_TX":{"type":"number","example":47,"description":"Purchases by a corporate buyer entity"},"FLIP_TX":{"type":"number","example":23,"description":"Resales recorded within 1 year of purchase (BASE_1YR_EXITED_FLIP)"},"FORECL_TX":{"type":"number","example":8,"description":"Foreclosure transactions"},"REO_TX":{"type":"number","example":5,"description":"REO sales"},"NEWCON_TX":{"type":"number","example":12,"description":"New construction transactions"},"MED_PRICE":{"type":"number","nullable":true,"example":425000,"description":"Median sale price"},"MED_FLIP_PROFIT":{"type":"number","nullable":true,"example":87500,"description":"Median gross margin on flip exits"},"AVG_FLIP_PROFIT":{"type":"number","nullable":true,"example":92340,"description":"Average gross margin on flip exits"},"MED_FLIP_DAYS":{"type":"number","nullable":true,"example":187,"description":"Median hold time in days for flip exits"}},"required":["TOTAL_TX","INVESTOR_TX","CASH_TX","CORP_TX","FLIP_TX","FORECL_TX","REO_TX","NEWCON_TX","MED_PRICE","MED_FLIP_PROFIT","AVG_FLIP_PROFIT","MED_FLIP_DAYS"]},"InvestorClassifyRow":{"type":"object","properties":{"TX_CLASSIFY":{"type":"string","nullable":true,"example":"Investor Cash","description":"TX_CLASSIFY label assigned by the dbt model"},"CNT":{"type":"number","example":87}},"required":["TX_CLASSIFY","CNT"]},"InvestorOwnership":{"type":"object","properties":{"TOTAL_SFR":{"type":"number","example":5234,"description":"Total single-family residences in the ZIP"},"OWNER_OCC":{"type":"number","example":3456,"description":"Owner-occupied per the assessor flag"},"TRUE_CORP":{"type":"number","example":423,"description":"Non-occupied with corporate name pattern (LLC/Inc/Corp/LP/etc.) and not also matching trust pattern"},"TRUST_HELD":{"type":"number","example":187,"description":"Non-occupied matching trust patterns (TRUST/TRUSTEE/REVOCABLE/etc.) without corp keywords"},"INDIV_INVESTOR":{"type":"number","example":945,"description":"Non-occupied without any corporate flag (treated as individual investors)"},"OTHER_ENTITY":{"type":"number","example":23,"description":"Non-occupied with the assessor corporate flag set but not matching corp/trust name patterns"},"MED_AVM":{"type":"number","nullable":true,"example":487500,"description":"Median current AVM value across all SFRs in the ZIP"}},"required":["TOTAL_SFR","OWNER_OCC","TRUE_CORP","TRUST_HELD","INDIV_INVESTOR","OTHER_ENTITY","MED_AVM"]},"ZipInvestorActivityResponse":{"type":"object","properties":{"zip_code":{"type":"string","example":"85004"},"state":{"type":"string","example":"AZ"},"years_back":{"type":"number","example":2,"description":"Years of transaction history actually applied"},"transactions":{"nullable":true,"description":"Transaction aggregates from MCP_GEO_FLIPS, or null when no transactions matched","allOf":[{"$ref":"#/components/schemas/InvestorTxStats"}]},"classifications":{"description":"Per-classification transaction counts (TX_CLASSIFY breakdown), ordered by count desc. Empty if no transactions.","type":"array","items":{"$ref":"#/components/schemas/InvestorClassifyRow"}},"ownership":{"nullable":true,"description":"SFR ownership snapshot from STG_ASSESSOR, or null when the ZIP has no SFR records","allOf":[{"$ref":"#/components/schemas/InvestorOwnership"}]}},"required":["zip_code","state","years_back","transactions","classifications","ownership"]},"UnderwritePropertyDetails":{"type":"object","properties":{"FULL_STREET_ADDRESS":{"type":"string","nullable":true,"example":"332 E WINDSOR AVE, PHOENIX, AZ 85004"},"ZIP_CODE":{"type":"string","nullable":true,"example":"85004"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"LATITUDE":{"type":"number","nullable":true,"example":33.4632},"LONGITUDE":{"type":"number","nullable":true,"example":-112.0712},"BEDROOMS":{"type":"number","nullable":true,"example":3},"BATHROOMS":{"type":"number","nullable":true,"example":2},"LIVING_AREA_SQFT":{"type":"number","nullable":true,"example":1750},"LOT_SIZE_SQFT":{"type":"number","nullable":true,"example":7234},"YEAR_BUILT":{"type":"number","nullable":true,"example":1962},"BUILDING_CONDITION_CODE":{"type":"string","nullable":true,"example":"AVERAGE","description":"Building condition code from the assessor table"},"CURRENT_AVM_VALUE":{"type":"number","nullable":true,"example":487500},"SCHOOL_DISTRICT_NAME":{"type":"string","nullable":true,"example":"PHOENIX UNION HIGH SCHOOL DIST"}},"required":["FULL_STREET_ADDRESS","ZIP_CODE","STATE","LATITUDE","LONGITUDE","BEDROOMS","BATHROOMS","LIVING_AREA_SQFT","LOT_SIZE_SQFT","YEAR_BUILT","BUILDING_CONDITION_CODE","CURRENT_AVM_VALUE","SCHOOL_DISTRICT_NAME"]},"UnderwriteCompSummary":{"type":"object","properties":{"median_comp_price":{"type":"number","nullable":true,"example":472500},"comp_count":{"type":"number","nullable":true,"example":10},"median_ppsf":{"type":"number","nullable":true,"example":268.4,"description":"Median price-per-sqft computed across the cached comps"},"ppsf_value":{"type":"number","nullable":true,"example":469700,"description":"median_ppsf × subject sqft"},"enhanced_value":{"type":"number","nullable":true,"example":471100,"description":"Average of median_comp_price and ppsf_value, rounded"},"price_range_min":{"type":"number","nullable":true,"example":412000,"description":"Cheapest comp sale price"},"price_range_max":{"type":"number","nullable":true,"example":545000,"description":"Most expensive comp sale price"}},"required":["median_comp_price","comp_count","median_ppsf","ppsf_value","enhanced_value","price_range_min","price_range_max"]},"UnderwriteMarketSnapshot":{"type":"object","properties":{"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_SALE_PRICE_YOY":{"type":"number","nullable":true,"example":0.057},"MEDIAN_PPSF":{"type":"number","nullable":true,"example":268.4},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"AVG_SALE_TO_LIST":{"type":"number","nullable":true,"example":0.987},"SOLD_ABOVE_LIST":{"type":"number","nullable":true,"example":0.234},"MONTHS_OF_SUPPLY":{"type":"number","nullable":true,"example":2.4},"HOMES_SOLD":{"type":"number","nullable":true,"example":187},"INVENTORY":{"type":"number","nullable":true,"example":1245},"PRICE_DROPS":{"type":"number","nullable":true,"example":0.156},"NEW_LISTINGS":{"type":"number","nullable":true,"example":312}},"required":["MEDIAN_SALE_PRICE","MEDIAN_SALE_PRICE_YOY","MEDIAN_PPSF","MEDIAN_DOM","AVG_SALE_TO_LIST","SOLD_ABOVE_LIST","MONTHS_OF_SUPPLY","HOMES_SOLD","INVENTORY","PRICE_DROPS","NEW_LISTINGS"]},"UnderwriteTrendPoint":{"type":"object","properties":{"PERIOD_END":{"type":"string","nullable":true,"example":"2024-08-31","description":"Period end date as ISO string (or Date depending on Snowflake driver coercion)"},"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_PPSF":{"type":"number","nullable":true,"example":268.4},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"AVG_SALE_TO_LIST":{"type":"number","nullable":true,"example":0.987}},"required":["PERIOD_END","MEDIAN_SALE_PRICE","MEDIAN_PPSF","MEDIAN_DOM","AVG_SALE_TO_LIST"]},"UnderwriteFlipRow":{"type":"object","properties":{"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE, PHOENIX, AZ 85007"},"BUY_PRICE":{"type":"number","nullable":true,"example":285000},"BUY_DATE":{"type":"string","nullable":true,"example":"2024-02-15"},"SALE_PRICE":{"type":"number","nullable":true,"example":425000},"SALE_DATE":{"type":"string","nullable":true,"example":"2024-08-15"},"HOLD_DAYS":{"type":"number","nullable":true,"example":182},"MARGIN":{"type":"number","nullable":true,"example":0.491,"description":"GROSS_MARGIN / PREVIOUS_SALE_AMT (decimal)"},"FLIPPER":{"type":"string","nullable":true,"example":"JONES INVESTMENTS LLC"},"BUYER":{"type":"string","nullable":true,"example":"SMITH JOHN & MARY"}},"required":["ADDRESS","BUY_PRICE","BUY_DATE","SALE_PRICE","SALE_DATE","HOLD_DAYS","MARGIN","FLIPPER","BUYER"]},"UnderwritePrivateLoanRow":{"type":"object","properties":{"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE, PHOENIX, AZ 85007"},"SALE_PRICE":{"type":"number","nullable":true,"example":425000},"DATE":{"type":"string","nullable":true,"example":"2024-08-15"},"LENDER":{"type":"string","nullable":true,"example":"KIAVI FUNDING INC"},"LOAN_AMT":{"type":"number","nullable":true,"example":340000},"BORROWER":{"type":"string","nullable":true,"example":"JONES INVESTMENTS LLC"},"LOAN_TYPE":{"type":"string","nullable":true,"example":"BRIDGE"},"LTV":{"type":"number","nullable":true,"example":0.8,"description":"Loan-to-value ratio (LOAN_AMT / SALE_PRICE)"}},"required":["ADDRESS","SALE_PRICE","DATE","LENDER","LOAN_AMT","BORROWER","LOAN_TYPE","LTV"]},"UnderwriteNeighborhood":{"type":"object","properties":{"MED_HH_INCOME":{"type":"number","nullable":true,"example":67727},"AVG_HH_NET_WORTH":{"type":"number","nullable":true,"example":285006},"PCT_BACHELORS_DEG":{"type":"number","nullable":true,"example":0.5668},"MEDIAN_AGE":{"type":"number","nullable":true,"example":27.8},"SFH_HVI":{"type":"number","nullable":true,"example":397866},"PCT_OWNER_OCC":{"type":"number","nullable":true,"example":0.2154},"MEDIAN_REAL_ESTATE_TAX":{"type":"number","nullable":true,"example":2634}},"required":["MED_HH_INCOME","AVG_HH_NET_WORTH","PCT_BACHELORS_DEG","MEDIAN_AGE","SFH_HVI","PCT_OWNER_OCC","MEDIAN_REAL_ESTATE_TAX"]},"UnderwriteLiquidityDistribution":{"type":"object","properties":{"P10":{"type":"number","nullable":true,"example":285000},"P25":{"type":"number","nullable":true,"example":365000},"P50":{"type":"number","nullable":true,"example":432000},"P75":{"type":"number","nullable":true,"example":525000},"P90":{"type":"number","nullable":true,"example":685000}},"required":["P10","P25","P50","P75","P90"]},"UnderwriteLiquidity":{"type":"object","properties":{"target_price":{"type":"number","nullable":true,"example":475000,"description":"The price the liquidity analysis was run against (resolved server-side from input/comps/AVM)"},"SALES_12MO":{"type":"number","nullable":true,"example":23,"description":"Sales within ±10% of target_price in the last 12 months"},"SALES_6MO":{"type":"number","nullable":true,"example":12,"description":"Sales within ±10% of target_price in the last 6 months"},"TOTAL_SALES":{"type":"number","nullable":true,"example":487,"description":"Total ZIP-level resale transactions in the last 12 months (denominator)"},"distribution":{"nullable":true,"description":"P10/P25/P50/P75/P90 of all ZIP sale prices in the last 12 months","allOf":[{"$ref":"#/components/schemas/UnderwriteLiquidityDistribution"}]}},"required":["target_price","SALES_12MO","SALES_6MO","TOTAL_SALES","distribution"]},"LenderUnderwriteResponse":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"zip_code":{"type":"string","example":"85004"},"state":{"type":"string","nullable":true,"example":"AZ"},"property":{"$ref":"#/components/schemas/UnderwritePropertyDetails"},"comps":{"$ref":"#/components/schemas/UnderwriteCompSummary"},"market":{"nullable":true,"description":"Latest Redfin SFR snapshot for the ZIP, or null when no row available","allOf":[{"$ref":"#/components/schemas/UnderwriteMarketSnapshot"}]},"trend":{"description":"12-month price/DOM/sale-to-list trend ordered chronologically. Empty if no data.","type":"array","items":{"$ref":"#/components/schemas/UnderwriteTrendPoint"}},"flips":{"description":"Up to 10 most recent flip exits in the ZIP (last 12 months)","type":"array","items":{"$ref":"#/components/schemas/UnderwriteFlipRow"}},"private_loans":{"description":"Up to 25 most recent private/hard-money loan originations in the ZIP (last 12 months)","type":"array","items":{"$ref":"#/components/schemas/UnderwritePrivateLoanRow"}},"neighborhood":{"nullable":true,"description":"Census + housing demographics for the ZIP","allOf":[{"$ref":"#/components/schemas/UnderwriteNeighborhood"}]},"liquidity":{"nullable":true,"description":"Liquidity analysis at target_price. Null when no target price could be resolved.","allOf":[{"$ref":"#/components/schemas/UnderwriteLiquidity"}]}},"required":["property_id","zip_code","state","property","comps","market","trend","flips","private_loans","neighborhood","liquidity"]},"MarketSnapshotRow":{"type":"object","properties":{"REGION":{"type":"string","example":"85004","description":"The region identifier — ZIP code when sourced from REDFIN_ZIP_MARKET, city name when from REDFIN_NEIGHBORHOOD_MARKET"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"Arizona"},"STATE_CODE":{"type":"string","nullable":true,"example":"AZ"},"PARENT_METRO_REGION":{"type":"string","nullable":true,"example":"Phoenix-Mesa-Chandler, AZ"},"PERIOD_BEGIN":{"type":"string","example":"2024-08-01"},"PERIOD_END":{"type":"string","example":"2024-08-31"},"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_LIST_PRICE":{"type":"number","nullable":true,"example":489000},"MEDIAN_PPSF":{"type":"number","nullable":true,"example":268.4},"MEDIAN_LIST_PPSF":{"type":"number","nullable":true,"example":275.2},"MEDIAN_SALE_PRICE_YOY":{"type":"number","nullable":true,"example":0.057,"description":"Year-over-year change in median sale price (decimal). Raw value — caller may want to sanitize outliers."},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"MEDIAN_DOM_YOY":{"type":"number","nullable":true,"example":-0.123},"INVENTORY":{"type":"number","nullable":true,"example":1245},"MONTHS_OF_SUPPLY":{"type":"number","nullable":true,"example":2.4},"HOMES_SOLD":{"type":"number","nullable":true,"example":187},"NEW_LISTINGS":{"type":"number","nullable":true,"example":312},"AVG_SALE_TO_LIST":{"type":"number","nullable":true,"example":0.987},"SOLD_ABOVE_LIST":{"type":"number","nullable":true,"example":0.234},"PRICE_DROPS":{"type":"number","nullable":true,"example":0.156},"OFF_MARKET_IN_TWO_WEEKS":{"type":"number","nullable":true,"example":0.412,"description":"Share of homes that went off-market within 2 weeks of listing"}},"required":["REGION","CITY","STATE","STATE_CODE","PARENT_METRO_REGION","PERIOD_BEGIN","PERIOD_END","MEDIAN_SALE_PRICE","MEDIAN_LIST_PRICE","MEDIAN_PPSF","MEDIAN_LIST_PPSF","MEDIAN_SALE_PRICE_YOY","MEDIAN_DOM","MEDIAN_DOM_YOY","INVENTORY","MONTHS_OF_SUPPLY","HOMES_SOLD","NEW_LISTINGS","AVG_SALE_TO_LIST","SOLD_ABOVE_LIST","PRICE_DROPS","OFF_MARKET_IN_TWO_WEEKS"]},"MarketSnapshotTrendPoint":{"type":"object","properties":{"PERIOD_END":{"type":"string","example":"2024-08-31"},"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"INVENTORY":{"type":"number","nullable":true,"example":1245}},"required":["PERIOD_END","MEDIAN_SALE_PRICE","MEDIAN_DOM","INVENTORY"]},"MarketSnapshotResponse":{"type":"object","properties":{"source":{"type":"string","enum":["zip","neighborhood"],"example":"zip","description":"Which Redfin table the snapshot was sourced from. ZIP queries hit REDFIN_ZIP_MARKET; city fallbacks hit REDFIN_NEIGHBORHOOD_MARKET."},"property_type":{"type":"string","example":"Single Family Residential","description":"Echo of the property_type filter applied"},"snapshot":{"nullable":true,"description":"Latest snapshot, or null when no row matched the lookup","allOf":[{"$ref":"#/components/schemas/MarketSnapshotRow"}]},"trend":{"description":"12-month trend (oldest first). Only populated when the lookup resolved from REDFIN_ZIP_MARKET — city/neighborhood lookups return an empty array.","type":"array","items":{"$ref":"#/components/schemas/MarketSnapshotTrendPoint"}}},"required":["source","property_type","snapshot","trend"]},"MarketTrendPoint":{"type":"object","properties":{"PERIOD_END":{"type":"string","example":"2024-08-31","description":"Period end date as ISO string (or Date depending on Snowflake driver coercion)"},"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"INVENTORY":{"type":"number","nullable":true,"example":1245}},"required":["PERIOD_END","MEDIAN_SALE_PRICE","MEDIAN_DOM","INVENTORY"]},"MarketTrendsResponse":{"type":"object","properties":{"zip_code":{"type":"string","example":"85004"},"state":{"type":"string","example":"AZ"},"months":{"type":"number","example":12,"description":"Months of history actually applied (may be smaller than the cap if data is sparse)"},"property_type":{"type":"string","example":"Single Family Residential"},"points":{"description":"Monthly market series ordered chronologically (oldest first). Empty if no data.","type":"array","items":{"$ref":"#/components/schemas/MarketTrendPoint"}}},"required":["zip_code","state","months","property_type","points"]},"MarketComparisonRequestDto":{"type":"object","properties":{"locations":{"description":"2-4 locations to compare side-by-side","type":"array","minItems":2,"maxItems":4,"items":{"type":"object","properties":{"zip_code":{"type":"string","pattern":"^\\d{5}$"},"city":{"type":"string","minLength":1},"state":{"type":"string"}},"required":["state"]}},"property_type":{"description":"Property type filter (defaults to \"All Residential\")","type":"string","enum":["All Residential","Single Family Residential","Condo/Co-op","Townhouse","Multi-Family (2-4 Unit)"],"x-enumNames":["ALL_RESIDENTIAL","SINGLE_FAMILY_RESIDENTIAL","CONDO_COOP","TOWNHOUSE","MULTI_FAMILY"],"default":"All Residential"}},"required":["locations"]},"MarketSnapshot":{"type":"object","properties":{"median_sale_price":{"type":"number","nullable":true,"example":425000},"median_ppsf":{"type":"number","nullable":true,"example":268.4,"description":"Median price per square foot"},"median_sale_price_yoy":{"type":"number","nullable":true,"example":0.057,"description":"Year-over-year change in median sale price (decimal, e.g. 0.057 = +5.7%)"},"median_dom":{"type":"number","nullable":true,"example":32,"description":"Median days on market"},"inventory":{"type":"number","nullable":true,"example":1245},"homes_sold":{"type":"number","nullable":true,"example":187},"avg_sale_to_list":{"type":"number","nullable":true,"example":0.987,"description":"Average sale-to-list ratio (decimal, e.g. 0.987 = 98.7% of list price)"},"sold_above_list":{"type":"number","nullable":true,"example":0.234,"description":"Share of homes sold above list price (decimal)"}},"required":["median_sale_price","median_ppsf","median_sale_price_yoy","median_dom","inventory","homes_sold","avg_sale_to_list","sold_above_list"]},"MarketComparisonEntry":{"type":"object","properties":{"label":{"type":"string","example":"85004, AZ","description":"Display label combining the requested region and state"},"zip_code":{"type":"string","nullable":true,"example":"85004","description":"5-digit ZIP code if the lookup was by ZIP, otherwise null"},"city":{"type":"string","nullable":true,"example":null,"description":"City name if the lookup was by city, otherwise null"},"state":{"type":"string","example":"AZ"},"source":{"type":"string","enum":["zip","neighborhood"],"example":"zip","description":"Which Redfin table the row was sourced from"},"data":{"nullable":true,"description":"Latest snapshot for this location, or null when no data is available","allOf":[{"$ref":"#/components/schemas/MarketSnapshot"}]}},"required":["label","zip_code","city","state","source","data"]},"MarketComparisonResponse":{"type":"object","properties":{"property_type":{"type":"string","example":"Single Family Residential","description":"Echo of the property_type filter applied to the lookup"},"results":{"description":"One entry per requested location, in the same order as the request. data: null when no snapshot was found.","type":"array","items":{"$ref":"#/components/schemas/MarketComparisonEntry"}}},"required":["property_type","results"]},"MarketZipRankingRow":{"type":"object","properties":{"REGION":{"type":"string","example":"85004","description":"ZIP code (REGION column)"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"PARENT_METRO_REGION":{"type":"string","nullable":true,"example":"Phoenix-Mesa-Chandler, AZ"},"MEDIAN_SALE_PRICE":{"type":"number","nullable":true,"example":467500},"MEDIAN_DOM":{"type":"number","nullable":true,"example":32},"INVENTORY":{"type":"number","nullable":true,"example":1245},"HOMES_SOLD":{"type":"number","nullable":true,"example":187},"NEW_LISTINGS":{"type":"number","nullable":true,"example":312},"AVG_SALE_TO_LIST":{"type":"number","nullable":true,"example":0.987},"SOLD_ABOVE_LIST":{"type":"number","nullable":true,"example":0.234},"MEDIAN_SALE_PRICE_YOY":{"type":"number","nullable":true,"example":0.057,"description":"Year-over-year change in median sale price (decimal)"},"PRICE_DROPS":{"type":"number","nullable":true,"example":0.156}},"required":["REGION","CITY","PARENT_METRO_REGION","MEDIAN_SALE_PRICE","MEDIAN_DOM","INVENTORY","HOMES_SOLD","NEW_LISTINGS","AVG_SALE_TO_LIST","SOLD_ABOVE_LIST","MEDIAN_SALE_PRICE_YOY","PRICE_DROPS"]},"MarketZipRankingsResponse":{"type":"object","properties":{"state":{"type":"string","example":"AZ"},"metro":{"type":"string","example":"Phoenix","description":"Metro filter applied (fuzzy LIKE match)"},"sort":{"type":"string","description":"Sort field with optional \"-\" prefix for descending. Fields: median_price, dom, inventory, price_growth, homes_sold, sale_to_list.","example":"-price_growth"},"limit":{"type":"number","example":10},"property_type":{"type":"string","example":"Single Family Residential"},"total":{"type":"number","example":10},"zips":{"description":"ZIPs ordered by the requested sort metric. Empty when no ZIPs match the metro+state filter.","type":"array","items":{"$ref":"#/components/schemas/MarketZipRankingRow"}}},"required":["state","metro","sort","limit","property_type","total","zips"]},"NewConstructionNearbyListing":{"type":"object","properties":{"ZPID":{"type":"string","nullable":true,"example":"12345678","description":"Zillow property ID"},"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP":{"type":"string","nullable":true,"example":"85007"},"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"PRICE":{"type":"number","nullable":true,"example":425000},"PRICE_PER_SQFT":{"type":"number","nullable":true,"example":218.4},"BEDS":{"type":"number","nullable":true,"example":4},"BATHS":{"type":"number","nullable":true,"example":2.5},"SQFT":{"type":"number","nullable":true,"example":1956},"LAT":{"type":"number","nullable":true,"example":33.4632},"LON":{"type":"number","nullable":true,"example":-112.0712},"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"singleFamily","description":"Zillow property type. Common values: 'singleFamily', 'condo', 'townhome', 'multiFamily', 'manufactured', 'land'"},"NC_TYPE":{"type":"string","nullable":true,"example":"builderSpec","description":"New-construction listing source type. Common values: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'"},"DAYS_ON_ZILLOW":{"type":"number","nullable":true,"example":47},"ZESTIMATE":{"type":"number","nullable":true,"example":432000},"RENT_ZESTIMATE":{"type":"number","nullable":true,"example":2450},"ZILLOW_URL":{"type":"string","nullable":true,"example":"https://www.zillow.com/homedetails/...","description":"Direct link to the Zillow listing page"},"DIST_MILES":{"type":"number","nullable":true,"example":0.4,"description":"Haversine distance in miles from the search center"}},"required":["ZPID","BUILDER_NAME","ADDRESS","CITY","STATE","ZIP","SUBDIVISION","PRICE","PRICE_PER_SQFT","BEDS","BATHS","SQFT","LAT","LON","PROPERTY_TYPE","NC_TYPE","DAYS_ON_ZILLOW","ZESTIMATE","RENT_ZESTIMATE","ZILLOW_URL","DIST_MILES"]},"NewConstructionNearbyResponse":{"type":"object","properties":{"resolved_lat":{"type":"number","example":33.4632,"description":"Resolved latitude — echo of input lat or value derived from address resolution"},"resolved_lon":{"type":"number","example":-112.0712,"description":"Resolved longitude — echo of input lon or value derived from address resolution"},"radius_miles":{"type":"number","example":5,"description":"Search radius in miles actually applied"},"total":{"type":"number","example":18},"listings":{"description":"Listings ordered by distance ascending. Empty when no listings match the filters.","type":"array","items":{"$ref":"#/components/schemas/NewConstructionNearbyListing"}}},"required":["resolved_lat","resolved_lon","radius_miles","total","listings"]},"NewConstructionSearchListing":{"type":"object","properties":{"ZPID":{"type":"string","nullable":true,"example":"12345678","description":"Zillow property ID"},"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP":{"type":"string","nullable":true,"example":"85007"},"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"PRICE":{"type":"number","nullable":true,"example":425000},"PRICE_PER_SQFT":{"type":"number","nullable":true,"example":218.4},"BEDS":{"type":"number","nullable":true,"example":4},"BATHS":{"type":"number","nullable":true,"example":2.5},"SQFT":{"type":"number","nullable":true,"example":1956},"LAT":{"type":"number","nullable":true,"example":33.4632},"LON":{"type":"number","nullable":true,"example":-112.0712},"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"singleFamily","description":"Zillow property type. Common values: 'singleFamily', 'condo', 'townhome', 'multiFamily', 'manufactured', 'land'"},"NC_TYPE":{"type":"string","nullable":true,"example":"builderSpec","description":"New-construction listing source type. Common values: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'"},"DAYS_ON_ZILLOW":{"type":"number","nullable":true,"example":47},"ZESTIMATE":{"type":"number","nullable":true,"example":432000},"RENT_ZESTIMATE":{"type":"number","nullable":true,"example":2450},"ZILLOW_URL":{"type":"string","nullable":true,"example":"https://www.zillow.com/homedetails/...","description":"Direct link to the Zillow listing page"},"LOT_SQFT":{"type":"number","nullable":true,"example":7234},"YEAR_BUILT":{"type":"number","nullable":true,"example":2024},"IS_PREMIER_BUILDER":{"type":"boolean","nullable":true,"example":true,"description":"Whether the builder is flagged as a Zillow Premier Builder"}},"required":["ZPID","BUILDER_NAME","ADDRESS","CITY","STATE","ZIP","SUBDIVISION","PRICE","PRICE_PER_SQFT","BEDS","BATHS","SQFT","LAT","LON","PROPERTY_TYPE","NC_TYPE","DAYS_ON_ZILLOW","ZESTIMATE","RENT_ZESTIMATE","ZILLOW_URL","LOT_SQFT","YEAR_BUILT","IS_PREMIER_BUILDER"]},"NewConstructionSearchResponse":{"type":"object","properties":{"total":{"type":"number","example":1247,"description":"Total matching listings across the dataset (not just the returned page)"},"returned":{"type":"number","example":25,"description":"Number of listings actually returned (capped by the limit query param)"},"state":{"type":"string","example":"AZ","description":"2-letter state code (echo of the required filter)"},"city":{"type":"string","nullable":true,"example":"Phoenix","description":"City filter applied, or null"},"zip":{"type":"string","nullable":true,"example":"85004","description":"ZIP filter applied, or null"},"listings":{"description":"Listings ordered by the requested sort column. Empty when no listings match the filters.","type":"array","items":{"$ref":"#/components/schemas/NewConstructionSearchListing"}}},"required":["total","returned","state","city","zip","listings"]},"NewConstructionStatsSummary":{"type":"object","properties":{"TOTAL":{"type":"number","example":4823},"MED_PRICE":{"type":"number","nullable":true,"example":425000},"AVG_PRICE":{"type":"number","nullable":true,"example":467823},"MIN_PRICE":{"type":"number","nullable":true,"example":189000},"MAX_PRICE":{"type":"number","nullable":true,"example":1875000},"MED_PPSF":{"type":"number","nullable":true,"example":218},"MED_SQFT":{"type":"number","nullable":true,"example":1956},"MED_BEDS":{"type":"number","nullable":true,"example":4},"MED_DOM":{"type":"number","nullable":true,"example":47},"PREMIER_COUNT":{"type":"number","nullable":true,"example":1234,"description":"Number of listings flagged as Premier Builder on Zillow"},"MED_ZESTIMATE":{"type":"number","nullable":true,"example":432000},"MED_RENT_ZEST":{"type":"number","nullable":true,"example":2450,"description":"Median monthly rent zestimate"}},"required":["TOTAL","MED_PRICE","AVG_PRICE","MIN_PRICE","MAX_PRICE","MED_PPSF","MED_SQFT","MED_BEDS","MED_DOM","PREMIER_COUNT","MED_ZESTIMATE","MED_RENT_ZEST"]},"NewConstructionBuilderRankRow":{"type":"object","properties":{"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"CNT":{"type":"number","example":312},"MED_PRICE":{"type":"number","nullable":true,"example":425000},"MIN_PRICE":{"type":"number","nullable":true,"example":215000},"MAX_PRICE":{"type":"number","nullable":true,"example":875000}},"required":["BUILDER_NAME","CNT","MED_PRICE","MIN_PRICE","MAX_PRICE"]},"NewConstructionPropertyTypeRow":{"type":"object","properties":{"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"singleFamily"},"CNT":{"type":"number","example":4123},"MED_PRICE":{"type":"number","nullable":true,"example":435000}},"required":["PROPERTY_TYPE","CNT","MED_PRICE"]},"NewConstructionNcTypeRow":{"type":"object","properties":{"NC_TYPE":{"type":"string","nullable":true,"example":"builderSpec","description":"Common values: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'"},"CNT":{"type":"number","example":3245}},"required":["NC_TYPE","CNT"]},"NewConstructionCityRow":{"type":"object","properties":{"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"CNT":{"type":"number","example":487},"MED_PRICE":{"type":"number","nullable":true,"example":425000}},"required":["CITY","CNT","MED_PRICE"]},"NewConstructionStatsResponse":{"type":"object","properties":{"state":{"type":"string","example":"AZ"},"city":{"type":"string","nullable":true,"example":"Phoenix"},"zip":{"type":"string","nullable":true,"example":"85004"},"summary":{"nullable":true,"description":"Aggregate stats. Null when no listings match the filters.","allOf":[{"$ref":"#/components/schemas/NewConstructionStatsSummary"}]},"builders":{"description":"Top 15 builders by listing count","type":"array","items":{"$ref":"#/components/schemas/NewConstructionBuilderRankRow"}},"property_types":{"description":"Property type breakdown ordered by listing count desc","type":"array","items":{"$ref":"#/components/schemas/NewConstructionPropertyTypeRow"}},"nc_types":{"description":"Listing source type (NC_TYPE) breakdown","type":"array","items":{"$ref":"#/components/schemas/NewConstructionNcTypeRow"}},"top_cities":{"description":"Top 10 cities by listing count. Only populated when neither city nor zip filter was provided — empty otherwise.","type":"array","items":{"$ref":"#/components/schemas/NewConstructionCityRow"}}},"required":["state","city","zip","summary","builders","property_types","nc_types","top_cities"]},"SubdivisionBuilderRow":{"type":"object","properties":{"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"CNT":{"type":"number","example":23},"MED_PRICE":{"type":"number","nullable":true,"example":425000}},"required":["BUILDER_NAME","CNT","MED_PRICE"]},"NewConstructionListing":{"type":"object","properties":{"ZPID":{"type":"string","nullable":true,"example":"12345678","description":"Zillow property ID"},"BUILDER_NAME":{"type":"string","nullable":true,"example":"LENNAR HOMES"},"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP":{"type":"string","nullable":true,"example":"85007"},"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"PRICE":{"type":"number","nullable":true,"example":425000},"PRICE_PER_SQFT":{"type":"number","nullable":true,"example":218.4},"BEDS":{"type":"number","nullable":true,"example":4},"BATHS":{"type":"number","nullable":true,"example":2.5},"SQFT":{"type":"number","nullable":true,"example":1956},"LAT":{"type":"number","nullable":true,"example":33.4632},"LON":{"type":"number","nullable":true,"example":-112.0712},"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"singleFamily","description":"Zillow property type. Common values: 'singleFamily', 'condo', 'townhome', 'multiFamily', 'manufactured', 'land'"},"NC_TYPE":{"type":"string","nullable":true,"example":"builderSpec","description":"New-construction listing source type. Common values: 'builderSpec', 'builderPlan', 'builderLotAndPrimaryPlanFacts'"},"DAYS_ON_ZILLOW":{"type":"number","nullable":true,"example":47},"ZESTIMATE":{"type":"number","nullable":true,"example":432000},"RENT_ZESTIMATE":{"type":"number","nullable":true,"example":2450},"ZILLOW_URL":{"type":"string","nullable":true,"example":"https://www.zillow.com/homedetails/...","description":"Direct link to the Zillow listing page"}},"required":["ZPID","BUILDER_NAME","ADDRESS","CITY","STATE","ZIP","SUBDIVISION","PRICE","PRICE_PER_SQFT","BEDS","BATHS","SQFT","LAT","LON","PROPERTY_TYPE","NC_TYPE","DAYS_ON_ZILLOW","ZESTIMATE","RENT_ZESTIMATE","ZILLOW_URL"]},"SubdivisionDetail":{"type":"object","properties":{"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"CITY":{"type":"string","nullable":true,"example":"CYPRESS"},"STATE":{"type":"string","nullable":true,"example":"TX"},"ZIP":{"type":"string","nullable":true,"example":"77433"},"total_listings":{"type":"number","example":87,"description":"Total listings across all rows that matched the subdivision filter (sums across the top 5 grouped rows)"},"MED_PRICE":{"type":"number","nullable":true,"example":412000},"MIN_PRICE":{"type":"number","nullable":true,"example":287000},"MAX_PRICE":{"type":"number","nullable":true,"example":745000},"MED_SQFT":{"type":"number","nullable":true,"example":2156},"MED_BEDS":{"type":"number","nullable":true,"example":4},"MED_BATHS":{"type":"number","nullable":true,"example":2.5},"MED_DOM":{"type":"number","nullable":true,"example":47},"MED_PPSF":{"type":"number","nullable":true,"example":191},"builders":{"description":"Top 5 builders active in this subdivision, ordered by listing count","type":"array","items":{"$ref":"#/components/schemas/SubdivisionBuilderRow"}},"listings":{"description":"Up to 50 individual listings in this subdivision, ordered by price ascending","type":"array","items":{"$ref":"#/components/schemas/NewConstructionListing"}}},"required":["SUBDIVISION","CITY","STATE","ZIP","total_listings","MED_PRICE","MIN_PRICE","MAX_PRICE","MED_SQFT","MED_BEDS","MED_BATHS","MED_DOM","MED_PPSF","builders","listings"]},"SubdivisionSummaryRow":{"type":"object","properties":{"SUBDIVISION":{"type":"string","nullable":true,"example":"BRIDGELAND"},"CITY":{"type":"string","nullable":true,"example":"CYPRESS"},"ZIP":{"type":"string","nullable":true,"example":"77433"},"CNT":{"type":"number","example":87},"MED_PRICE":{"type":"number","nullable":true,"example":412000},"MIN_PRICE":{"type":"number","nullable":true,"example":287000},"MAX_PRICE":{"type":"number","nullable":true,"example":745000},"MED_SQFT":{"type":"number","nullable":true,"example":2156},"BUILDERS":{"type":"string","nullable":true,"example":"LENNAR HOMES, PERRY HOMES","description":"Comma-separated unique builder names active in this subdivision (LISTAGG result)"}},"required":["SUBDIVISION","CITY","ZIP","CNT","MED_PRICE","MIN_PRICE","MAX_PRICE","MED_SQFT","BUILDERS"]},"SubdivisionSearchResponse":{"type":"object","properties":{"state":{"type":"string","example":"AZ"},"city":{"type":"string","nullable":true,"example":"Cypress"},"zip":{"type":"string","nullable":true,"example":null},"query_subdivision":{"type":"string","nullable":true,"example":"Bridgeland","description":"Echo of the subdivision name filter, or null when in top-list mode"},"detail":{"nullable":true,"description":"Detailed view of the top-matching subdivision. Populated only when query_subdivision is set; null otherwise.","allOf":[{"$ref":"#/components/schemas/SubdivisionDetail"}]},"top_subdivisions":{"description":"Top subdivisions by listing count in the requested area. Populated only when query_subdivision is null; empty array otherwise.","type":"array","items":{"$ref":"#/components/schemas/SubdivisionSummaryRow"}}},"required":["state","city","zip","query_subdivision","detail","top_subdivisions"]},"RentalMarketSummary":{"type":"object","properties":{"TOTAL":{"type":"number","example":4823},"MED_RENT":{"type":"number","nullable":true,"example":1950},"AVG_RENT":{"type":"number","nullable":true,"example":2087},"AVG_RPSF":{"type":"number","nullable":true,"example":1.42,"description":"Average rent per square foot"},"P10":{"type":"number","nullable":true,"example":1100,"description":"10th percentile rent"},"P25":{"type":"number","nullable":true,"example":1500,"description":"25th percentile rent"},"P50":{"type":"number","nullable":true,"example":1950,"description":"50th percentile (median) rent"},"P75":{"type":"number","nullable":true,"example":2600,"description":"75th percentile rent"},"P90":{"type":"number","nullable":true,"example":3500,"description":"90th percentile rent"},"AVG_BEDS":{"type":"number","nullable":true,"example":2.8},"AVG_SQFT":{"type":"number","nullable":true,"example":1456}},"required":["TOTAL","MED_RENT","AVG_RENT","AVG_RPSF","P10","P25","P50","P75","P90","AVG_BEDS","AVG_SQFT"]},"RentalMarketPropertyTypeRow":{"type":"object","properties":{"HOMETYPE":{"type":"string","nullable":true,"example":"SINGLE_FAMILY","description":"Zillow HOMETYPE value"},"CNT":{"type":"number","example":312},"MED_RENT":{"type":"number","nullable":true,"example":2200}},"required":["HOMETYPE","CNT","MED_RENT"]},"RentalMarketResponse":{"type":"object","properties":{"zip_code":{"type":"string","nullable":true,"example":"85004","description":"ZIP code filter applied, or null"},"city":{"type":"string","nullable":true,"example":null,"description":"City filter applied, or null"},"state":{"type":"string","example":"AZ"},"lookback_months":{"type":"number","example":12,"description":"Lookback window in months actually applied"},"summary":{"nullable":true,"description":"Aggregate stats. Null when no listings match the filters.","allOf":[{"$ref":"#/components/schemas/RentalMarketSummary"}]},"property_types":{"description":"Top 8 property types by listing count, ordered desc. Empty when no listings.","type":"array","items":{"$ref":"#/components/schemas/RentalMarketPropertyTypeRow"}}},"required":["zip_code","city","state","lookback_months","summary","property_types"]},"RentalYieldRentStats":{"type":"object","properties":{"TOTAL":{"type":"number","example":4823},"MED_RENT":{"type":"number","nullable":true,"example":1950},"AVG_RENT":{"type":"number","nullable":true,"example":2087},"MED_ZEST":{"type":"number","nullable":true,"example":432000,"description":"Median Zestimate across rent listings"},"MED_AVM":{"type":"number","nullable":true,"example":425000,"description":"Median First American AVM across rent listings"},"MED_RPSF":{"type":"number","nullable":true,"example":1.42,"description":"Median rent per square foot across rent listings"}},"required":["TOTAL","MED_RENT","AVG_RENT","MED_ZEST","MED_AVM","MED_RPSF"]},"RentalYieldAcquisitionStats":{"type":"object","properties":{"MATCHED_PROPERTY_CNT":{"type":"number","example":87,"description":"Number of unique properties with both a recent sale and a rent listing"},"MED_PRICE":{"type":"number","nullable":true,"example":425000,"description":"Median sale price in the matched-pair set"},"MED_RENT_SUBSET":{"type":"number","nullable":true,"example":2100,"description":"Median monthly rent for the same matched-pair properties (subset of all rent listings)"},"MED_YIELD":{"type":"number","nullable":true,"example":0.0593,"description":"Median acquisition cap rate (annual rent / sale price) computed per matched property and then median-aggregated"},"YIELD_P25":{"type":"number","nullable":true,"example":0.045,"description":"25th percentile of acquisition yields"},"YIELD_P75":{"type":"number","nullable":true,"example":0.072,"description":"75th percentile of acquisition yields"},"MED_PPSF":{"type":"number","nullable":true,"example":218.4,"description":"Median sale-price-per-square-foot across matched-pair purchases"}},"required":["MATCHED_PROPERTY_CNT","MED_PRICE","MED_RENT_SUBSET","MED_YIELD","YIELD_P25","YIELD_P75","MED_PPSF"]},"RentalYieldResponse":{"type":"object","properties":{"zip_code":{"type":"string","nullable":true,"example":"85004"},"city":{"type":"string","nullable":true,"example":null},"state":{"type":"string","example":"AZ"},"sale_start_date":{"type":"string","example":"2025-01-01","description":"Sale-date floor used for matched-pair acquisition stats. Properties with a sale before this date are excluded."},"rent_stats":{"nullable":true,"description":"Aggregate rent + valuation stats for the requested location. Null when no listings match.","allOf":[{"$ref":"#/components/schemas/RentalYieldRentStats"}]},"acquisition_stats":{"nullable":true,"description":"Matched-pair acquisition stats. Always null when zip_code is not provided (city-only lookups have no acquisition data).","allOf":[{"$ref":"#/components/schemas/RentalYieldAcquisitionStats"}]},"market_yield":{"type":"number","nullable":true,"example":0.0551,"description":"Market cap rate computed server-side: (median rent × 12) / (median AVM ?? median Zestimate). Null when inputs are missing."},"rent_to_price":{"type":"number","nullable":true,"example":0.00459,"description":"Rent-to-price ratio: median rent / (median AVM ?? median Zestimate). Null when inputs are missing."},"acquisition_yield":{"type":"number","nullable":true,"example":0.0593,"description":"Convenience alias for acquisition_stats.MED_YIELD (or null when acquisition_stats is null)"}},"required":["zip_code","city","state","sale_start_date","rent_stats","acquisition_stats","market_yield","rent_to_price","acquisition_yield"]},"RentalZipRankingRow":{"type":"object","properties":{"ZIP":{"type":"string","example":"85004","description":"5-digit ZIP code"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"TOTAL_LISTINGS":{"type":"number","example":487,"description":"Total rent listings in the lookback window"},"MEDIAN_RENT":{"type":"number","nullable":true,"example":1950},"AVG_RENT":{"type":"number","nullable":true,"example":2087},"AVG_RENT_PER_SQFT":{"type":"number","nullable":true,"example":1.42},"MARKET_YIELD":{"type":"number","nullable":true,"example":0.0612,"description":"Market yield: (median rent × 12) / median(COALESCE(CURRENT_AVM_VALUE, ZESTIMATE)). Null when valuation is missing."},"MEDIAN_AVM":{"type":"number","nullable":true,"example":432000,"description":"Median valuation per ZIP, preferring First American AVM and falling back to Zillow Zestimate"}},"required":["ZIP","CITY","TOTAL_LISTINGS","MEDIAN_RENT","AVG_RENT","AVG_RENT_PER_SQFT","MARKET_YIELD","MEDIAN_AVM"]},"RentalZipRankingsResponse":{"type":"object","properties":{"state":{"type":"string","example":"AZ"},"metro":{"type":"string","nullable":true,"example":"Phoenix","description":"Metro/MSA filter applied (fuzzy LIKE match), or null"},"sort":{"type":"string","description":"Sort field with optional \"-\" prefix for descending. Fields: median_rent, gross_yield, rent_per_sqft, total_listings.","example":"-gross_yield"},"limit":{"type":"number","example":15,"description":"Result limit actually applied"},"min_listings":{"type":"number","example":10,"description":"Minimum listings per ZIP filter actually applied"},"total":{"type":"number","example":12,"description":"Number of ZIPs returned"},"zips":{"description":"ZIP rows ordered by the requested sort metric. Empty when no ZIPs match the filters.","type":"array","items":{"$ref":"#/components/schemas/RentalZipRankingRow"}}},"required":["state","metro","sort","limit","min_listings","total","zips"]},"ListingRow":{"type":"object","properties":{"PROPERTY_ID":{"type":"number","example":12345678},"LISTING_ID":{"type":"string","nullable":true,"example":"L_98765432"},"ADDRESS":{"type":"string","nullable":true,"example":"332 E WINDSOR AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP_CODE":{"type":"string","nullable":true,"example":"85004"},"PRICE":{"type":"number","nullable":true,"example":425000},"BEDS":{"type":"number","nullable":true,"example":3},"BATHS":{"type":"number","nullable":true,"example":2},"SQFT":{"type":"number","nullable":true,"example":1750},"LOT_SIZE":{"type":"number","nullable":true,"example":7234},"YEAR_BUILT":{"type":"number","nullable":true,"example":1962},"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"Single Family Residential"},"DOM":{"type":"number","nullable":true,"example":32,"description":"Days on market"},"HOA_DUES":{"type":"number","nullable":true,"example":250},"URL":{"type":"string","nullable":true,"example":"https://www.redfin.com/..."},"LATITUDE":{"type":"number","nullable":true,"example":33.4632},"LONGITUDE":{"type":"number","nullable":true,"example":-112.0712},"STATUS":{"type":"string","nullable":true,"example":"Active"},"FIRST_SEEN":{"type":"string","nullable":true,"example":"2024-08-01"},"LAST_SEEN":{"type":"string","nullable":true,"example":"2024-09-15"}},"required":["PROPERTY_ID","LISTING_ID","ADDRESS","CITY","STATE","ZIP_CODE","PRICE","BEDS","BATHS","SQFT","LOT_SIZE","YEAR_BUILT","PROPERTY_TYPE","DOM","HOA_DUES","URL","LATITUDE","LONGITUDE","STATUS","FIRST_SEEN","LAST_SEEN"]},"ListingSearchResponse":{"type":"object","properties":{"total":{"type":"number","example":1247,"description":"Total matching listings across the dataset (not just the returned page)"},"returned":{"type":"number","example":25,"description":"Number of listings actually returned (capped by the limit query param)"},"offset":{"type":"number","example":0,"description":"Pagination offset actually applied"},"listings":{"description":"Listings ordered by the requested sort metric. Empty when no listings match the filters.","type":"array","items":{"$ref":"#/components/schemas/ListingRow"}}},"required":["total","returned","offset","listings"]},"SoldRow":{"type":"object","properties":{"PROPERTY_ID":{"type":"number","example":12345678},"LISTING_ID":{"type":"string","nullable":true,"example":"L_98765432"},"ADDRESS":{"type":"string","nullable":true,"example":"332 E WINDSOR AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP_CODE":{"type":"string","nullable":true,"example":"85004"},"SOLD_PRICE":{"type":"number","nullable":true,"example":410000},"LIST_PRICE":{"type":"number","nullable":true,"example":425000},"BEDS":{"type":"number","nullable":true,"example":3},"BATHS":{"type":"number","nullable":true,"example":2},"SQFT":{"type":"number","nullable":true,"example":1750},"YEAR_BUILT":{"type":"number","nullable":true,"example":1962},"PROPERTY_TYPE":{"type":"string","nullable":true,"example":"Single Family Residential"},"SOLD_DATE":{"type":"string","nullable":true,"example":"2024-08-15"},"DOM":{"type":"number","nullable":true,"example":14},"LATITUDE":{"type":"number","nullable":true,"example":33.4632},"LONGITUDE":{"type":"number","nullable":true,"example":-112.0712},"URL":{"type":"string","nullable":true,"example":"https://www.redfin.com/..."}},"required":["PROPERTY_ID","LISTING_ID","ADDRESS","CITY","STATE","ZIP_CODE","SOLD_PRICE","LIST_PRICE","BEDS","BATHS","SQFT","YEAR_BUILT","PROPERTY_TYPE","SOLD_DATE","DOM","LATITUDE","LONGITUDE","URL"]},"PropertyDetailRow":{"type":"object","properties":{"PROPERTY_ID":{"type":"number","example":12345678},"LISTING_ID":{"type":"string","nullable":true,"example":"L_98765432"},"DESCRIPTION":{"type":"string","nullable":true,"example":"Charming mid-century home in historic Windsor district. Recently updated kitchen..."},"TAX_ASSESSED_VALUE":{"type":"number","nullable":true,"example":387500},"LAST_SALE_DATE":{"type":"string","nullable":true,"example":"2018-06-22"},"LAST_SALE_PRICE":{"type":"number","nullable":true,"example":285000},"LISTING_AGENT":{"type":"string","nullable":true,"example":"Jane Smith • Redfin"},"LISTING_BROKER":{"type":"string","nullable":true,"example":"Realty Executives Phoenix"},"PRICE_HISTORY":{"type":"array","items":{"type":"object","additionalProperties":true},"nullable":true,"description":"Array of price-change events. Schema varies — typical fields include `date`/`eventDate`, `eventDescription`/`event`, `price`/`priceChangeAmount`. Null when no history available."},"TAX_HISTORY":{"type":"array","items":{"type":"object","additionalProperties":true},"nullable":true,"description":"Array of tax history entries. Schema varies. Null when no history available."},"FETCHED_AT":{"type":"string","nullable":true,"example":"2024-09-15 14:32","description":"When the detail row was last fetched/scraped"},"TAGS_DISTRESS":{"nullable":true,"example":["pre_foreclosure"],"description":"Distress signals tagged for this property","type":"array","items":{"type":"string"}},"TAGS_INVESTOR":{"nullable":true,"example":["cash_buyer"],"type":"array","items":{"type":"string"}},"TAGS_MOTIVATION":{"nullable":true,"example":["price_drop"],"type":"array","items":{"type":"string"}},"TAGS_OPPORTUNITY":{"nullable":true,"example":["fixer_upper"],"type":"array","items":{"type":"string"}},"TAGS_CASH_ONLY":{"nullable":true,"example":["cash_only"],"type":"array","items":{"type":"string"}},"TAGS_VACANT":{"nullable":true,"example":["vacant"],"type":"array","items":{"type":"string"}},"TAGS_CREATIVE_FINANCING":{"nullable":true,"example":["seller_financing"],"type":"array","items":{"type":"string"}},"TAGS_MULTI_UNIT":{"nullable":true,"example":["duplex"],"type":"array","items":{"type":"string"}},"TAGS_DEVELOPMENT":{"nullable":true,"example":["lot_split_potential"],"type":"array","items":{"type":"string"}},"TAGS_NON_CONFORMING":{"nullable":true,"example":["off_grid"],"type":"array","items":{"type":"string"}}},"required":["PROPERTY_ID","LISTING_ID","DESCRIPTION","TAX_ASSESSED_VALUE","LAST_SALE_DATE","LAST_SALE_PRICE","LISTING_AGENT","LISTING_BROKER","PRICE_HISTORY","TAX_HISTORY","FETCHED_AT","TAGS_DISTRESS","TAGS_INVESTOR","TAGS_MOTIVATION","TAGS_OPPORTUNITY","TAGS_CASH_ONLY","TAGS_VACANT","TAGS_CREATIVE_FINANCING","TAGS_MULTI_UNIT","TAGS_DEVELOPMENT","TAGS_NON_CONFORMING"]},"PropertyDetailResponse":{"type":"object","properties":{"property_id":{"type":"number","example":12345678},"listing":{"nullable":true,"description":"Active listing row, or null when the property is not currently listed","allOf":[{"$ref":"#/components/schemas/ListingRow"}]},"sold":{"nullable":true,"description":"Most recent sold record, or null when the property has not sold via Redfin","allOf":[{"$ref":"#/components/schemas/SoldRow"}]},"detail":{"nullable":true,"description":"Enriched details (description, agent, tax info, tags, history). Null when not yet fetched.","allOf":[{"$ref":"#/components/schemas/PropertyDetailRow"}]}},"required":["property_id","listing","sold","detail"]},"SoldCompsSubject":{"type":"object","properties":{"property_id":{"type":"number","nullable":true,"example":12345678},"address":{"type":"string","nullable":true,"example":"332 E WINDSOR AVE"},"city":{"type":"string","nullable":true,"example":"PHOENIX"},"state":{"type":"string","nullable":true,"example":"AZ"},"zip_code":{"type":"string","nullable":true,"example":"85004"},"price":{"type":"number","nullable":true,"example":475000},"beds":{"type":"number","nullable":true,"example":3},"baths":{"type":"number","nullable":true,"example":2},"sqft":{"type":"number","nullable":true,"example":1750},"year_built":{"type":"number","nullable":true,"example":1962},"latitude":{"type":"number","nullable":true,"example":33.4632},"longitude":{"type":"number","nullable":true,"example":-112.0712}},"required":["property_id","address","city","state","zip_code","price","beds","baths","sqft","year_built","latitude","longitude"]},"SoldCompsSummary":{"type":"object","properties":{"comp_count":{"type":"number","example":18},"median_price":{"type":"number","nullable":true,"example":432500},"median_adjusted_price":{"type":"number","nullable":true,"example":441200,"description":"Median of time-adjusted prices"},"min_price":{"type":"number","nullable":true,"example":320000},"max_price":{"type":"number","nullable":true,"example":587000},"median_price_per_sqft":{"type":"number","nullable":true,"example":247},"vs_median_pct":{"type":"number","nullable":true,"example":7.7,"description":"Subject price vs. median adjusted price as a percentage. Positive = subject is above median. Null when subject price unknown."}},"required":["comp_count","median_price","median_adjusted_price","min_price","max_price","median_price_per_sqft","vs_median_pct"]},"SoldCompRow":{"type":"object","properties":{"PROPERTY_ID":{"type":"number","example":14523891},"ADDRESS":{"type":"string","nullable":true,"example":"1245 N 7TH AVE"},"CITY":{"type":"string","nullable":true,"example":"PHOENIX"},"STATE":{"type":"string","nullable":true,"example":"AZ"},"ZIP_CODE":{"type":"string","nullable":true,"example":"85007"},"SOLD_PRICE":{"type":"number","nullable":true,"example":425000},"LIST_PRICE":{"type":"number","nullable":true,"example":435000},"BEDS":{"type":"number","nullable":true,"example":3},"BATHS":{"type":"number","nullable":true,"example":2},"SQFT":{"type":"number","nullable":true,"example":1750},"YEAR_BUILT":{"type":"number","nullable":true,"example":1965},"SOLD_DATE":{"type":"string","nullable":true,"example":"2024-08-15"},"DOM":{"type":"number","nullable":true,"example":14,"description":"Days on market"},"LATITUDE":{"type":"number","nullable":true,"example":33.4632},"LONGITUDE":{"type":"number","nullable":true,"example":-112.0712},"DIST_MILES":{"type":"number","nullable":true,"example":0.4,"description":"Haversine distance in miles from the subject location"},"SIMILARITY":{"type":"number","example":87.5,"description":"Similarity score 0-100. Weights: distance 30%, sqft 25%, beds 10%, baths 5%, year built 15%, recency 15%."},"ADJUSTED_PRICE":{"type":"number","nullable":true,"example":432500,"description":"Sale price adjusted to today using the local YoY appreciation rate (or 3% default)"},"PRICE_PER_SQFT":{"type":"number","nullable":true,"example":247,"description":"SOLD_PRICE / SQFT, rounded"}},"required":["PROPERTY_ID","ADDRESS","CITY","STATE","ZIP_CODE","SOLD_PRICE","LIST_PRICE","BEDS","BATHS","SQFT","YEAR_BUILT","SOLD_DATE","DOM","LATITUDE","LONGITUDE","DIST_MILES","SIMILARITY","ADJUSTED_PRICE","PRICE_PER_SQFT"]},"SoldCompsResponse":{"type":"object","properties":{"subject":{"nullable":true,"description":"Subject property info if it was resolvable from property_id or address. Null for lat+lon or ZIP-centroid lookups.","allOf":[{"$ref":"#/components/schemas/SoldCompsSubject"}]},"resolved_lat":{"type":"number","example":33.4632,"description":"Search center latitude actually used"},"resolved_lon":{"type":"number","example":-112.0712,"description":"Search center longitude actually used"},"radius_miles":{"type":"number","example":1,"description":"Search radius actually applied"},"days_back":{"type":"number","example":180,"description":"Lookback window actually applied"},"yoy_rate_used":{"type":"number","example":0.057,"description":"YoY appreciation rate used for time adjustment. Sourced from REDFIN_ZIP_MARKET when ZIP is known; defaults to 0.03."},"summary":{"nullable":true,"description":"Aggregate stats over the returned comps. Null when comps[] is empty.","allOf":[{"$ref":"#/components/schemas/SoldCompsSummary"}]},"comps":{"description":"Top N comps sorted by similarity score descending. Empty when no sold comps within the radius.","type":"array","items":{"$ref":"#/components/schemas/SoldCompRow"}}},"required":["subject","resolved_lat","resolved_lon","radius_miles","days_back","yoy_rate_used","summary","comps"]}}},"externalDocs":{"description":"API Guide","url":"/api-guide"}}