Version 1 · Base URL: https://foodaware.io/api/v1
All endpoints require a Bearer token:
Authorization: Bearer fa_live_<your_key>
Generate keys at foodaware.io/settings/api-keys. Free tier allows 1,000 requests per day.
Search and list food establishments.
GET /api/v1/places?q=chipotle&city=chicago&page=1&per_page=20
Query parameters:
| Parameter | Type | Description |
|---|---|---|
q | string | Name search (case-insensitive partial match) |
city | string | Filter by city |
page | integer | Page number (default: 1) |
per_page | integer | Results per page (max 100, default 20) |
{
"data": [
{
"id": "uuid",
"name": "Chipotle Mexican Grill",
"address": "123 Main St",
"city": "Chicago",
"state": "IL",
"lat": 41.878,
"lng": -87.629,
"category": "restaurant"
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1
}
}Full detail for a single place with optional includes.
GET /api/v1/places/uuid?include_menu=true&include_inspections=true&include_supply=true
| Parameter | Type | Description |
|---|---|---|
include_menu | boolean | Attach menu items and recent price changes |
include_inspections | boolean | Attach 10 most recent inspection events |
include_recalls | boolean | Attach relevant recall events |
include_supply | boolean | Attach supply chain / shipment events |
Query the alert feed for status changes, delays, recalls, and price events.
GET /api/v1/alerts?type=price&place_id=uuid&since=2025-01-01T00:00:00Z
| Parameter | Type | Description |
|---|---|---|
place_id | uuid | Filter to a single establishment |
type | string | delay · price · inspection · recall · closed |
since | ISO 8601 | Return alerts after this timestamp |
until | ISO 8601 | Return alerts before this timestamp |
page / per_page | integer | Pagination (max 100 per page) |
Supply chain event feed — shipments, inventory, commodity shortages, and origin tracking. This endpoint powers Wagyu provenance tracking, import delay alerts, and upstream supplier intelligence. Currently in early access.
GET /api/v1/supply?commodity=wagyu_a5&origin_country=JP&status=in_transit
| Parameter | Type | Description |
|---|---|---|
commodity | string | e.g. wagyu_a5 · chicken · produce |
origin_country | string | ISO 2-letter country code |
status | string | in_transit · at_customs · delivered · delayed |
place_id | uuid | Filter by restaurant or distributor |
Early access: supply write access requires a partner integration. Email api@foodaware.io to connect your logistics provider (Flexport, NLBC, USDA FSIS, etc.).
Rate limit headers are returned on every response:
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 847 X-RateLimit-Reset: 1735689600 # Unix timestamp
Exceeding the limit returns HTTP 429. The window resets every 24 hours.
{
"error": "Descriptive message here."
}| Parameter | Type | Description |
|---|---|---|
401 | — | Missing or invalid API key |
403 | — | Key lacks required scope |
404 | — | Resource not found |
429 | — | Rate limit exceeded |
500 | — | Internal server error |