{ "openapi": "3.1.0", "info": { "title": "NYC API", "description": "Decision-ready intelligence on NYC properties, restaurants, and buildings. Health grades, violations, ownership, permits — via REST API.\n\nCredits: Each API call costs 1 credit. When credits reach 0, requests return 402 Payment Required until your next billing cycle resets them. No overage charges.\n\nCredit Costs per Endpoint:\n- Most endpoints: 1 credit per call\n- /api/owner/portfolio: 1 credit (queries multiple data sources per property)\n- /api/violations/profile: 1 credit (queries 5 datasets in parallel)", "version": "1.4.0", "contact": { "email": "support@matchup.dev", "url": "https://nycapi.app" } }, "servers": [ { "url": "https://nycapi.app", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Property", "description": "Property intelligence — ownership, assessments, transactions, and violation counts" }, { "name": "Venue", "description": "Restaurant and venue intelligence — health grades, inspections, permits, and licenses" }, { "name": "Violations", "description": "Building violations and complaints — DOB, HPD, ECB, and 311 data" }, { "name": "Owner", "description": "Portfolio-level intelligence — aggregate violations, assessments, and lien exposure across all properties owned by an entity" }, { "name": "Admin", "description": "Usage analytics and account management" } ], "paths": { "/api/property/lookup": { "get": { "operationId": "propertyLookup", "summary": "Full property profile", "description": "Returns a comprehensive property profile including ownership, assessment, recent ACRIS transactions, liens, and DOB/HPD violation counts. Provide either address+borough, a 10-digit BBL, or block+lot+borough.", "tags": [ "Property" ], "parameters": [ { "name": "address", "in": "query", "description": "Street address (e.g., \"280 Broadway\")", "schema": { "type": "string" }, "example": "280 Broadway" }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] }, "example": "Manhattan" }, { "name": "bbl", "in": "query", "description": "10-digit Borough-Block-Lot identifier", "schema": { "type": "string", "pattern": "^[1-5]\\d{9}$" }, "example": "1001680001" }, { "name": "block", "in": "query", "description": "Tax block number", "schema": { "type": "string" } }, { "name": "lot", "in": "query", "description": "Tax lot number", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Property profile found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PropertyProfile" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/property/search": { "get": { "operationId": "propertySearch", "summary": "Search PLUTO property records", "description": "Search NYC properties by address, owner name, borough, zipcode, or building class. Returns paginated property summaries.", "tags": [ "Property" ], "parameters": [ { "name": "address", "in": "query", "description": "Street address substring match", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Owner name substring match", "schema": { "type": "string" } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } }, { "name": "building_class", "in": "query", "description": "1-2 character building class code (e.g., R4, A5)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Properties found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "results", "total", "limit", "offset" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PropertySummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/venue/health": { "get": { "operationId": "venueHealth", "summary": "Restaurant health inspection profile", "description": "Returns the full health inspection history for a NYC restaurant, including all inspections, grades, scores, and individual violations. Query by restaurant name, address, or CAMIS ID.", "tags": [ "Venue" ], "parameters": [ { "name": "name", "in": "query", "description": "Restaurant name (DBA) — substring match", "schema": { "type": "string" }, "example": "PETER LUGER" }, { "name": "address", "in": "query", "description": "Street address (e.g., \"178 Broadway\")", "schema": { "type": "string" } }, { "name": "camis", "in": "query", "description": "DOH CAMIS identifier (numeric)", "schema": { "type": "string" }, "example": "40364296" }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restaurant health profile found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VenueHealthProfile" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/venue/search": { "get": { "operationId": "venueSearch", "summary": "Search NYC restaurants", "description": "Search restaurants by cuisine, grade, borough, or zipcode. Returns deduplicated venue summaries (one per CAMIS, most recent grade).", "tags": [ "Venue" ], "parameters": [ { "name": "cuisine", "in": "query", "description": "Cuisine type substring match (e.g., \"Italian\", \"Chinese\")", "schema": { "type": "string" } }, { "name": "grade", "in": "query", "description": "DOH letter grade", "schema": { "type": "string", "enum": [ "A", "B", "C" ] } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit100" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Restaurants found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "results", "total", "limit", "offset" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/VenueSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/venue/permits": { "get": { "operationId": "venuePermits", "summary": "Venue permits and licenses", "description": "Returns sidewalk cafe permits and DCA business licenses for a NYC venue. Queries by name and/or address.", "tags": [ "Venue" ], "parameters": [ { "name": "name", "in": "query", "description": "Business name — substring match", "schema": { "type": "string" } }, { "name": "address", "in": "query", "description": "Street address (e.g., \"178 Broadway\")", "schema": { "type": "string" } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Permits and licenses found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VenuePermitProfile" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/violations/dob": { "get": { "operationId": "violationsDob", "summary": "DOB + ECB violations", "description": "Returns DOB standard violations and OATH/ECB penalties for a building. Query by address, block+lot, or BIN.", "tags": [ "Violations" ], "parameters": [ { "name": "address", "in": "query", "description": "Street address (e.g., \"100 Broadway\")", "schema": { "type": "string" } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "block", "in": "query", "description": "Tax block number", "schema": { "type": "string" } }, { "name": "lot", "in": "query", "description": "Tax lot number", "schema": { "type": "string" } }, { "name": "bin", "in": "query", "description": "Building Identification Number", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "DOB violations found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "dob_violations", "ecb_violations", "totals", "limit", "offset" ], "properties": { "dob_violations": { "type": "array", "items": { "$ref": "#/components/schemas/DobViolationSummary" } }, "ecb_violations": { "type": "array", "items": { "$ref": "#/components/schemas/EcbViolationSummary" } }, "totals": { "type": "object", "properties": { "dob": { "type": "integer" }, "ecb": { "type": "integer" }, "total": { "type": "integer" } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/violations/hpd": { "get": { "operationId": "violationsHpd", "summary": "HPD violations", "description": "Returns HPD housing violations for a building. Filterable by violation class (A/B/C). Query by address or block+lot.", "tags": [ "Violations" ], "parameters": [ { "name": "address", "in": "query", "description": "Street address (e.g., \"100 Broadway\")", "schema": { "type": "string" } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } }, { "name": "block", "in": "query", "description": "Tax block number", "schema": { "type": "string" } }, { "name": "lot", "in": "query", "description": "Tax lot number", "schema": { "type": "string" } }, { "name": "class", "in": "query", "description": "Violation class filter: A (non-hazardous), B (hazardous), C (immediately hazardous)", "schema": { "type": "string", "enum": [ "A", "B", "C" ] } }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "HPD violations found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "results", "limit", "offset" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/HpdViolationSummary" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/violations/complaints": { "get": { "operationId": "violationsComplaints", "summary": "311 building complaints", "description": "Returns 311 building-related complaints (plumbing, heating, water leak, etc.) for a given address. Filterable by complaint type.", "tags": [ "Violations" ], "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Street address (e.g., \"100 Broadway\")", "schema": { "type": "string" } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Complaint type filter (e.g., HEATING, PLUMBING, WATER LEAK)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit200" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "311 complaints found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "results", "limit", "offset" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Complaint311Summary" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/violations/profile": { "get": { "operationId": "violationsProfile", "summary": "Combined building violation profile", "description": "Returns a comprehensive violation profile combining DOB violations, OATH/ECB violations, HPD violations, DOB complaints, and 311 building complaints for a single address.", "tags": [ "Violations" ], "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Street address (e.g., \"100 Broadway\")", "schema": { "type": "string" } }, { "name": "borough", "in": "query", "description": "NYC borough name", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "zipcode", "in": "query", "description": "5-digit zip code", "schema": { "type": "string" } }, { "name": "block", "in": "query", "description": "Tax block number", "schema": { "type": "string" } }, { "name": "lot", "in": "query", "description": "Tax lot number", "schema": { "type": "string" } }, { "name": "bin", "in": "query", "description": "Building Identification Number", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Violation profile found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/BuildingViolationProfile" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/owner/portfolio": { "get": { "operationId": "ownerPortfolio", "summary": "Owner portfolio intelligence", "description": "Returns all properties owned by an entity with aggregate violation counts, assessed values, and borough distribution. Queries PLUTO for matching properties, then fetches DOB/ECB/HPD violation counts for each.", "tags": [ "Owner" ], "parameters": [ { "name": "owner", "in": "query", "required": true, "description": "Owner name — substring match (e.g., \"NYC HOUSING AUTHORITY\")", "schema": { "type": "string" }, "example": "NYC HOUSING AUTHORITY" }, { "name": "borough", "in": "query", "description": "NYC borough name filter", "schema": { "type": "string", "enum": [ "Manhattan", "Brooklyn", "Queens", "Bronx", "Staten Island" ] } }, { "name": "limit", "in": "query", "description": "Maximum properties to return (default 50, max 200)", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Owner portfolio found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/OwnerPortfolio" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 1 } }, "/api/admin/usage": { "get": { "operationId": "adminUsage", "summary": "API key usage analytics", "description": "Returns usage analytics for the authenticated API key — daily request counts, credit consumption, per-endpoint breakdowns, error rates, and average response times.", "tags": [ "Admin" ], "parameters": [ { "name": "days", "in": "query", "description": "Lookback window in days (default 7, max 90)", "schema": { "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, { "name": "endpoint", "in": "query", "description": "Filter to a specific endpoint path (e.g., \"/api/venue/health\")", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage analytics returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsageAnalytics" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-credit-cost": 0 } }, "/api/keys/free": { "post": { "operationId": "createFreeKey", "summary": "Provision a free-tier API key", "description": "Creates a free API key (50 credits, 5 req/min) for testing against real NYC data. No Stripe required. One key per email.", "tags": [ "Admin" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address for the key owner" } } } } } }, "responses": { "201": { "description": "Free API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key": { "type": "string", "description": "The API key (shown once)" }, "tier": { "type": "string", "enum": [ "free" ] }, "credits": { "type": "integer" }, "rate_limit": { "type": "string" }, "note": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "description": "A free key already exists for this email" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 0 } }, "/api/enterprise/inquiry": { "post": { "operationId": "enterpriseInquiry", "summary": "Submit an enterprise pricing inquiry", "description": "Logs a sales inquiry for custom volume, SLA, or white-label pricing. No authentication required.", "tags": [ "Admin" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "use_case": { "type": "string" }, "volume": { "type": "string", "description": "Estimated monthly API calls" } } } } } }, "responses": { "201": { "description": "Inquiry received", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-credit-cost": 0 } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key starting with mv_live_ — obtain at https://nycapi.app/signup" } }, "parameters": { "Limit100": { "name": "limit", "in": "query", "description": "Maximum results per page (default 20, max 100)", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, "Limit200": { "name": "limit", "in": "query", "description": "Maximum results per page (default 50, max 200)", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "Offset": { "name": "offset", "in": "query", "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0, "minimum": 0 } } }, "schemas": { "Meta": { "type": "object", "required": [ "source", "updated", "query_ms" ], "properties": { "source": { "type": "string", "description": "Data source(s) used" }, "updated": { "type": "string", "format": "date-time" }, "query_ms": { "type": "integer", "description": "Server-side query time in milliseconds" }, "credits_remaining": { "type": "integer", "description": "API credits remaining on your key" } } }, "ErrorDetail": { "type": "object", "required": [ "type", "title", "status", "detail" ], "description": "RFC 7807 Problem Details", "properties": { "type": { "type": "string", "format": "uri", "description": "URI identifying the problem type" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } }, "PropertyProfile": { "type": "object", "required": [ "bbl", "address", "property", "assessment", "recent_transactions", "liens", "violation_counts" ], "properties": { "bbl": { "type": "string", "description": "10-digit Borough-Block-Lot" }, "address": { "type": "object", "properties": { "full": { "type": "string" }, "borough": { "type": "string" }, "zipcode": { "type": "string" } } }, "owner": { "type": [ "string", "null" ] }, "property": { "type": "object", "properties": { "building_class": { "type": [ "string", "null" ] }, "land_use": { "type": [ "string", "null" ] }, "zoning": { "type": [ "string", "null" ] }, "year_built": { "type": [ "number", "null" ] }, "year_altered": { "type": [ "number", "null" ] }, "num_buildings": { "type": [ "number", "null" ] }, "num_floors": { "type": [ "number", "null" ] }, "residential_units": { "type": [ "number", "null" ] }, "total_units": { "type": [ "number", "null" ] }, "lot_area_sqft": { "type": [ "number", "null" ] }, "building_area_sqft": { "type": [ "number", "null" ] } } }, "assessment": { "type": "object", "properties": { "land_value": { "type": [ "number", "null" ] }, "total_value": { "type": [ "number", "null" ] }, "exempt_value": { "type": [ "number", "null" ] } } }, "coordinates": { "oneOf": [ { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, { "type": "null" } ] }, "recent_transactions": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyTransaction" } }, "liens": { "type": "object", "properties": { "active_count": { "type": "integer" }, "has_liens": { "type": "boolean" } } }, "violation_counts": { "type": "object", "properties": { "dob": { "type": "integer" }, "hpd": { "type": "integer" } } }, "sources_unavailable": { "type": "array", "items": { "type": "string" }, "description": "Data sources that failed during this request. Present only when partial results are returned." } } }, "PropertyTransaction": { "type": "object", "properties": { "document_id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "ACRIS document type code" }, "type_category": { "type": "string", "enum": [ "deed", "mortgage", "lien", "other" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "recorded_date": { "type": [ "string", "null" ], "format": "date" }, "amount": { "type": [ "number", "null" ] } } }, "PropertySummary": { "type": "object", "properties": { "bbl": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "borough": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "owner": { "type": [ "string", "null" ] }, "building_class": { "type": [ "string", "null" ] }, "year_built": { "type": [ "number", "null" ] }, "total_units": { "type": [ "number", "null" ] }, "lot_area_sqft": { "type": [ "number", "null" ] }, "assessed_total": { "type": [ "number", "null" ] } } }, "VenueHealthProfile": { "type": "object", "required": [ "camis", "name", "address", "cuisine", "inspections", "total_inspections", "risk_assessment" ], "properties": { "camis": { "type": "string", "description": "DOH unique restaurant identifier" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "building": { "type": "string" }, "street": { "type": "string" }, "borough": { "type": "string" }, "zipcode": { "type": "string" } } }, "phone": { "type": [ "string", "null" ] }, "cuisine": { "type": "string" }, "current_grade": { "type": [ "string", "null" ], "description": "Most recent letter grade (A/B/C), excludes pending (P) and grade pending (Z)" }, "current_score": { "type": [ "integer", "null" ], "description": "Most recent inspection score (lower is better)" }, "grade_date": { "type": [ "string", "null" ], "format": "date" }, "inspections": { "type": "array", "items": { "$ref": "#/components/schemas/VenueInspection" } }, "total_inspections": { "type": "integer" }, "risk_assessment": { "$ref": "#/components/schemas/VenueRiskAssessment" } } }, "VenueRiskAssessment": { "type": "object", "required": [ "score", "level", "factors" ], "description": "Composite risk assessment (0–100) computed from inspection history. Higher score = higher risk.", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Composite risk score — 0 (safest) to 100 (riskiest)" }, "level": { "type": "string", "enum": [ "low", "moderate", "high", "critical" ], "description": "Human-readable risk level" }, "factors": { "type": "object", "description": "Breakdown of how the score was computed", "properties": { "grade": { "type": "object", "properties": { "value": { "type": [ "string", "null" ] }, "points": { "type": "integer", "description": "0–30 points. A=0, B=15, C=30" } } }, "inspection_score": { "type": "object", "properties": { "value": { "type": [ "integer", "null" ] }, "points": { "type": "integer", "description": "0–20 points. Based on DOH scoring thresholds" } } }, "critical_violations": { "type": "object", "properties": { "count": { "type": "integer" }, "points": { "type": "integer", "description": "0–20 points. 0 violations=0, 1-2=10, 3+=20" } } }, "trajectory": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "improving", "stable", "declining", "unknown" ] }, "points": { "type": "integer", "description": "0–15 points. Improving=0, Stable=5, Declining=15" } } }, "recency": { "type": "object", "properties": { "days_since_last": { "type": [ "integer", "null" ] }, "points": { "type": "integer", "description": "0–15 points. <6mo=0, 6-12mo=5, 12-18mo=10, 18mo+=15" } } } } } } }, "VenueInspection": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "type": { "type": [ "string", "null" ] }, "score": { "type": [ "integer", "null" ] }, "grade": { "type": [ "string", "null" ] }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/VenueViolation" } } } }, "VenueViolation": { "type": "object", "properties": { "code": { "type": "string", "description": "DOH violation code" }, "description": { "type": "string" }, "critical": { "type": "boolean" } } }, "VenueSummary": { "type": "object", "properties": { "camis": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "building": { "type": "string" }, "street": { "type": "string" }, "borough": { "type": "string" }, "zipcode": { "type": "string" } } }, "cuisine": { "type": "string" }, "current_grade": { "type": [ "string", "null" ] }, "current_score": { "type": [ "integer", "null" ] }, "last_inspection_date": { "type": [ "string", "null" ], "format": "date" } } }, "VenuePermitProfile": { "type": "object", "required": [ "business_name", "address", "business_licenses" ], "properties": { "business_name": { "type": "string" }, "address": { "type": "object", "properties": { "building": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zipcode": { "type": "string" } } }, "sidewalk_cafe": { "oneOf": [ { "$ref": "#/components/schemas/SidewalkCafePermit" }, { "type": "null" } ] }, "business_licenses": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessLicense" } } } }, "SidewalkCafePermit": { "type": "object", "properties": { "license_number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "Enclosed, Unenclosed, or Small Sidewalk Cafe" }, "status": { "type": [ "string", "null" ] }, "tables": { "type": [ "integer", "null" ] }, "chairs": { "type": [ "integer", "null" ] }, "area_sq_ft": { "type": [ "number", "null" ] }, "expiration_date": { "type": [ "string", "null" ], "format": "date" } } }, "BusinessLicense": { "type": "object", "properties": { "license_number": { "type": [ "string", "null" ] }, "license_type": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "created_date": { "type": [ "string", "null" ], "format": "date" }, "expiration_date": { "type": [ "string", "null" ], "format": "date" } } }, "DobViolationSummary": { "type": "object", "properties": { "violation_number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "disposition": { "type": [ "string", "null" ] } } }, "EcbViolationSummary": { "type": "object", "properties": { "ecb_violation_number": { "type": [ "string", "null" ] }, "ecb_violation_status": { "type": [ "string", "null" ] }, "violation_type": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "penalty_imposed": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "balance_due": { "type": [ "number", "null" ] }, "respondent_name": { "type": [ "string", "null" ] }, "infraction_codes": { "type": [ "string", "null" ] }, "certification_status": { "type": [ "string", "null" ] } } }, "HpdViolationSummary": { "type": "object", "properties": { "violation_id": { "type": [ "string", "null" ] }, "class": { "type": [ "string", "null" ], "description": "A=non-hazardous, B=hazardous, C=immediately hazardous" }, "date": { "type": [ "string", "null" ], "format": "date" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "status_date": { "type": [ "string", "null" ], "format": "date" }, "nov_type": { "type": [ "string", "null" ] }, "rent_impairing": { "type": "boolean" } } }, "Complaint311Summary": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "created_date": { "type": [ "string", "null" ], "format": "date" }, "closed_date": { "type": [ "string", "null" ], "format": "date" }, "type": { "type": [ "string", "null" ] }, "descriptor": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "agency": { "type": [ "string", "null" ] } } }, "DobComplaintSummary": { "type": "object", "properties": { "complaint_number": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "format": "date" }, "category": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "disposition_date": { "type": [ "string", "null" ], "format": "date" }, "disposition_code": { "type": [ "string", "null" ] }, "inspection_date": { "type": [ "string", "null" ], "format": "date" } } }, "BuildingViolationProfile": { "type": "object", "required": [ "address", "dob_violations", "ecb_violations", "hpd_violations", "dob_complaints", "complaints_311", "totals" ], "properties": { "address": { "type": "object", "properties": { "house_number": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "borough": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "lot": { "type": [ "string", "null" ] } } }, "dob_violations": { "type": "array", "items": { "$ref": "#/components/schemas/DobViolationSummary" } }, "ecb_violations": { "type": "array", "items": { "$ref": "#/components/schemas/EcbViolationSummary" } }, "hpd_violations": { "type": "array", "items": { "$ref": "#/components/schemas/HpdViolationSummary" } }, "dob_complaints": { "type": "array", "items": { "$ref": "#/components/schemas/DobComplaintSummary" } }, "complaints_311": { "type": "array", "items": { "$ref": "#/components/schemas/Complaint311Summary" } }, "totals": { "type": "object", "properties": { "dob": { "type": "integer" }, "ecb": { "type": "integer" }, "hpd": { "type": "integer" }, "dob_complaints": { "type": "integer" }, "complaints_311": { "type": "integer" }, "total": { "type": "integer" }, "truncated": { "type": "object", "description": "Present when any section hit its query limit", "properties": { "dob": { "type": "boolean" }, "ecb": { "type": "boolean" }, "hpd": { "type": "boolean" }, "dob_complaints": { "type": "boolean" }, "complaints_311": { "type": "boolean" } } } } }, "trends": { "type": "object", "description": "Temporal analysis of violations (DOB + ECB + HPD). Present when at least one violation has a date.", "properties": { "earliest_date": { "type": [ "string", "null" ], "format": "date" }, "most_recent_date": { "type": [ "string", "null" ], "format": "date" }, "span_days": { "type": [ "integer", "null" ], "description": "Days between earliest and most recent violation" }, "violations_per_year": { "type": [ "number", "null" ], "description": "Average violations per year across the span" }, "by_year": { "type": "object", "description": "Year-over-year violation counts (DOB + ECB + HPD combined)", "additionalProperties": { "type": "integer" } } } }, "sources_unavailable": { "type": "array", "items": { "type": "string" }, "description": "Data sources that failed during this request. Present only when partial results are returned." } } }, "OwnerPortfolio": { "type": "object", "required": [ "owner_query", "property_count", "properties", "aggregate" ], "properties": { "owner_query": { "type": "string" }, "property_count": { "type": "integer" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "bbl": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "borough": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "building_class": { "type": [ "string", "null" ] }, "year_built": { "type": [ "number", "null" ] }, "total_units": { "type": [ "number", "null" ] }, "lot_area_sqft": { "type": [ "number", "null" ] }, "assessed_total": { "type": [ "number", "null" ] }, "assessed_land": { "type": [ "number", "null" ] }, "exempt_total": { "type": [ "number", "null" ] }, "violation_counts": { "type": "object", "properties": { "dob": { "type": "integer" }, "ecb": { "type": "integer" }, "hpd": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "aggregate": { "type": "object", "properties": { "total_assessed_value": { "type": "number" }, "total_assessed_land": { "type": "number" }, "total_exempt_value": { "type": "number" }, "total_units": { "type": "number" }, "total_lot_area_sqft": { "type": "number" }, "violations": { "type": "object", "properties": { "dob": { "type": "integer" }, "ecb": { "type": "integer" }, "hpd": { "type": "integer" }, "total": { "type": "integer" }, "per_property": { "type": "number" } } }, "borough_distribution": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "truncated": { "type": "boolean" } } }, "UsageAnalytics": { "type": "object", "required": [ "key_id", "tier", "period", "total_requests", "total_credits" ], "properties": { "key_id": { "type": "string", "format": "uuid" }, "tier": { "type": "string", "enum": [ "starter", "growth", "scale" ] }, "credits_remaining": { "type": "integer" }, "credits_total": { "type": "integer" }, "period": { "type": "object", "properties": { "days": { "type": "integer" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } } }, "total_requests": { "type": "integer" }, "total_credits": { "type": "number" }, "error_rate": { "type": "number", "description": "Fraction of requests returning 4xx/5xx" }, "avg_response_ms": { "type": "integer" }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "requests": { "type": "integer" }, "credits": { "type": "number" }, "errors": { "type": "integer" }, "avg_response_ms": { "type": "integer" } } } }, "by_endpoint": { "type": "object", "additionalProperties": { "type": "object", "properties": { "requests": { "type": "integer" }, "credits": { "type": "number" }, "errors": { "type": "integer" }, "avg_response_ms": { "type": "integer" } } } } } } }, "responses": { "BadRequest": { "description": "Missing or invalid parameters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "PaymentRequired": { "description": "Credits exhausted or no active subscription", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "NotFound": { "description": "No matching record found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } } } }