{"openapi":"3.1.0","info":{"title":"Property Comps API","description":"Comparable property sales data across 16 global markets. One unified API, government registry data.\n\n**Markets:** UK, France, Singapore, NYC, Chicago, Dubai, Miami, Philadelphia, Connecticut, Ireland, Taiwan, Washington DC, Seattle, Phoenix, Denver, Pittsburgh\n\n**Total transactions:** 51M+ recorded sales from official government registries.\n\nEvery result is an actual sale recorded by a tax authority -- not an estimate, not a listing.\n\n## Rental Yield Data (US Markets)\n\nFor US markets (NYC, CHI, MIA, PHL, CT, DC, SEA, PHX, DEN, PIT), `/v1/stats` responses include gross rental yield:\n\n- `monthly_rent_estimate`: area rent from federal data\n- `gross_yield_pct`: (monthly_rent x 12) / median_price x 100\n- `yield_source`: \"HUD SAFMR FY2026\" or \"Census ACS 5-Year 2023\"\n- `beds_used_for_yield`: bedroom count used for rent lookup\n\nUse the `min_beds` parameter to refine the yield to a specific bedroom bracket.\nData is sourced from federal government registries (HUD SAFMR + Census ACS) and updated annually.\n\n## Bedroom & Bathroom Filters\n\n- `min_beds` (integer): NYC, CHI, MIA, PHL, DC, SEA, PHX, DEN, PIT\n- `min_baths` (number): CHI, MIA, PHL, DC, SEA, PHX, DEN, PIT\n\nThese markets with no bedroom/bathroom data: UK, FR, SG, DXB, IE, TW, CT.\n\n## Data Quality (US Markets)\n\nFor NYC, MIA, PHL, and DC the API distinguishes three transaction classes via the `sale_type` parameter:\n\n- `unit` (default): individual dwelling or apartment sales -- the comp set you want for residential valuations\n- `whole_building`: entire multi-unit rental assets sold as a single deal (NYC + MIA only, where `total_units > 1`)\n- `bulk_disguised`: portfolio or whole-building deals that the source agency filed as N individual unit deeds at the total transaction price. Auto-detected when the same `sale_date` and exact `sale_price` appears across 3+ distinct addresses at >= $10M. Excluded from the default unit-level results so portfolio transfers do not pollute medians, yields, or by-type breakdowns.\n- `all`: returns every classification (use only if you specifically need polluted records for auditing).\n\nAll `/v1/comps`, `/v1/stats`, `/v1/trends`, and `/v1/analytics` endpoints default to `sale_type=unit`. CHI and CT source data is already clean and these classes do not apply.\n\n## Quick Start\n\n1. Pick a market (e.g. `uk`, `nyc`, `dxb`)\n2. Call `/v1/comps?market=uk&postcode=SW1A1AA` to get comparable sales\n3. Call `/v1/stats?market=uk&postcode=SW1A1AA` for area statistics\n4. Call `/markets` to see all 16 markets with examples\n\n## Location Parameters\n\nEach market uses its local location format:\n\n| Market | Code | Parameter | Example |\n|--------|------|-----------|---------|\n| United Kingdom | `uk` | `postcode` | `SW1A1AA` |\n| France | `fr` | `code_postal` | `75001` |\n| Singapore | `sg` | `postal_code` | `310195` |\n| New York City | `nyc` | `zip_code` | `10001` |\n| Chicago | `chi` | `zip_code` | `60606` |\n| Dubai | `dxb` | `area_name` | `Dubai Marina` |\n| Miami | `mia` | `zip_code` | `33101` |\n| Philadelphia | `phl` | `zip_code` | `19103` |\n| Connecticut | `ct` | `town` | `Greenwich` |\n| Ireland | `ie` | `county` | `Dublin` |\n| Taiwan | `tw` | `city` | `Taipei` |\n| Washington DC | `dc` | `zip_code` | `20001` |\n| Seattle | `sea` | `zip_code` | `98115` |\n| Phoenix | `phx` | `zip_code` | `85004` |\n| Denver | `den` | `zip_code` | `80202` |\n| Pittsburgh | `pit` | `zip_code` | `15222` |\n","version":"1.0.0","contact":{"name":"New Way Capital Advisory","email":"info@nwc-advisory.com","url":"https://nwc-advisory.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.nwc-advisory.com","description":"Production (unified gateway)"}],"paths":{"/markets":{"get":{"operationId":"listMarkets","summary":"List all available markets","description":"Returns all 16 available markets with metadata including name, currency,\ntransaction count, location parameter name, and example value.\nCall this first to discover which markets are available and how to query them.\n","tags":["Discovery"],"responses":{"200":{"description":"List of markets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketsResponse"},"example":{"markets":[{"market":"uk","name":"United Kingdom","currency":"GBP","transactions":"31M","location_param":"postcode","example":"SW1A1AA"},{"market":"nyc","name":"New York City","currency":"USD","transactions":"505K","location_param":"zip_code","example":"10001"}],"total_markets":16,"total_transactions":"51M+","data_source":"Official government property registries"}}}}}}},"/v1/comps":{"get":{"operationId":"searchComps","summary":"Search comparable sales","description":"Find recent property sales within a radius of a given location.\nReturns price, date, address, property type, area, and distance for each sale.\nAlso returns aggregate statistics (median, average, min, max, count).\n\nPass the location using the market-specific parameter name.\nFor example: `?market=uk&postcode=SW1A1AA` or `?market=nyc&zip_code=10001`\n","tags":["Comparable Sales"],"parameters":[{"$ref":"#/components/parameters/market"},{"name":"postcode","in":"query","description":"Location for UK market","schema":{"type":"string"},"example":"SW1A1AA"},{"name":"code_postal","in":"query","description":"Location for France market","schema":{"type":"string"},"example":"75001"},{"name":"zip_code","in":"query","description":"Location for US markets: NYC, Chicago, Miami, Philadelphia, DC, Seattle, Phoenix, Denver, Pittsburgh","schema":{"type":"string"},"example":"10001"},{"name":"postal_code","in":"query","description":"Location for Singapore market","schema":{"type":"string"},"example":"310195"},{"name":"area_name","in":"query","description":"Location for Dubai market","schema":{"type":"string"},"example":"Dubai Marina"},{"name":"town","in":"query","description":"Location for Connecticut market","schema":{"type":"string"},"example":"Greenwich"},{"name":"county","in":"query","description":"Location for Ireland market","schema":{"type":"string"},"example":"Dublin"},{"name":"city","in":"query","description":"Location for Taiwan market","schema":{"type":"string"},"example":"Taipei"},{"name":"radius_miles","in":"query","description":"Search radius in miles (UK and US markets)","schema":{"type":"number","minimum":0.01,"maximum":10.0,"default":1.0}},{"name":"radius_km","in":"query","description":"Search radius in km (France, Singapore, Dubai, Ireland, Taiwan)","schema":{"type":"number","minimum":0.01,"maximum":15.0,"default":1.0}},{"name":"months","in":"query","description":"Look-back period in months","schema":{"type":"integer","minimum":1,"maximum":360,"default":12}},{"name":"property_type","in":"query","description":"Filter by property type (market-specific values):\n- UK: D (Detached), S (Semi-Detached), T (Terraced), F (Flat)\n- NYC/CHI/MIA/PHL/DC/SEA/PHX/DEN/PIT: Single Family, Condo, Co-op, 2-Family, 3-Family, Townhouse\n- Singapore: 2 ROOM, 3 ROOM, 4 ROOM, 5 ROOM, EXECUTIVE\n- Dubai: Villa, Apartment, Townhouse, Penthouse\n","schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum sale price filter","schema":{"type":"integer"}},{"name":"max_price","in":"query","description":"Maximum sale price filter","schema":{"type":"integer"}},{"name":"limit","in":"query","description":"Maximum results to return","schema":{"type":"integer","minimum":1,"maximum":500,"default":25}},{"$ref":"#/components/parameters/min_beds"},{"$ref":"#/components/parameters/min_baths"}],"responses":{"200":{"description":"Comparable sales with statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompsResponse"},"examples":{"uk_example":{"summary":"UK -- London SW1A postcode","value":{"results":[{"price":1250000,"date":"2025-11-15","address":"42 Buckingham Gate, London SW1E 6BS","property_type":"Flat","distance_miles":0.18,"floor_area_sqm":85},{"price":875000,"date":"2025-10-22","address":"15 Petty France, London SW1H 9EA","property_type":"Flat","distance_miles":0.31}],"count":42,"statistics":{"median":950000,"average":1125000,"min":425000,"max":3200000,"count":42},"_meta":{"market":"uk","market_name":"United Kingdom","currency":"GBP","response_ms":1250,"source":"Official government property registry"}}},"seattle_example":{"summary":"US -- Seattle ZIP 98115","value":{"results":[{"sale_price":825000,"sale_date":"2025-12-03","address":"4512 NE 55th St, Seattle","property_type":"Single Family","zip_code":"98115","distance_miles":0.42,"gross_sqft":1680,"price_per_sqft":491.07,"bedrooms":3,"bathrooms":2.0,"year_built":1942,"stories":1.5,"grade":"7","condition":4},{"sale_price":615000,"sale_date":"2025-11-18","address":"6724 25th Ave NE, Seattle","property_type":"Condo","zip_code":"98115","distance_miles":0.67,"gross_sqft":1050,"price_per_sqft":585.71,"bedrooms":2,"bathrooms":1.5,"year_built":2018}],"count":85,"statistics":{"median":735000,"average":812000,"min":345000,"max":2100000,"count":85},"_meta":{"market":"sea","market_name":"Seattle","currency":"USD","response_ms":890,"source":"Official government property registry"}}}}}}},"400":{"description":"Missing or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Area statistics","description":"Get price statistics for an area broken down by property type.\nReturns median, average, min, max, and transaction count.\nUseful for quick market snapshots without full transaction data.\n","tags":["Statistics"],"parameters":[{"$ref":"#/components/parameters/market"},{"name":"postcode","in":"query","description":"Location for UK market","schema":{"type":"string"},"example":"SW1A1AA"},{"name":"code_postal","in":"query","description":"Location for France market","schema":{"type":"string"},"example":"75001"},{"name":"zip_code","in":"query","description":"Location for US markets: NYC, CHI, MIA, PHL, DC, SEA, PHX, DEN, PIT","schema":{"type":"string"},"example":"10001"},{"name":"postal_code","in":"query","description":"Location for Singapore market","schema":{"type":"string"},"example":"310195"},{"name":"area_name","in":"query","description":"Location for Dubai market","schema":{"type":"string"},"example":"Dubai Marina"},{"name":"town","in":"query","description":"Location for Connecticut market","schema":{"type":"string"},"example":"Greenwich"},{"name":"county","in":"query","description":"Location for Ireland market","schema":{"type":"string"},"example":"Dublin"},{"name":"city","in":"query","description":"Location for Taiwan market","schema":{"type":"string"},"example":"Taipei"},{"name":"radius_miles","in":"query","description":"Search radius in miles (UK and US markets)","schema":{"type":"number","default":1.0}},{"name":"months","in":"query","schema":{"type":"integer","default":12}},{"$ref":"#/components/parameters/min_beds"},{"$ref":"#/components/parameters/min_baths"}],"responses":{"200":{"description":"Area statistics by property type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"},"example":{"area":"10001","period":"12 months","stats":{"median":875000,"average":1125000,"min":350000,"max":4500000,"count":128},"by_type":{"Condo":{"median":950000,"average":1250000,"count":87},"Co-op":{"median":625000,"average":720000,"count":41}},"monthly_rent_estimate":3150,"gross_yield_pct":4.3,"yield_source":"HUD SAFMR FY2026","beds_used_for_yield":2,"_meta":{"market":"nyc","market_name":"New York City","currency":"USD"}}}}}}}},"/v1/trends":{"get":{"operationId":"getTrends","summary":"Monthly price trends","description":"Monthly median and average prices with year-over-year percentage change.\nUseful for tracking market direction. Pro plan required.\n","tags":["Trends"],"parameters":[{"$ref":"#/components/parameters/market"},{"name":"postcode","in":"query","description":"Location (use market-specific parameter name)","schema":{"type":"string"}},{"name":"months","in":"query","schema":{"type":"integer","default":24}}],"responses":{"200":{"description":"Monthly trends with YoY change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendsResponse"}}}}}}},"/v1/comps/csv":{"get":{"operationId":"getCompsCsv","summary":"CSV export","description":"Download comparable sales results as a CSV file for spreadsheet analysis.","tags":["Exports"],"parameters":[{"$ref":"#/components/parameters/market"},{"name":"postcode","in":"query","description":"Location (use market-specific parameter name)","schema":{"type":"string"}},{"name":"radius_miles","in":"query","schema":{"type":"number","default":1.0}},{"name":"months","in":"query","schema":{"type":"integer","default":12}},{"name":"limit","in":"query","schema":{"type":"integer","default":25}},{"$ref":"#/components/parameters/min_beds"},{"$ref":"#/components/parameters/min_baths"}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/v1/valuation/pdf":{"get":{"operationId":"getValuationPdf","summary":"PDF valuation report","description":"Generate a branded, multi-page PDF report with charts, statistics,\nmethodology, and comparable transactions table.\nReports available in English, French, Spanish, and Traditional Chinese\ndepending on market. Pro plan required.\n","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/market"},{"name":"postcode","in":"query","description":"Location (use market-specific parameter name)","schema":{"type":"string"}},{"name":"radius_miles","in":"query","schema":{"type":"number","default":1.0}},{"name":"months","in":"query","schema":{"type":"integer","default":12}},{"name":"lang","in":"query","description":"Report language: en, fr, es, zh","schema":{"type":"string","default":"en","enum":["en","fr","es","zh"]}},{"$ref":"#/components/parameters/min_beds"},{"$ref":"#/components/parameters/min_baths"}],"responses":{"200":{"description":"PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}}}}},"/health":{"get":{"operationId":"healthCheck","summary":"Gateway health check","description":"Returns gateway status and health of all 16 market backends.","tags":["System"],"responses":{"200":{"description":"Health status with backend availability","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"1.0.0"},"markets_online":{"type":"string","example":"16/16"},"backends":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}}},"components":{"parameters":{"min_beds":{"name":"min_beds","in":"query","required":false,"description":"Minimum bedroom count filter. Supported: NYC, CHI, MIA, PHL, DC, SEA, PHX, DEN, PIT. Also refines yield calculation to matching bedroom rent bracket.","schema":{"type":"integer","minimum":0,"maximum":10},"example":2},"min_baths":{"name":"min_baths","in":"query","required":false,"description":"Minimum bathroom count filter. Supported: CHI, MIA, PHL, DC, SEA, PHX, DEN, PIT.","schema":{"type":"number","minimum":0,"maximum":10},"example":2},"market":{"name":"market","in":"query","required":true,"description":"Market code. One of: uk, fr, sg, nyc, chi, dxb, mia, phl, ct, ie, tw, dc, sea, phx, den, pit.\nUse /markets to see all options with examples.\n","schema":{"type":"string","enum":["uk","fr","sg","nyc","chi","dxb","mia","phl","ct","ie","tw","dc","sea","phx","den","pit"]}}},"schemas":{"MarketsResponse":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"market":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"transactions":{"type":"string"},"location_param":{"type":"string"},"example":{"type":"string"}}}},"total_markets":{"type":"integer"},"total_transactions":{"type":"string"},"data_source":{"type":"string"}}},"CompsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"count":{"type":"integer","example":42},"statistics":{"$ref":"#/components/schemas/Statistics"},"query_params":{"type":"object"},"_meta":{"$ref":"#/components/schemas/Meta"}}},"Transaction":{"type":"object","description":"A single property sale record. Field availability varies by market.\nUK: floor_area_sqm, price_per_sqm. US markets: gross_sqft, price_per_sqft, bedrooms, bathrooms, year_built, stories, grade, condition.\nAll markets: price (sale_price), date (sale_date), address, property_type, distance_miles.\n","properties":{"price":{"type":"integer","description":"Sale price in local currency (also returned as sale_price)","example":450000},"date":{"type":"string","description":"Sale date (also returned as sale_date)","example":"2025-01-15"},"address":{"type":"string","example":"123 High Street, London"},"property_type":{"type":"string","example":"Flat"},"distance_miles":{"type":"number","example":0.32},"floor_area_sqm":{"type":"number","description":"Floor area in square metres (UK, FR, SG, DXB, IE, TW)","example":85.5},"price_per_sqm":{"type":"number","description":"Price per square metre (UK, FR, SG, DXB, IE, TW)","example":5263},"gross_sqft":{"type":"integer","description":"Building area in square feet (US markets). May be 0 if unavailable.","example":1250},"price_per_sqft":{"type":"number","description":"Price per square foot (US markets). Null if gross_sqft is 0.","example":360.0},"bedrooms":{"type":"integer","description":"Number of bedrooms (US markets)","example":3},"bathrooms":{"type":"number","description":"Number of bathrooms (US markets, may be decimal e.g. 2.5)","example":2.0},"year_built":{"type":"integer","description":"Year the property was built (US markets)","example":1985},"stories":{"type":"number","description":"Number of stories (US markets)","example":2},"grade":{"type":"string","description":"Assessor grade/class (US markets, varies by county)","example":"C+"},"condition":{"type":"integer","description":"Property condition score 1-7 (PHL, PHX, PIT, DEN). Higher is better.","example":4}}},"Statistics":{"type":"object","properties":{"median":{"type":"integer","example":450000},"average":{"type":"integer","example":465000},"min":{"type":"integer","example":280000},"max":{"type":"integer","example":750000},"count":{"type":"integer","example":42}}},"StatsResponse":{"type":"object","properties":{"area":{"type":"string"},"period":{"type":"string"},"stats":{"$ref":"#/components/schemas/Statistics"},"by_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Statistics"}},"monthly_rent_estimate":{"type":"integer","nullable":true,"description":"Estimated monthly rent for the area, derived from HUD SAFMR or Census ACS (US markets only)","example":3150},"gross_yield_pct":{"type":"number","format":"float","nullable":true,"description":"Gross rental yield percentage: (monthly_rent x 12) / median_price x 100. Available for US markets (NYC, CHI, MIA, PHL, CT, DC, SEA, PHX, DEN, PIT).","example":5.4},"yield_source":{"type":"string","nullable":true,"description":"Data source for rental yield. Values: 'Census ACS 5-Year 2023', 'HUD SAFMR FY2026', or null if unavailable.","example":"HUD SAFMR FY2026"},"beds_used_for_yield":{"type":"integer","nullable":true,"description":"Bedroom count used for rent lookup (0-4). Follows min_beds filter if provided, else median from comps, else 2.","example":2},"_meta":{"$ref":"#/components/schemas/Meta"}}},"TrendsResponse":{"type":"object","properties":{"trends":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2025-01"},"median_price":{"type":"integer"},"avg_price":{"type":"integer"},"count":{"type":"integer"},"yoy_change_pct":{"type":"number"}}}},"_meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","description":"Metadata added by the gateway","properties":{"market":{"type":"string","example":"uk"},"market_name":{"type":"string","example":"United Kingdom"},"currency":{"type":"string","example":"GBP"},"response_ms":{"type":"integer","example":1250},"source":{"type":"string","example":"Official government property registry"}}},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unknown market: xyz"},"available_markets":{"type":"array","items":{"type":"string"}},"hint":{"type":"string","example":"Use /markets to see all options with examples"}}}}}}