v1.0 — Live

NYC API

Structured NYC restaurant health inspections, sidewalk cafe permits, and business licenses — via a single, agent-friendly REST API.

https://nycapi.app

Overview

The Restaurant & Venue Intel API transforms raw NYC Open Data into structured, query-ready intelligence for any restaurant or food establishment in New York City. It sources from three official city datasets in real time — no stale caches.

Health Inspections

DOH grades, scores, violations, inspection history

Venue Search

Find restaurants by cuisine, grade, borough, zip

Permits & Licenses

Sidewalk cafes, DCA business licenses

Property Intelligence

Owner info, zoning, assessments, ACRIS transactions, violation counts

Building Violations

DOB violations, HPD violations, 311 complaints per address

Built for

AI agents & LLM tool-use • Real estate platforms • Hospitality analytics • Event planning automation • Food-tech startups • Commercial underwriting • Compliance workflows

Authentication

Every request requires a valid API key passed in the Authorization header using the Bearer scheme.

Authorization: Bearer mv_live_a1b2c3d4e5f6...

Getting a key

API keys are issued per product. Request access at matchuplabs.com/api-access or email api@matchuplabs.com. Each key is scoped to nyc-api and includes a credit balance and per-minute rate limit.

Key prefixes

Prefix	Environment
`mv_live_`	Production
`mv_test_`	Testing / sandbox

Rate Limits

Rate limits are enforced per API key using a sliding window of 60 seconds. Limits vary by tier.

Tier	Requests / min	Credits included
Free	30	500
Pro	120	10,000
Enterprise	Custom	Custom

Rate limit headers

Every response includes these headers:

Header	Description
`X-RateLimit-Limit`	Max requests per minute for this key
`X-RateLimit-Remaining`	Requests remaining in the current window
`Retry-After`	Seconds until the window resets (only on 429)

Credit System

Each successful API call (HTTP 200) consumes 1 credit, regardless of endpoint. Failed requests (4xx, 5xx) are free. Your remaining balance is returned in the meta.credits_remaining field of every successful response.

Cost per call: 1 credit
Free tier: 500 credits (no expiration)
Top-ups: Available via dashboard or API
Overage: Returns 402 credits_exhausted when balance hits 0

Response Envelope

All responses follow a consistent envelope. Successful responses use the standard JSON envelope. Error responses use RFC 7807 Problem Details.

Success (HTTP 200)

{
  "data": { ... },
  "meta": {
    "source": "nyc-open-data/doh-inspections",
    "updated": "2026-03-26T15:30:00.000Z",
    "query_ms": 342,
    "credits_remaining": 487
  }
}

Error (HTTP 4xx / 5xx)

{
  "type": "https://api.matchuplabs.com/errors/not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "No restaurant found matching the provided criteria.",
  "query": { "name": "NONEXISTENT PLACE", "borough": "Manhattan" }
}

GET/api/venue/health

Returns the full health inspection profile for a NYC restaurant, including current grade, inspection history, and individual violations. Data sourced from DOH Restaurant Inspections in real time.

Query Parameters

Parameter	Type	Description
namerequired*	string	Business name (partial, case-insensitive)
addressrequired*	string	Street address (e.g. "178 Broadway")
camisrequired*	string	Unique DOH restaurant ID (10-digit)
boroughoptional	string	Borough name or code (1-5). Narrows results.
zipcodeoptional	string	5-digit ZIP code

* At least one of name, address, or camis is required.

Example Request

curl "https://nycapi.app/api/venue/health?name=PETER+LUGER&borough=Brooklyn" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "camis": "40364335",
    "name": "PETER LUGER STEAKHOUSE",
    "address": {
      "building": "178",
      "street": "BROADWAY",
      "borough": "Brooklyn",
      "zipcode": "11211"
    },
    "phone": "7183877400",
    "cuisine": "Steakhouse",
    "current_grade": "A",
    "current_score": 12,
    "grade_date": "2024-09-30",
    "inspections": [
      {
        "date": "2024-09-30",
        "type": "Cycle Inspection / Re-Inspection",
        "score": 12,
        "grade": "A",
        "violations": [
          {
            "code": "10F",
            "description": "Non-food contact surface improperly constructed.",
            "critical": false
          }
        ]
      },
      {
        "date": "2024-03-14",
        "type": "Cycle Inspection / Initial Inspection",
        "score": 27,
        "grade": null,
        "violations": [
          {
            "code": "04L",
            "description": "Evidence of mice or live mice in establishment.",
            "critical": true
          },
          {
            "code": "06D",
            "description": "Food contact surface improperly maintained.",
            "critical": true
          }
        ]
      }
    ],
    "total_inspections": 2
  },
  "meta": {
    "source": "nyc-open-data/doh-inspections",
    "updated": "2026-03-26T15:30:00.000Z",
    "query_ms": 1840,
    "credits_remaining": 492
  }
}

