Restaurant & Venue Intel API

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.

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 restaurant-venue-intel and includes a credit balance and per-minute rate limit.

Key prefixes

Rate Limits

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

Rate limit headers

Every response includes these headers:

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.

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

* 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

* 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

* 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
  }
}

Error Codes

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

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.