TheFork APIthefork.it ↗
Search Italian restaurants by city, retrieve top-rated listings, and fetch detailed info including reviews, tags, and average prices via the TheFork Italy API.
What is the TheFork API?
The TheFork Italy API exposes 4 endpoints covering restaurant search, top-rated rankings, and full restaurant details across Italian cities. Call search_restaurants to get up to 25 restaurants per city query — each result includes name, rating, address, average price, and slug identifiers ready to pass into get_restaurant_details for descriptions, cuisine tags, and up to 10 user reviews.
curl -X GET 'https://api.parse.bot/scraper/ea22957c-867d-4aaf-9db6-e3cd3ba61e99/search_restaurants?page=1&city_id=461789&city_slug=roma' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace thefork-it-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""TheFork Italy API — find top restaurants in Italian cities and read reviews."""
from parse_apis.thefork_italy_api import TheFork, RestaurantNotFound
client = TheFork()
# List available Italian cities
for city in client.cities.list(limit=5):
print(city.name, city.slug)
# Search restaurants in Roma
restaurant = client.restaurants.search(city_id="461789", city_slug="roma", limit=1).first()
if restaurant:
print(restaurant.name, restaurant.rating, restaurant.slug)
# Get top-rated restaurants in Milano
for r in client.restaurants.top_rated(city_id="348156", city_slug="milano", limit=3):
print(r.name, r.rating, r.address.locality)
# Drill into restaurant details via sub-resource
if restaurant:
try:
detail = restaurant.details.get()
print(detail.name, detail.tags[:3])
for review in detail.reviews[:2]:
print(review.reviewer, review.rating, review.text[:60] if review.text else "")
except RestaurantNotFound as exc:
print(f"Restaurant not found: {exc}")
print("exercised: cities.list / restaurants.search / restaurants.top_rated / restaurant.details.get")
Search for restaurants in a city by city ID and slug. Returns up to 25 restaurants with ratings, addresses, and average prices. Use get_cities to discover valid city_id and city_slug values.
| Param | Type | Description |
|---|---|---|
| city_id | string | City ID from get_cities endpoint. Must correspond to city_slug. |
| city_slug | string | City slug from get_cities endpoint. Must correspond to city_id. |
{
"type": "object",
"fields": {
"items": "array of restaurant objects with id, legacyId, name, rating, address, avgPrice, slug, city"
},
"sample": {
"data": {
"items": [
{
"id": "e458e1a0-2c6b-4d1f-a1b8-c5c0bc36285a",
"city": null,
"name": "The Times Bar & Ristorante Roma",
"slug": "the-times-bar-ristorante-roma",
"rating": 9.4,
"address": {
"street": "Via Milano, 42",
"country": "Italia",
"zipCode": "00184",
"locality": "Roma"
},
"avgPrice": {
"value": 3000,
"currency": {
"isoCurrency": "EUR",
"decimalPosition": 2
}
},
"legacyId": 734330
}
]
},
"status": "success"
}
}About the TheFork API
City Discovery and Restaurant Search
Start with get_cities to retrieve the full list of supported Italian cities, each with an id and slug. These values are required inputs for search_restaurants and get_top_rated_restaurants. For example, Roma maps to city_id=461789 and city_slug='roma'; Milano uses 348156 and 'milano'. The search_restaurants endpoint returns up to 25 restaurant objects per call, each containing id, legacyId, name, rating, address, avgPrice, slug, and city.
Top-Rated Listings
get_top_rated_restaurants accepts the same city_id and city_slug inputs plus an optional limit parameter to cap the number of results. Results are sorted by rating descending, making it straightforward to build curated lists or compare quality tiers across cities without a separate sort step on your end.
Restaurant Detail
get_restaurant_details requires a slug and a restaurant_id (the legacyId from search results as a string). The response adds fields not present in search results: a prose description, a tags array (cuisine type, atmosphere, and similar classifiers), and a reviews array of up to 10 entries each carrying reviewer name, text, and rating. This endpoint is the natural second call after a search — use the slug and legacyId fields from search_restaurants output directly.
Coverage and Scope
All coverage is scoped to Italy. City support is defined by what get_cities returns; there is no free-text city input — only city_id and city_slug pairs from that endpoint are accepted. Average price (avgPrice) is returned as a numeric value in the restaurant objects; the currency is EUR given the Italian market context.
The TheFork API is a managed, monitored endpoint for thefork.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when thefork.it changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official thefork.it API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a city guide app that lists top-rated restaurants in Rome or Milan using
get_top_rated_restaurants - Aggregate restaurant ratings and average prices across Italian cities for a dining cost comparison tool
- Populate a travel itinerary feature with restaurant names, addresses, and cuisine tags from
get_restaurant_details - Feed a review sentiment pipeline using the up-to-10 user reviews returned per restaurant
- Create a restaurant discovery widget filtered by city slug for an Italian tourism website
- Cross-reference TheFork restaurant slugs with other data sources using the
legacyIdnumeric identifier - Monitor rating changes over time by periodically calling
search_restaurantsand storing theratingfield per restaurant
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TheFork have an official public developer API?+
What does `get_restaurant_details` return that `search_restaurants` does not?+
search_restaurants returns core fields: id, legacyId, name, rating, address, avgPrice, slug, and city. get_restaurant_details adds a prose description, a tags array of cuisine and atmosphere classifiers, and a reviews array of up to 10 entries each with reviewer name, review text, and rating.Can I search restaurants by cuisine type or price range rather than city?+
city_id and city_slug only; there are no cuisine, price range, or keyword query parameters. You can fork this API on Parse and revise it to add filtering parameters if your use case requires cuisine- or price-based queries.