GET/api/venue/search

Search NYC restaurants by cuisine, health grade, borough, or ZIP code. Returns a paginated list of venue summaries — one entry per restaurant, deduplicated by CAMIS, with the most recent grade.

Query Parameters

Parameter	Type	Description
cuisinerequired*	string	Cuisine type (partial match: "Italian", "Thai", "Pizza")
graderequired*	A \| B \| C	Current health grade
boroughrequired*	string	Borough name or numeric code (1-5)
zipcoderequired*	string	5-digit ZIP code
limitoptional	number	Results per page. Default: 20, max: 100
offsetoptional	number	Number of results to skip. Default: 0

* At least one of cuisine, grade, borough, or zipcode is required.

Example Request

curl "https://nycapi.app/api/venue/search?cuisine=Italian&borough=Brooklyn&limit=5" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "results": [
      {
        "camis": "50099664",
        "name": "UN POSTO ITALIANO",
        "address": {
          "building": "206",
          "street": "GARFIELD PLACE",
          "borough": "Brooklyn",
          "zipcode": "11215"
        },
        "cuisine": "Italian",
        "current_grade": "A",
        "current_score": 4,
        "last_inspection_date": "2026-03-19"
      },
      {
        "camis": "41664792",
        "name": "FRANKIES 457 SPUNTINO",
        "address": {
          "building": "457",
          "street": "COURT ST",
          "borough": "Brooklyn",
          "zipcode": "11231"
        },
        "cuisine": "Italian",
        "current_grade": "A",
        "current_score": 9,
        "last_inspection_date": "2026-02-28"
      }
    ],
    "total": 21,
    "limit": 5,
    "offset": 0
  },
  "meta": {
    "source": "nyc-open-data/doh-inspections",
    "updated": "2026-03-26T15:40:09.850Z",
    "query_ms": 349,
    "credits_remaining": 488
  }
}

GET/api/venue/permits

Returns sidewalk cafe permits and DCA business licenses for a venue. Cross-references two city datasets by name and address. Useful for due diligence, commercial leasing, and compliance verification.

Query Parameters

Parameter	Type	Description
namerequired*	string	Business name (searches owner name and DBA)
addressrequired*	string	Street address (e.g. "119 Macdougal St")
zipcodeoptional	string	5-digit ZIP code (recommended for accuracy)

* At least one of name or address is required.

Example Request

curl "https://nycapi.app/api/venue/permits?address=119+MACDOUGAL+ST&zipcode=10012" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "business_name": "CAVALLACCI, FABRIZIO",
    "address": {
      "building": "119",
      "street": "MACDOUGAL ST",
      "city": "NEW YORK",
      "state": "NY",
      "zipcode": "10012"
    },
    "sidewalk_cafe": {
      "license_number": "1083712",
      "type": "Unenclosed",
      "status": "Active",
      "tables": 4,
      "chairs": 8,
      "area_sq_ft": 114,
      "expiration_date": "2017-11-24"
    },
    "business_licenses": []
  },
  "meta": {
    "source": "nyc-open-data/dca-sidewalk-cafes,dca-businesses",
    "updated": "2026-03-26T16:12:44.221Z",
    "query_ms": 812,
    "credits_remaining": 486
  }
}

GET/api/property/lookup

Returns a full property profile — owner info, zoning, assessment values, recent ACRIS transactions, and violation counts from DOB and HPD. Query by address+borough, BBL, or block+lot+borough.

Query Parameters

Parameter	Type	Description
addressrequired*	string	Street address (e.g. "100 Broadway")
boroughrequired*	string	Borough name (Manhattan, Brooklyn, Queens, Bronx, Staten Island)
bblrequired*	string	10-digit Borough-Block-Lot identifier
blockrequired*	string	Tax block number
lotrequired*	string	Tax lot number

* One of these sets is required: (address + borough), (bbl), or (block + lot + borough).

Example Request

curl "https://nycapi.app/api/property/lookup?address=100+Broadway&borough=Manhattan" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "bbl": "1000770001",
    "address": {
      "number": "100",
      "street": "BROADWAY",
      "borough": "Manhattan",
      "zipcode": "10005"
    },
    "owner": "100 BROADWAY OWNER LLC",
    "building_class": "O4",
    "zoning": "C6-4",
    "year_built": 1896,
    "total_units": 0,
    "lot_area_sqft": 26122,
    "assessed_total": 26437500,
    "acris_transactions": [
      {
        "document_type": "DEED",
        "document_date": "2022-06-15",
        "amount": 185000000,
        "party_1": "PREVIOUS OWNER LLC",
        "party_2": "100 BROADWAY OWNER LLC"
      }
    ],
    "violations": {
      "dob_count": 12,
      "hpd_count": 0
    }
  },
  "meta": {
    "source": "nyc-open-data/pluto,acris,dob-violations,hpd-violations",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 2340,
    "credits_remaining": 480
  }
}

