{"openapi":"3.1.0","info":{"title":"StreetSpy NYC building records API","version":"1.0.0","description":"Read-only NYC housing records for every residential building, from public city data, refreshed nightly. Grades follow methodology 2026.10.3 (https://streetspy.nyc/methodology). Attribution required for public display: \"Data by StreetSpy, streetspy.nyc\" with a link. Terms: https://streetspy.nyc/data/terms.","termsOfService":"https://streetspy.nyc/data/terms","contact":{"name":"StreetSpy","email":"hello@streetspy.nyc","url":"https://streetspy.nyc/data"}},"servers":[{"url":"https://streetspy.nyc/api/v1"}],"tags":[{"name":"Buildings"},{"name":"Neighborhoods"},{"name":"Landlords","description":"Growth plan and above."},{"name":"Changes","description":"Growth plan and above."},{"name":"Account"},{"name":"Widget"}],"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <key>. Free keys at streetspy.nyc/data."},"widgetKey":{"type":"apiKey","in":"query","name":"key","description":"Widget keys only; checked against the page's domain."}},"schemas":{"Source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"Building":{"type":"object","properties":{"id":{"type":"integer"},"address":{"type":"string"},"borough":{"type":"string"},"neighborhood":{"type":["string","null"]},"zip":{"type":["string","null"]},"bbl":{"type":["string","null"],"description":"10-digit borough, block and lot"},"lat":{"type":"number"},"lng":{"type":"number"},"report_url":{"type":"string"},"building_type":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["coop","condo","nycha","rental"]},"label":{"type":"string"}}},{"type":"null"}]},"units":{"type":["integer","null"]},"year_built":{"type":["integer","null"]},"grade":{"type":"object","properties":{"status":{"type":"string","enum":["graded","no_bbl","not_covered"]},"letter":{"type":["string","null"],"enum":["A","B","C","D","F",null]},"score":{"type":["integer","null"]},"label":{"type":"string"},"summary":{"type":"string"},"methodology_version":{"type":"string"}}},"grade_history":{"type":"object","properties":{"recorded_since":{"type":["string","null"],"format":"date","description":"First nightly refresh that recorded grade changes; no history exists before it."},"changes":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"score":{"type":["integer","null"]},"methodology_version":{"type":["string","null"]}}}}}},"hpd_violations":{"type":"object","properties":{"open":{"type":"integer"},"open_by_class":{"type":"object","properties":{"A":{"type":"integer"},"B":{"type":"integer"},"C":{"type":"integer"},"I":{"type":"integer"}}},"rent_impairing_open":{"type":"integer"},"open_per_10_units":{"type":["number","null"]},"issued_last_12_months":{"type":"integer"},"total_on_record":{"type":"integer"},"recently_active":{"type":"boolean"}}},"complaints_311_last_12_months":{"type":"object","properties":{"total":{"type":"integer"},"by_type":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"count":{"type":"integer"}}}}}},"heat_complaints_this_season":{"type":"object","properties":{"season":{"type":"string"},"season_start":{"type":"string","format":"date"},"count":{"type":["integer","null"]}}},"bedbugs":{"type":"object","properties":{"infested_units_last_3_years":{"type":"integer"},"reinfested_last_3_years":{"type":"boolean"}}},"evictions":{"type":"object","properties":{"executed_last_3_years":{"type":"integer"},"executed_total":{"type":"integer"},"last_executed":{"type":["string","null"]}}},"litigation":{"type":"object","properties":{"total":{"type":"integer"},"open":{"type":"integer"},"harassment_findings":{"type":"integer"}}},"dob_violations":{"type":"object","properties":{"open":{"type":"integer"},"total":{"type":"integer"}}},"rent_stabilization":{"type":"object","properties":{"status":{"type":"string","enum":["stabilized","none_on_tax_bill","not_on_file","could_not_verify"]},"units":{"type":["integer","null"]},"of_units":{"type":["integer","null"]},"tax_bill_year":{"type":["integer","null"]}}},"hpd_registration":{"type":"object","properties":{"status":{"type":"string","enum":["registered","expired","not_on_file"]},"registration_id":{"type":["string","null"]},"last_registered":{"type":["string","null"]},"expires":{"type":["string","null"]}}},"owner":{"type":"object","properties":{"owner_entity":{"type":["string","null"],"description":"The registered owner when it is a company; null for an individual owner"},"owner_kind":{"type":["string","null"],"enum":["entity","individual",null]},"head_officer":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"label":{"const":"head officer on HPD registrations"},"registration_id":{"type":["string","null"]},"source":{"type":"string"}}},{"type":"null"}]},"managing_agent":{"type":["string","null"],"description":"Company name only"},"portfolio_url":{"type":["string","null"]}}}}},"LandlordTotals":{"type":"object","properties":{"buildings":{"type":"integer"},"units":{"type":"integer"},"open_violations":{"type":"integer"},"open_class_c":{"type":"integer"},"open_per_10_units":{"type":["number","null"]},"complaints_311_last_12_months":{"type":"integer"},"evictions_last_3_years":{"type":"integer"},"bedbug_units_last_3_years":{"type":"integer"},"harassment_findings":{"type":"integer"},"buildings_graded_d_or_f":{"type":"integer"},"average_score":{"type":["integer","null"]}}},"LandlordRankEntry":{"type":"object","properties":{"rank":{"type":"integer"},"kind":{"type":"string","enum":["head_officer","owner_entity"]},"name":{"type":"string"},"label":{"type":"string","enum":["head officer on HPD registrations","owner entity"]},"slug":{"type":["string","null"]},"url":{"type":["string","null"]},"totals":{"$ref":"#/components/schemas/LandlordTotals"},"owner_entities":{"type":"integer"},"largest_owner_entities":{"type":"array","items":{"type":"string"}}}},"PortfolioBuilding":{"type":"object","properties":{"id":{"type":"integer"},"address":{"type":"string"},"borough":{"type":"string"},"neighborhood":{"type":["string","null"]},"units":{"type":["integer","null"]},"open_violations":{"type":"integer"},"open_class_c":{"type":"integer"},"grade":{"type":["string","null"]},"score":{"type":["integer","null"]},"report_url":{"type":"string"}}},"Landlord":{"type":"object","properties":{"kind":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"slug":{"type":["string","null"]},"url":{"type":["string","null"]},"rank":{"type":["integer","null"]},"ranked_among":{"type":"integer"},"totals":{"$ref":"#/components/schemas/LandlordTotals"},"owner_entities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"buildings":{"type":"integer"},"url":{"type":["string","null"]}}}},"head_officers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"buildings":{"type":"integer"}}}},"buildings":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioBuilding"}}}},"LandlordChange":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"url":{"type":["string","null"]},"status":{"type":"string","enum":["entered","left","changed"]},"rank":{"type":["integer","null"]},"previous_rank":{"type":["integer","null"]},"rank_change":{"type":["integer","null"],"description":"previous_rank minus rank: positive moved toward #1"},"open_violations":{"type":["integer","null"]},"previous_open_violations":{"type":["integer","null"]},"open_violations_change":{"type":["integer","null"]},"open_per_10_units":{"type":["number","null"]},"previous_open_per_10_units":{"type":["number","null"]},"buildings":{"type":["integer","null"]},"units":{"type":["integer","null"]}}},"NeighborhoodListItem":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"borough":{"type":"string"},"graded_buildings":{"type":"integer"},"median_open_per_10_units":{"type":["number","null"]},"url":{"type":"string"}}},"Neighborhood":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"borough":{"type":"string"},"summary":{"type":"string"},"buildings":{"type":"integer"},"graded_buildings":{"type":"integer"},"grade_distribution":{"type":"object","additionalProperties":{"type":"integer"}},"units":{"type":"integer"},"open_violations":{"type":"integer"},"open_class_c":{"type":"integer"},"median_open_per_10_units":{"type":["number","null"]},"borough_median_open_per_10_units":{"type":["number","null"]},"average_score":{"type":["integer","null"]},"complaints_311_last_12_months":{"type":"integer"},"top_311_last_12_months":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"count":{"type":"integer"}}}},"evictions_last_3_years":{"type":"integer"},"bedbug_units_last_3_years":{"type":"integer"},"rent_stabilized_units":{"type":["integer","null"]},"worst_five":{"type":"array","items":{"type":"string"}},"best_five":{"type":"array","items":{"type":"string"}},"largest_landlords":{"type":"array"},"list_rule":{"type":"string"},"url":{"type":"string"}}},"Change":{"type":"object","properties":{"type":{"type":"string","enum":["grade_change","hpd_violation","complaint_311","dob_violation","eviction","litigation"]},"date":{"type":"string","format":"date"},"bbl":{"type":["string","null"]},"building_ids":{"type":"array","items":{"type":"integer"}},"record_id":{"type":"string"},"details":{"type":"object"}}},"Usage":{"type":"object","properties":{"plan":{"type":"string"},"monthly_quota":{"type":"integer"},"used_this_period":{"type":"integer"},"period_start":{"type":"string","format":"date"},"resets_on":{"type":"string","format":"date"},"rate_per_minute":{"type":"integer"},"daily":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"calls":{"type":"integer"},"calls_429":{"type":"integer"}}}}}},"WidgetGrade":{"type":"object","properties":{"id":{"type":"integer"},"address":{"type":"string"},"grade":{"type":"object","properties":{"status":{"type":"string"},"letter":{"type":["string","null"]},"label":{"type":"string"}}},"open_violations":{"type":"integer"},"report_url":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}},"paths":{"/buildings/lookup":{"get":{"operationId":"lookupBuilding","summary":"Look up a building by address","description":"An NYC street address to the StreetSpy building and its full record: grade and grade history, open HPD violations by class, 311 housing complaints by type for 12 months, heat complaints this season, HPD registration status and expiry, rent-stabilized units, owner entity and head officer as named on the registration, building type, methodology version and records-as-of date.","tags":["Buildings"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":true,"parameters":[{"name":"address","in":"query","required":true,"description":"Street address starting with the house number, for example 1000 Grand Concourse. Unit numbers are ignored.","schema":{"type":"string"}},{"name":"borough","in":"query","required":false,"description":"Manhattan, Brooklyn, Queens, Bronx or Staten Island, when the street exists in more than one borough.","schema":{"type":"string","enum":["Manhattan","Brooklyn","Queens","Bronx","Staten Island"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Building"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/buildings/bbl/{bbl}":{"get":{"operationId":"buildingsByBbl","summary":"Buildings on a tax lot (BBL)","description":"Every StreetSpy building on a borough, block and lot (usually one; a lot can hold several buildings). Each has the same record as the lookup. At most 10.","tags":["Buildings"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":true,"parameters":[{"name":"bbl","in":"path","required":true,"description":"10-digit BBL: borough (1), block (5), lot (4). An 11-digit form with a 5-digit lot is accepted.","schema":{"type":"string","pattern":"^[1-5][0-9]{9,10}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Building"}},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/buildings/{id}":{"get":{"operationId":"getBuilding","summary":"A building by StreetSpy id","description":"The same record as the lookup, by the id in streetspy.nyc/building/{id}.","tags":["Buildings"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":true,"parameters":[{"name":"id","in":"path","required":true,"description":"StreetSpy building id.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Building"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/neighborhoods":{"get":{"operationId":"listNeighborhoods","summary":"NYC neighborhoods","description":"Every NYC neighborhood StreetSpy covers, with graded buildings and the median open HPD violations per 10 units (buildings with 3+ units).","tags":["Neighborhoods"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":true,"parameters":[{"name":"borough","in":"query","required":false,"description":"Only this borough.","schema":{"type":"string","enum":["Manhattan","Brooklyn","Queens","Bronx","Staten Island"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NeighborhoodListItem"}},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/neighborhoods/{slug}":{"get":{"operationId":"getNeighborhood","summary":"One neighborhood's aggregates","description":"The figures on the neighborhood page: graded buildings and grade mix, median open violations per 10 units against the borough, rent-stabilized units, top 311 complaint types, the five worst and best rental buildings per 10 units, and the largest landlords.","tags":["Neighborhoods"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":true,"parameters":[{"name":"slug","in":"path","required":true,"description":"Neighborhood slug, as in streetspy.nyc/neighborhoods/{borough}/{slug} (for example concourse).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Neighborhood"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/landlords":{"get":{"operationId":"listLandlords","summary":"The landlord ranking","description":"Portfolios grouped by the head officer on HPD registrations (or the owner entity when there is none), as on streetspy.nyc/landlords. The floor is never lower than 3 buildings and 50 units. Owner entities are named only when the name is a company.","tags":["Landlords"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"sort","in":"query","required":false,"description":"per_10_units (default): open HPD violations per 10 units. open_violations: the total.","schema":{"type":"string","enum":["per_10_units","open_violations"],"default":"per_10_units"}},{"name":"min_buildings","in":"query","required":false,"description":"At least 3.","schema":{"type":"integer","minimum":3,"default":3}},{"name":"min_units","in":"query","required":false,"description":"At least 50.","schema":{"type":"integer","minimum":50,"default":50}},{"name":"borough","in":"query","required":false,"description":"Totals within one borough.","schema":{"type":"string","enum":["Manhattan","Brooklyn","Queens","Bronx","Staten Island"]}},{"name":"limit","in":"query","required":false,"description":"Rows per page (default 50, at most 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Rows to skip.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LandlordRankEntry"}},"page":{"type":"object"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/landlords/changes":{"get":{"operationId":"landlordChanges","summary":"Week-over-week ranking changes","description":"Entries of the weekly landlord ranking snapshot (taken Sundays, 52 weeks kept) whose rank or open HPD violations changed against the snapshot `weeks` weeks earlier.","tags":["Landlords"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"weeks","in":"query","required":false,"description":"Compare against this many weeks back (1 to 52).","schema":{"type":"integer","minimum":1,"maximum":52,"default":1}},{"name":"kind","in":"query","required":false,"description":"operator (default): the /landlords grouping. entity: grouped by owner entity only.","schema":{"type":"string","enum":["operator","entity"],"default":"operator"}},{"name":"limit","in":"query","required":false,"description":"Rows per page (default 200, at most 1000).","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LandlordChange"}},"page":{"type":"object"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/landlords.csv":{"get":{"operationId":"landlordsCsv","summary":"Weekly landlord ranking as CSV","description":"The latest weekly ranking snapshot with the same floor and columns as the public press CSV (/api/rankings/landlords.csv), plus week-over-week columns: week_of, previous_week, previous_rank, rank_change (previous_rank minus rank), previous_open_hpd_violations, open_hpd_violations_change, previous_open_per_10_units. records_as_of, methodology_version and sources are in the X-Records-As-Of, X-Methodology-Version and X-Sources headers.","tags":["Landlords"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"kind","in":"query","required":false,"description":"operator (default) or entity.","schema":{"type":"string","enum":["operator","entity"],"default":"operator"}}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/landlords/person/{slug}":{"get":{"operationId":"getHeadOfficerPortfolio","summary":"A head officer's portfolio","description":"Every building whose HPD registration names this head officer, across the owner entities it is held through. Only head officers at or above the ranking floor (3 buildings, 50 units) are returned, always labeled \"head officer on HPD registrations\".","tags":["Landlords"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug in streetspy.nyc/landlords/person/{slug}.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Landlord"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/landlords/{slug}":{"get":{"operationId":"getEntityPortfolio","summary":"An owner entity's portfolio","description":"An owner entity (company) by the slug in streetspy.nyc/landlords/{slug}: totals, rank when ranked, the head officers on its registrations (labeled) and its buildings. Individual owners are not returned by name.","tags":["Landlords"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"slug","in":"path","required":true,"description":"The slug in streetspy.nyc/landlords/{slug}.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Landlord"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changes":{"get":{"operationId":"listChanges","summary":"New records and grade changes since a date","description":"New HPD violations, 311 housing complaints, DOB violations, executed residential evictions, HPD housing litigation and StreetSpy grade changes on or after `since`, oldest first, paged with next_cursor. City-wide, since can be at most 31 days back; with building_id, up to 5 years. Poll daily after the nightly refresh (about 2 am New York) with since set to your last poll date. Apartment numbers, names and free-text from residents are never included.","tags":["Changes"],"security":[{"bearerKey":[]}],"x-min-plan":"growth","x-counted":true,"parameters":[{"name":"since","in":"query","required":true,"description":"YYYY-MM-DD, inclusive (the record's own date: issued, filed, executed or changed).","schema":{"type":"string","format":"date"}},{"name":"building_id","in":"query","required":false,"description":"Only this StreetSpy building (records on its tax lot).","schema":{"type":"integer","minimum":1}},{"name":"types","in":"query","required":false,"description":"Comma-separated: grade_change, hpd_violation, complaint_311, dob_violation, eviction, litigation. Default all.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor from the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows per page (default 100, at most 500).","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Change"}},"page":{"type":"object"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"operationId":"getUsage","summary":"This key's plan and usage","description":"Plan, monthly quota, calls used this period and the last 30 days. Not counted against the quota. Quotas reset on the first of each month, New York time.","tags":["Account"],"security":[{"bearerKey":[]}],"x-min-plan":"free","x-counted":false,"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Usage"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/widget":{"get":{"operationId":"widgetGrade","summary":"Grade for the embeddable widget","description":"Used by streetspy.nyc/widget.js. Widget keys are tied to one website domain: the request's Origin (or Referer) must be that domain or a subdomain. The key goes in the `key` query parameter because it is public in the page.","tags":["Widget"],"security":[{"widgetKey":[]}],"x-min-plan":"widget","x-counted":true,"parameters":[{"name":"key","in":"query","required":true,"description":"Widget key.","schema":{"type":"string"}},{"name":"building_id","in":"query","required":false,"description":"StreetSpy building id (or give address).","schema":{"type":"integer"}},{"name":"address","in":"query","required":false,"description":"Street address (or give building_id).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WidgetGrade"},"records_as_of":{"type":["string","null"],"format":"date","description":"The date the underlying city records are current through."},"methodology_version":{"type":"string","example":"2026.10.3"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"attribution":{"type":"object","properties":{"text":{"const":"Data by StreetSpy, streetspy.nyc"},"url":{"type":"string"},"required":{"type":"string"}}}},"required":["data","records_as_of","methodology_version","sources","attribution"]}}}},"400":{"description":"A parameter is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, or the key is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key is revoked, on a plan without this endpoint, or (widget) used on another domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing matched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-minute rate limit (Retry-After header) or the monthly quota (resets on the 1st, New York time). Never charged as overage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error; reported automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}