{"openapi":"3.0.3","info":{"title":"NYC Building Report API","version":"1.0.0","description":"Read-only JSON API for public NYC building reports aggregated from NYC Open Data and related public records. Not an official City of New York service. No authentication is required."},"servers":[{"url":"https://nycbuildingreport.com","description":"NYC Building Report"}],"paths":{"/api/v1/buildings/search":{"get":{"operationId":"searchBuildings","summary":"Search for buildings by address or BIN","description":"Uses the same address resolution as the website search. Returns at most 10 matches. A unique match is not redirected; it is returned in the buildings array.","parameters":[{"name":"address","in":"query","required":true,"description":"Street address (optionally with borough) or a 7-digit BIN.","schema":{"type":"string"},"example":"350 5th Avenue, Manhattan"}],"responses":{"200":{"description":"Search results. The buildings array is empty when nothing matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"examples":{"matches":{"$ref":"#/components/examples/SearchMatches"},"empty":{"$ref":"#/components/examples/SearchEmpty"}}}}},"400":{"description":"Missing or blank address parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}},"405":{"description":"Method not allowed. This API is read-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}}}}},"/api/v1/buildings/{identifier}":{"get":{"operationId":"getBuilding","summary":"Get a public building report","description":"Returns the public-record information shown on the building report page, plus individual records (newest first, limited). Identifier is a 7-digit BIN or borough/slug (for example manhattan/350-5th-avenue). Permits are not imported yet and are always an empty array.","parameters":[{"name":"identifier","in":"path","required":true,"description":"BIN or borough/slug.","schema":{"type":"string"},"examples":{"bin":{"value":"1015862"},"slug":{"value":"manhattan/350-5th-avenue"}}}],"responses":{"200":{"description":"Public building report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingReport"},"examples":{"report":{"$ref":"#/components/examples/BuildingReport"}}}}},"404":{"description":"Building not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}},"405":{"description":"Method not allowed. This API is read-only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Building not found."}}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"SearchResponse":{"type":"object","required":["query","buildings"],"properties":{"query":{"type":"string"},"buildings":{"type":"array","items":{"$ref":"#/components/schemas/BuildingSearchResult"}}}},"BuildingSearchResult":{"type":"object","properties":{"id":{"type":"string","description":"Stable public identifier as borough/slug."},"bin":{"type":"string"},"bbl":{"type":["string","null"]},"formatted_bbl":{"type":["string","null"]},"slug":{"type":"string"},"street_address":{"type":["string","null"]},"borough":{"type":"string"},"neighborhood":{"type":["string","null"]},"url":{"type":"string","format":"uri"}}},"BuildingReport":{"type":"object","properties":{"id":{"type":"string"},"bin":{"type":"string"},"bbl":{"type":["string","null"]},"formatted_bbl":{"type":["string","null"]},"slug":{"type":"string"},"street_address":{"type":["string","null"]},"borough":{"type":"string"},"neighborhood":{"type":["object","null"]},"zip_code":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"bedbug_summary":{"type":["string","null"]},"ranking_summary":{"type":["string","null"]},"alternative_addresses":{"type":"array","items":{"type":"string"}},"property":{"type":"object"},"rankings":{"type":"object"},"counts":{"type":"object"},"included_record_limit":{"type":"integer"},"dob_complaints":{"type":"array","items":{"type":"object"}},"dob_violations":{"type":"array","items":{"type":"object"}},"hpd_violations":{"type":"array","items":{"type":"object"}},"permits":{"type":"array","items":{"type":"object"},"description":"Always empty until a permits dataset is imported."},"bedbug_history":{"type":"array","items":{"type":"object"}},"service_requests":{"type":"array","items":{"type":"object"}},"residential_units":{"type":"array","items":{"type":"object"}},"last_updated":{"type":["string","null"],"format":"date-time"},"source_updated_at":{"type":["string","null"],"format":"date-time"},"attribution":{"type":"object"}}}},"examples":{"SearchMatches":{"summary":"One or more buildings","value":{"query":"350 5th Avenue, Manhattan","buildings":[{"id":"manhattan/350-5th-avenue","bin":"1015862","bbl":"1008350041","formatted_bbl":"1-00835-0041","slug":"350-5th-avenue","street_address":"350 5th Avenue","borough":"Manhattan","neighborhood":null,"url":"https://nycbuildingreport.com/buildings/manhattan/350-5th-avenue"}]}},"SearchEmpty":{"summary":"No matches","value":{"query":"999 Impossible Street, Manhattan","buildings":[]}},"BuildingReport":{"summary":"Building report","value":{"id":"manhattan/350-5th-avenue","bin":"1015862","bbl":"1008350041","formatted_bbl":"1-00835-0041","slug":"350-5th-avenue","street_address":"350 5th Avenue","borough":"Manhattan","neighborhood":null,"zip_code":"10118","url":"https://nycbuildingreport.com/buildings/manhattan/350-5th-avenue","description":"350 5th Avenue is a 102-story building in Manhattan.","bedbug_summary":null,"ranking_summary":null,"alternative_addresses":["350A 5th Avenue"],"property":{"year_built":1931,"number_of_floors":102,"residential_units":null,"total_units":null,"building_class":null,"latitude":40.748441,"longitude":-73.985656},"rankings":{"neighborhood_sale_rank":null,"city_sale_rank":null,"dob_complaint_top_percent":null,"dob_violation_top_percent":null,"hpd_violation_top_percent":null},"counts":{"dob_complaints":0,"dob_violations":0,"hpd_violations":0,"bedbug_reports":0,"service_requests":0,"residential_units":0,"recorded_unit_sales":0,"recorded_unit_sales_total":0.0},"included_record_limit":100,"dob_complaints":[],"dob_violations":[],"hpd_violations":[],"permits":[],"bedbug_history":[],"service_requests":[],"residential_units":[],"last_updated":null,"source_updated_at":null,"attribution":{"text":"Aggregated from NYC Open Data and other public NYC records. Not an official City of New York website.","site":"https://nycbuildingreport.com/"}}}}}}