GET/api/property/search

Search PLUTO property records by address, owner name, borough, ZIP code, or building class. Returns paginated property summaries.

Query Parameters

Parameter	Type	Description
addressoptional*	string	Street address (partial match)
owneroptional*	string	Owner name (partial, case-insensitive)
boroughoptional*	string	Borough name
zipcodeoptional*	string	5-digit ZIP code
building_classoptional*	string	2-character DOF building class code
limitoptional	number	Results per page. Default: 20, max: 100
offsetoptional	number	Number of results to skip. Default: 0

* At least one filter parameter is required.

Example Request

curl "https://nycapi.app/api/property/search?owner=VORNADO&borough=Manhattan&limit=3" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "results": [
      {
        "bbl": "1008130059",
        "address": "1 PENN PLAZA",
        "borough": "Manhattan",
        "zipcode": "10001",
        "owner": "VORNADO REALTY TRUST",
        "building_class": "O4",
        "year_built": 1972,
        "total_units": 0,
        "lot_area_sqft": 166422,
        "assessed_total": 348750000
      }
    ],
    "total": 8,
    "limit": 3,
    "offset": 0
  },
  "meta": {
    "source": "nyc-open-data/pluto",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 890,
    "credits_remaining": 477
  }
}

GET/api/violations/dob

Returns DOB (Department of Buildings) violations for an address. Includes violation type, category, disposition date, and status. Paginated, newest first.

Query Parameters

Parameter	Type	Description
addressrequired	string	Street address (e.g. "100 Broadway")
boroughoptional	string	Borough name (narrows results)
blockoptional	string	Tax block number
lotoptional	string	Tax lot number
limitoptional	number	Results per page. Default: 50, max: 200
offsetoptional	number	Number of results to skip. Default: 0

Example Request

curl "https://nycapi.app/api/violations/dob?address=100+Broadway&borough=Manhattan&limit=3" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "results": [
      {
        "isn_dob_bis_viol": "1234567",
        "violation_type": "LL6291",
        "violation_category": "V*-DOB VIOLATION - ACTIVE",
        "violation_type_description": "FAILURE TO MAINTAIN",
        "disposition_date": "2025-08-15",
        "disposition_comments": "RESOLVE",
        "violation_number": "012345"
      }
    ],
    "total": 12,
    "limit": 3,
    "offset": 0
  },
  "meta": {
    "source": "nyc-open-data/dob-violations",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 1120,
    "credits_remaining": 474
  }
}

GET/api/violations/hpd

Returns HPD (Housing Preservation & Development) violations for a residential address. Filterable by violation class (A=non-hazardous, B=hazardous, C=immediately hazardous). Paginated, newest first.

Query Parameters

Parameter	Type	Description
addressrequired	string	Street address (e.g. "100 Broadway")
boroughoptional	string	Borough name
zipcodeoptional	string	5-digit ZIP code
blockoptional	string	Tax block number
lotoptional	string	Tax lot number
classoptional	A \| B \| C	Violation class filter
limitoptional	number	Results per page. Default: 50, max: 200
offsetoptional	number	Number of results to skip. Default: 0

Example Request

curl "https://nycapi.app/api/violations/hpd?address=100+W+135+ST&borough=Manhattan&class=C&limit=3" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "results": [
      {
        "violation_id": 12345678,
        "class": "C",
        "date": "2025-11-20",
        "description": "WATER SUPPLY NOT PROVIDED WITH ADEQUATE PRESSURE",
        "status": "Open",
        "status_date": "2025-11-22",
        "nov_type": "Original",
        "rent_impairing": true
      }
    ],
    "total": 24,
    "limit": 3,
    "offset": 0
  },
  "meta": {
    "source": "nyc-open-data/hpd-violations",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 980,
    "credits_remaining": 471
  }
}

GET/api/violations/complaints

Returns 311 building-related complaints for an address. Filterable by complaint type (e.g. HEATING, PLUMBING, ELEVATOR). Paginated, newest first.

Query Parameters

Parameter	Type	Description
addressrequired	string	Street address (e.g. "100 Broadway")
boroughoptional	string	Borough name (narrows results)
zipcodeoptional	string	5-digit ZIP code
typeoptional	string	Complaint type filter (e.g. HEATING, PLUMBING, ELEVATOR, WATER LEAK)
limitoptional	number	Results per page. Default: 50, max: 200
offsetoptional	number	Number of results to skip. Default: 0

