API Documentation - FoodSafe Score API

Authentication

All API requests must include your API key in the X-FoodSafe-Key request header. Generate a key from your account dashboard. Never expose your key in client-side or public code.

Keep your API key private. If compromised, rotate it immediately from your dashboard. All requests are logged per key.

Required request header

HTTP Header

              X-FoodSafe-Key: fsk_live_your_api_key_here

Base URL

All endpoints are relative to the base URL below. The current stable version is v1.

Base URL https://api.foodsafescoreapi.com/v1

Always use HTTPS. HTTP requests are rejected with a 301 Redirect.

Endpoints

GET /search Search restaurants by name and city

Search for restaurants by name, optionally filtered by city. Returns a paginated list of matching restaurants with their current FoodSafe scores.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Required	Restaurant name or partial name. Minimum 2 characters.
`city`	string	Optional	City name to narrow results. Example: `New York`, `Los Angeles`.
`limit`	integer	Optional	Results per page. Default `10`, max `50`.
`page`	integer	Optional	Page number. Default `1`.

Example Request

cURL
curl -X GET \
  "https://api.foodsafescoreapi.com/v1/search?q=joe%27s+pizza&city=New+York" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here"

Example Response

JSON Response - 200 OK
{
  "total": 3,
  "page": 1,
  "results": [
    {
      "id": "rest_nyc_7f4a2b1c",
      "name": "Joe's Pizza",
      "address": "7 Carmine St, New York, NY 10014",
      "city": "New York",
      "state": "NY",
      "score": 87,
      "grade": "A",
      "last_inspection": "2025-11-15"
    }
  ]
}

GET /restaurant/{id} Get detailed score for a restaurant

Retrieve the full FoodSafe Score profile for a specific restaurant, including violation breakdown and normalized score components.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Required	Unique restaurant identifier returned by `/search` or `/batch`.

Example Request

cURL
curl -X GET \
  "https://api.foodsafescoreapi.com/v1/restaurant/rest_nyc_7f4a2b1c" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here"

Example Response

JSON Response - 200 OK
{
  "id": "rest_nyc_7f4a2b1c",
  "name": "Joe's Pizza",
  "address": "7 Carmine St, New York, NY 10014",
  "city": "New York",
  "state": "NY",
  "cuisine": "Pizza",
  "score": 87,
  "grade": "A",
  "score_components": {
    "critical_violations": 0,
    "non_critical_violations": 2,
    "re_inspection_required": false
  },
  "last_inspection": "2025-11-15",
  "inspection_count": 12,
  "source_jurisdiction": "NYC DOHMH",
  "data_updated_at": "2025-11-17T08:30:00Z"
}

GET /restaurant/{id}/history Inspection history for a restaurant

Returns the full inspection history for a restaurant, showing how its FoodSafe Score has changed over time. Useful for trend analysis and risk modeling.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Required	Unique restaurant identifier.

Query Parameters

Parameter	Type	Required	Description
`from`	string	Optional	Start date in `YYYY-MM-DD` format. Defaults to 2 years ago.
`to`	string	Optional	End date in `YYYY-MM-DD` format. Defaults to today.

Example Request

cURL
curl -X GET \
  "https://api.foodsafescoreapi.com/v1/restaurant/rest_nyc_7f4a2b1c/history?from=2024-01-01" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here"

Example Response

JSON Response - 200 OK
{
  "id": "rest_nyc_7f4a2b1c",
  "name": "Joe's Pizza",
  "inspections": [
    {
      "date": "2025-11-15",
      "score": 87,
      "grade": "A",
      "violations": 2,
      "critical_violations": 0
    },
    {
      "date": "2024-08-22",
      "score": 74,
      "grade": "B",
      "violations": 5,
      "critical_violations": 1
    }
  ]
}

GET /coverage List all supported US metros

Returns all supported US metropolitan areas, including the data source for each jurisdiction and the date data was last refreshed. No parameters required.

Example Request

cURL
curl -X GET \
  "https://api.foodsafescoreapi.com/v1/coverage" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here"

Example Response

JSON Response - 200 OK
{
  "total_metros": 52,
  "metros": [
    {
      "city": "New York",
      "state": "NY",
      "source": "NYC DOHMH",
      "restaurant_count": 27450,
      "data_updated_at": "2025-12-01"
    },
    {
      "city": "Los Angeles",
      "state": "CA",
      "source": "LA County DPH",
      "restaurant_count": 34120,
      "data_updated_at": "2025-12-01"
    }
  ]
}

