{"openapi":"3.1.0","info":{"title":"NYC Property Market: public data API","version":"1.0.0","description":"Free, unauthenticated JSON API for New York City property sale statistics, built entirely from official NYC Department of Finance recorded deed sales. Only arm's-length market sales feed price metrics; figures are medians (never averages) and are suppressed below a minimum sample. Every response carries a provenance envelope with an as-of date, source and attribution line. Free to use with attribution to NYC Property Market.","contact":{"name":"NYC Property Market","url":"https://nycpropertymarket.com"},"license":{"name":"Free with attribution","url":"https://nycpropertymarket.com/methodology"}},"servers":[{"url":"https://nycpropertymarket.com/api/v1","description":"Production"}],"paths":{"/meta":{"get":{"summary":"Data vintages, license, endpoint index","operationId":"getMeta","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Meta_data"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}}}}},"/market":{"get":{"summary":"Citywide 12-month summary + by-borough rollup","operationId":"getMarket","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GeoSummary"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}}}}},"/boroughs/{slug}":{"get":{"summary":"Borough 12-month summary","operationId":"getBorough","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","enum":["manhattan","bronx","brooklyn","queens","staten-island"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GeoSummary"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/areas":{"get":{"summary":"All neighborhoods with headline 12-month stats","operationId":"listAreas","parameters":[{"name":"borough","in":"query","required":false,"schema":{"type":"string","enum":["manhattan","bronx","brooklyn","queens","staten-island"]},"description":"Restrict to one borough."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AreaList"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}}}}},"/areas/{slug}":{"get":{"summary":"Full neighborhood summary","operationId":"getArea","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Neighborhood slug (see /api/v1/areas). Retired slugs 308-redirect to the canonical one."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Area"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/areas/{slug}/history":{"get":{"summary":"Yearly median-price series (2003–present), all property types combined","operationId":"getAreaHistory","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Neighborhood slug (see /api/v1/areas). Retired slugs 308-redirect to the canonical one."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/History"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/areas/{slug}/rent-yield":{"get":{"summary":"Neighborhood rent + gross rent-to-price yield","operationId":"getAreaRentYield","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Neighborhood slug (see /api/v1/areas). Retired slugs 308-redirect to the canonical one."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentYield"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rankings/rent-yield":{"get":{"summary":"Neighborhoods ranked by gross rent-to-price yield (most profitable rental areas)","operationId":"getRentYieldRanking","parameters":[{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["high","low"]},"description":"Sort direction (default high)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 25."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentYieldRanking"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}}}}},"/property/{bbl}":{"get":{"summary":"Property snapshot by 10-digit BBL","operationId":"getProperty","parameters":[{"name":"bbl","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{10}$"},"description":"Borough-Block-Lot (10 digits). Resolve an address at /tools/bbl-lookup."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Meta":{"type":"object","properties":{"asOf":{"type":["string","null"],"format":"date","description":"Data vintage (as-of date)."},"source":{"type":"string","description":"Upstream source of the underlying records."},"license":{"type":"string","description":"Usage terms: free with attribution."},"attribution":{"type":"string","description":"Attribution line to reproduce when citing."},"canonicalUrl":{"type":"string","description":"Human page this data mirrors."},"sampleNote":{"type":"string","description":"Present when a metric is suppressed for small sample."},"docs":{"type":"string"}},"required":["source","license","attribution"]},"Meta_data":{"type":"object","description":"API metadata document.","additionalProperties":true},"GeoSummary":{"type":"object","properties":{"name":{"type":"string"},"scope":{"type":"string"},"summary":{"type":"string","description":"One-sentence, quotable, source-attributed statement."},"asOf":{"type":"string","format":"date"},"window":{"type":"string"},"sales12m":{"type":"integer"},"medianPrice12m":{"type":["number","null"],"description":"Median recorded sale price, trailing 12 months. Null if sample below minimum."},"yoyPct":{"type":["number","null"]},"byType":{"type":"object","description":"Per-asset-class medians. Prices are per-unit; $/ft² is only ever computed for houses/whole buildings (never condo/co-op units).","properties":{"houseMedianPpsf":{"type":["number","null"]},"houseSampleN":{"type":"integer"},"condoMedianPrice":{"type":["number","null"]},"condoSampleN":{"type":"integer"},"coopMedianPrice":{"type":["number","null"]},"coopSampleN":{"type":"integer"}}},"classMix":{"type":["array","null"],"items":{"type":"object"}}}},"AreaList":{"type":"object","properties":{"count":{"type":"integer"},"borough":{"type":["string","null"]},"areas":{"type":"array","items":{"type":"object"}}}},"Area":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"borough":{"type":["string","null"]},"summary":{"type":"string"},"asOf":{"type":"string","format":"date"},"sales12m":{"type":"integer"},"medianPrice12m":{"type":["number","null"]},"yoyPct":{"type":["number","null"]},"byType":{"type":"object","description":"Per-asset-class medians. Prices are per-unit; $/ft² is only ever computed for houses/whole buildings (never condo/co-op units).","properties":{"houseMedianPpsf":{"type":["number","null"]},"houseSampleN":{"type":"integer"},"condoMedianPrice":{"type":["number","null"]},"condoSampleN":{"type":"integer"},"coopMedianPrice":{"type":["number","null"]},"coopSampleN":{"type":"integer"}}},"classMix":{"type":["array","null"],"items":{"type":"object"}}}},"History":{"type":"object","properties":{"slug":{"type":"string"},"class":{"type":"string"},"years":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer"},"sales":{"type":"integer"},"medianPrice":{"type":["number","null"]}}}}}},"Property":{"type":"object","properties":{"bbl":{"type":"integer"},"address":{"type":"string"},"borough":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"type":{"type":"string"},"yearBuilt":{"type":["integer","null"]},"lastSale":{"type":["object","null"]},"saleHistory":{"type":"array","items":{"type":"object"}},"assessment":{"type":["object","null"]}}},"RentYield":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"medianSalePrice12m":{"type":["number","null"]},"medianGrossRentMonthly":{"type":["number","null"],"description":"ACS median gross rent (monthly, incl. utilities)."},"renterUnits":{"type":["integer","null"]},"grossRentToPriceYieldPct":{"type":["number","null"],"description":"Median gross rent × 12 ÷ median sale price. Gross ratio, not a cap rate."},"source":{"type":"string"},"sourceNotice":{"type":"string","description":"The Census Bureau's required API notice."},"vintage":{"type":["string","null"]},"note":{"type":"string","description":"Methodology caveat: not investment advice."}}},"RentYieldRanking":{"type":"object","properties":{"order":{"type":"string","enum":["high","low"]},"count":{"type":"integer"},"metric":{"type":"string"},"note":{"type":"string"},"areas":{"type":"array","items":{"type":"object"}},"rentVintage":{"type":["string","null"]},"sourceNotice":{"type":"string","description":"The Census Bureau's required API notice."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}