Example Request

curl "https://nycapi.app/api/violations/complaints?address=100+Broadway&borough=Manhattan&type=HEATING&limit=3" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "results": [
      {
        "id": "62438901",
        "created_date": "2025-12-10",
        "closed_date": "2025-12-18",
        "type": "HEATING",
        "descriptor": "ENTIRE BUILDING",
        "status": "Closed",
        "resolution": "The Department of Housing Preservation and Development inspected the following conditions.",
        "agency": "HPD"
      }
    ],
    "total": 7,
    "limit": 3,
    "offset": 0
  },
  "meta": {
    "source": "nyc-open-data/311-complaints",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 1450,
    "credits_remaining": 468
  }
}

GET/api/violations/profile

Returns a combined building violation profile — DOB violations, HPD violations, and 311 building-related complaints for a single address. All three data sources are queried in parallel and returned in one response.

Query Parameters

Parameter	Type	Description
addressrequired	string	Street address (e.g. "100 Broadway")
boroughoptional	string	Borough name
zipcodeoptional	string	5-digit ZIP code
blockoptional	string	Tax block number
lotoptional	string	Tax lot number

Example Request

curl "https://nycapi.app/api/violations/profile?address=100+Broadway&borough=Manhattan" \
  -H "Authorization: Bearer mv_live_your_key_here"

Example Response

{
  "data": {
    "address": {
      "house_number": "100",
      "street": "BROADWAY",
      "borough": "Manhattan",
      "zipcode": "10005",
      "block": "00077",
      "lot": "0001"
    },
    "dob_violations": [
      {
        "violation_number": "012345",
        "type": "LL6291",
        "date": "2025-08-15",
        "description": "FAILURE TO MAINTAIN",
        "category": "V*-DOB VIOLATION - ACTIVE",
        "disposition": "RESOLVE"
      }
    ],
    "hpd_violations": [],
    "complaints_311": [
      {
        "id": "62438901",
        "created_date": "2025-12-10",
        "closed_date": "2025-12-18",
        "type": "ELEVATOR",
        "descriptor": "DEFECTIVE",
        "status": "Closed",
        "resolution": "Inspected",
        "agency": "DOB"
      }
    ],
    "totals": {
      "dob": 12,
      "hpd": 0,
      "complaints_311": 7,
      "total": 19
    }
  },
  "meta": {
    "source": "nyc-open-data/dob-violations,hpd-violations,311-complaints",
    "updated": "2026-03-29T12:00:00.000Z",
    "query_ms": 2890,
    "credits_remaining": 465
  }
}

Error Codes

All errors follow RFC 7807 Problem Details with a Content-Type: application/problem+json header. No credits are consumed on errors.

Status	Type	When
400	`invalid_input`	Missing required parameters or invalid values
401	`missing_api_key`	No Authorization header provided
401	`invalid_api_key`	Key not found or wrong product scope
403	`key_disabled`	API key has been deactivated
403	`key_expired`	API key has passed its expiration date
404	`not_found`	No matching records in the upstream dataset
429	`rate_limit_exceeded`	Too many requests in the current minute window
402	`credits_exhausted`	Credit balance is zero — upgrade your plan
502	`upstream_error`	NYC Open Data API returned an error or is unreachable

Example error response

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 23
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0

{
  "type": "https://api.matchuplabs.com/errors/rate_limit_exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 30 requests per minute exceeded. Retry after 23s.",
  "limit": 30,
  "remaining": 0,
  "retry_after_seconds": 23
}

Data Sources

All data is queried in real time from official NYC Open Data SODA endpoints. No data is cached or stored on our servers.

Dataset	Agency	Endpoint
DOH Restaurant Inspections	Dept. of Health	`43nn-pn8j`
DCA Sidewalk Cafe Permits	Dept. of Consumer Affairs	`qcdj-rwhu`
DCA Legally Operating Businesses	Dept. of Consumer Affairs	`w7w3-xahh`
PLUTO (Property Land Use)	Dept. of City Planning	`64uk-42ks`
ACRIS Real Property Legals	Dept. of Finance	`8h5j-fqxa`
ACRIS Real Property Master	Dept. of Finance	`bnx9-e6tj`
DOB Violations	Dept. of Buildings	`3h2n-5cm9`
HPD Violations	Housing Preservation	`wvxf-dwi5`
311 Complaints	311 / Multiple	`erm2-nwe9`

Matchup Labs • NYC API • v1.0

Questions? api@matchuplabs.com