POST /batch Batch lookup up to 100 restaurants

Resolve up to 100 restaurant IDs in a single request. Returns the current FoodSafe Score for each. Counts as one request against your rate limit regardless of how many IDs are submitted.

Request Body

Field	Type	Required	Description
`ids`	string[]	Required	Array of restaurant IDs to look up. Maximum 100 per request.

Example Request

cURL
curl -X POST \
  "https://api.foodsafescoreapi.com/v1/batch" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "rest_nyc_7f4a2b1c",
      "rest_la_3e8d9f12",
      "rest_chi_9a2c4b77"
    ]
  }'

Example Response

JSON Response - 200 OK
{
  "results": [
    { "id": "rest_nyc_7f4a2b1c", "score": 87, "grade": "A", "last_inspection": "2025-11-15" },
    { "id": "rest_la_3e8d9f12",  "score": 92, "grade": "A", "last_inspection": "2025-10-03" },
    { "id": "rest_chi_9a2c4b77", "score": 61, "grade": "C", "last_inspection": "2025-09-18" }
  ],
  "not_found": []
}

POST /webhooks Register a webhook for score changes

Register a webhook URL to receive real-time HTTP POST notifications whenever a watched restaurant's FoodSafe Score changes after a new inspection is published.

Request Body

Field	Type	Required	Description
`url`	string	Required	Your HTTPS endpoint to receive webhook payloads.
`restaurant_ids`	string[]	Required	Restaurant IDs to monitor for score changes. Maximum 500 per webhook.
`secret`	string	Optional	Secret string used to sign payloads via HMAC-SHA256. Verify the `X-FoodSafe-Signature` header on all incoming requests.

Example Request

cURL
curl -X POST \
  "https://api.foodsafescoreapi.com/v1/webhooks" \
  -H "X-FoodSafe-Key: fsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/foodsafe",
    "restaurant_ids": ["rest_nyc_7f4a2b1c", "rest_la_3e8d9f12"],
    "secret": "your_webhook_secret"
  }'

Example Response

JSON Response - 201 Created
{
  "webhook_id": "wh_a1b2c3d4e5",
  "url": "https://yourapp.com/webhooks/foodsafe",
  "restaurant_count": 2,
  "status": "active",
  "created_at": "2026-04-03T09:00:00Z"
}

Webhook payloads include a X-FoodSafe-Signature HMAC-SHA256 header. Always verify this signature to confirm requests originate from FoodSafe Score API.

Rate Limits

Rate limits are enforced per API key and reset every 60 seconds. When a limit is exceeded the API returns 429 Too Many Requests. Check the Retry-After header for how many seconds to wait before retrying.

Starter

10

requests / min

Growth

60

requests / min

Enterprise

300

requests / min

Batch requests count as a single request against your rate limit. Use POST /batch to maximize throughput on high-volume lookups.

Error Codes

All errors return a JSON body with a code and message field. Use the HTTP status code to handle errors programmatically.

HTTP Status	Error Code	Description
400	`bad_request`	The request is malformed or missing required parameters. Check the `message` field for details.
401	`unauthorized`	Missing or invalid `X-FoodSafe-Key` header. Verify your API key is correct and active.
403	`forbidden`	Your current plan does not include access to this endpoint. Upgrade your plan to unlock it.
404	`not_found`	The requested restaurant ID does not exist in our database.
429	`rate_limit_exceeded`	You have exceeded your plan's rate limit. Wait the number of seconds in the `Retry-After` header before retrying.
500	`internal_error`	An unexpected server error occurred. If this persists, contact [email protected].

Example error response

JSON Response - 401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing X-FoodSafe-Key header.",
    "docs_url": "https://foodsafescoreapi.com/docs/#authentication"
  }
}

SDKs

Official client libraries are in active development. The REST API works with any HTTP client in the meantime. Contact us to vote for your preferred language.

Python

Official Python SDK with async support, automatic retries, and full type hints for Python 3.10+ applications.

Coming soon

Node.js

Official Node.js and TypeScript SDK with Promise-based API, full type coverage, and tree-shakeable ESM exports.

Coming soon

Go

Official Go SDK with idiomatic error handling, context support, and zero external dependencies for production services.

Coming soon

Want a different language? Email us or open a GitHub issue to vote for your preferred SDK.