# Restaurant Inspection Scores & Violations (Official City Data) (`civicdataforge/restaurant-inspection-scores`) Actor

- **URL**: https://apify.com/civicdataforge/restaurant-inspection-scores.md
- **Developed by:** [Bryan](https://apify.com/civicdataforge) (community)
- **Categories:** Real estate, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Restaurant Inspection Scores & Violations (Official City Data)

Official government restaurant / food-service **health inspection results** — pulled straight
from each city's open-data portal (no scraping, no third-party aggregators) and normalized
into **one unified schema** across cities.

Currently covered (every source verified live against the portal's API):

| City | Source (official) | Dataset | Freshness at build (2026-07-19) | Row grain |
|---|---|---|---|---|
| New York City, NY | NYC DOHMH via NYC Open Data | [`43nn-pn8j`](https://data.cityofnewyork.us/Health/DOHMH-New-York-City-Restaurant-Inspection-Results/43nn-pn8j) | newest rows 2026-07-16 | one row **per cited violation** |
| Chicago, IL | Chicago Dept. of Public Health via Chicago Data Portal | [`4ijn-s7e5`](https://data.cityofchicago.org/Health-Human-Services/Food-Inspections/4ijn-s7e5) | newest rows 2026-07-16 | one row per inspection |
| Austin, TX | Austin Public Health via City of Austin Open Data | [`ecmv-9xxi`](https://data.austintexas.gov/Health-and-Community-Services/Food-Establishment-Inspection-Scores/ecmv-9xxi) | newest rows 2026-05-22 | one row per inspection |
| Cincinnati, OH | Cincinnati Health Dept. via Cincinnati Open Data | [`rg6p-b3h3`](https://data.cincinnati-oh.gov/Thriving-Neighborhoods/Cincinnati-Food-Safety-Program/rg6p-b3h3) | newest rows 2026-07 | one row **per cited violation** |

### Unified record schema

```json
{
  "city": "Chicago",
  "state": "IL",
  "business_name": "OLD TOWN POUR HOUSE",
  "address": "120 N LA SALLE ST CHICAGO IL 60602",
  "inspection_date": "2026-07-16T00:00:00.000",
  "inspection_type": "License",
  "result_or_grade": "Fail",
  "score": null,
  "violations_summary": "3. MANAGEMENT, FOOD EMPLOYEE ... (truncated at 2000 chars)",
  "source_url": "https://data.cityofchicago.org/resource/4ijn-s7e5.json",
  "raw": { "...every original field from the city, verbatim..." }
}
````

`raw` always carries the **complete original record** (minus phone numbers), so nothing the
city published is lost — the unified fields are a convenience layer on top, never a replacement.

### Honest coverage notes (read before comparing cities)

Cities grade differently; this actor **does not translate between grading systems** — it
reports each city's own fields verbatim:

- **NYC** — numeric `score` where **lower is better** (0 = clean), plus letter `grade`
  (A/B/C; `N`/`Z`/`P` are pending states; often empty until a grade is assigned). One row per
  cited violation: an inspection with 3 violations = 3 rows sharing date/score/grade.
- **Chicago** — `result_or_grade` = Pass / Pass w/ Conditions / Fail / Out of Business / No Entry…
  **No numeric score.** Full violation narrative in `violations_summary` (truncated at 2000
  chars; full text always in `raw.violations`).
- **Austin** — numeric `score` where **higher is better** (100 = perfect). **No letter grade or
  pass/fail, and no violation detail** in the city's feed.
- **Cincinnati** — `result_or_grade` = the inspection's action status (Approved / Approved -
  Minor Violations / Not In Compliance…). **No numeric score.** One row per cited violation,
  with Ohio food-code section, description, and inspector comments.

So: **do not** rank a NYC 10 against an Austin 90 — they are different scales in opposite
directions. Compare within a city, or use `result_or_grade`.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `cities` | array | all 4 | `nyc`, `chicago`, `austin`, `cincinnati` |
| `businessNameContains` | string | — | case-insensitive substring on the establishment name (server-side) |
| `resultContains` | string | — | case-insensitive substring on result/grade, e.g. `fail`; skips Austin (score-only) with a warning |
| `since` | string | — | ISO date `YYYY-MM-DD`; only inspections on/after (server-side) |
| `maxRecordsPerCity` | integer | 1000 | newest first |

Records are always returned **newest first**, so capped runs surface the most recent inspections.
If a city portal fails mid-run, the actor **fails open**: it keeps everything already collected,
logs a loud warning naming the city, and continues with the other cities.

### Who uses this

- **Acquisition / franchise diligence** — pull the full inspection history of a target
  restaurant (or every location of a brand via `businessNameContains`) before a deal.
- **Food-safety analytics & insurers** — track failure rates, repeat violations, and
  closure actions across markets.
- **Journalists & researchers** — closures (`action` in NYC `raw`), failed inspections,
  pest violations, neighborhood patterns.
- **Restaurant-tech & delivery platforms** — surface official grades next to listings.

### Data custody

Values are **verbatim from the official source** — no inference, no cleanup beyond
whitespace/assembly of address parts, no cross-city score translation. Phone numbers are
stripped. Each record carries `source_url` so every row is independently checkable against
the city portal.

# Actor input Schema

## `cities` (type: `array`):

Which official city inspection feeds to pull. Published fields vary by city — see the README coverage table (e.g. Austin has a 0-100 score but no grade; Chicago has Pass/Fail but no score).

## `businessNameContains` (type: `string`):

Case-insensitive substring match on the establishment name (server-side), e.g. "pizza" or "McDonald".

## `resultContains` (type: `string`):

Case-insensitive substring match on the city's result or grade field, e.g. "fail" (Chicago), "A" (NYC grade), "not in compliance" (Cincinnati). Austin publishes only a numeric score, so this filter skips Austin (with a warning).

## `since` (type: `string`):

Only inspections on or after this date, e.g. 2026-01-01 (server-side filter).

## `maxRecordsPerCity` (type: `integer`):

Cap records per city, newest first. Default 1000.

## Actor input object example

```json
{
  "cities": [
    "chicago"
  ],
  "maxRecordsPerCity": 300
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cities": [
        "chicago"
    ],
    "maxRecordsPerCity": 300
};

// Run the Actor and wait for it to finish
const run = await client.actor("civicdataforge/restaurant-inspection-scores").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cities": ["chicago"],
    "maxRecordsPerCity": 300,
}

# Run the Actor and wait for it to finish
run = client.actor("civicdataforge/restaurant-inspection-scores").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cities": [
    "chicago"
  ],
  "maxRecordsPerCity": 300
}' |
apify call civicdataforge/restaurant-inspection-scores --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=civicdataforge/restaurant-inspection-scores",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Restaurant Inspection Scores & Violations (Official City Data)",
        "version": "0.1",
        "x-build-id": "crC4WB4JrVe65862J"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/civicdataforge~restaurant-inspection-scores/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-civicdataforge-restaurant-inspection-scores",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/civicdataforge~restaurant-inspection-scores/runs": {
            "post": {
                "operationId": "runs-sync-civicdataforge-restaurant-inspection-scores",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/civicdataforge~restaurant-inspection-scores/run-sync": {
            "post": {
                "operationId": "run-sync-civicdataforge-restaurant-inspection-scores",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "cities": {
                        "title": "Cities",
                        "type": "array",
                        "description": "Which official city inspection feeds to pull. Published fields vary by city — see the README coverage table (e.g. Austin has a 0-100 score but no grade; Chicago has Pass/Fail but no score).",
                        "items": {
                            "type": "string",
                            "enum": [
                                "nyc",
                                "chicago",
                                "austin",
                                "cincinnati"
                            ],
                            "enumTitles": [
                                "New York City, NY",
                                "Chicago, IL",
                                "Austin, TX",
                                "Cincinnati, OH"
                            ]
                        },
                        "default": [
                            "nyc",
                            "chicago",
                            "austin",
                            "cincinnati"
                        ]
                    },
                    "businessNameContains": {
                        "title": "Business name contains",
                        "type": "string",
                        "description": "Case-insensitive substring match on the establishment name (server-side), e.g. \"pizza\" or \"McDonald\"."
                    },
                    "resultContains": {
                        "title": "Result / grade contains",
                        "type": "string",
                        "description": "Case-insensitive substring match on the city's result or grade field, e.g. \"fail\" (Chicago), \"A\" (NYC grade), \"not in compliance\" (Cincinnati). Austin publishes only a numeric score, so this filter skips Austin (with a warning)."
                    },
                    "since": {
                        "title": "Inspections since (ISO date)",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}",
                        "type": "string",
                        "description": "Only inspections on or after this date, e.g. 2026-01-01 (server-side filter)."
                    },
                    "maxRecordsPerCity": {
                        "title": "Max records per city",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Cap records per city, newest first. Default 1000.",
                        "default": 1000
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```