# TheFork Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/thefork/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/thefork-search |

## Description

Search TheFork restaurants from a full search or city URL and retrieve ratings, cuisine, prices, availability, review summaries, and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/thefork/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search restaurants in Strasbourg for 8 guests on 2026-06-13

```json
{
  "results": [
    {
      "id": 423365,
      "url": "https://www.thefork.fr/restaurant/le-vintage-r423365",
      "name": "Le Vintage",
      "slug": "le-vintage",
      "uuid": "a55fe916-811b-43be-9b14-4babd77b0df9",
      "image": "https://cdn.thefork.com/tf-lab/image/upload/restaurant/a55fe916-811b-43be-9b14-4babd77b0df9/54b4e261-50d9-4bbb-a690-08a38059391c.jpg",
      "rating": 9.5,
      "address": "15 Rue des Serruriers, 67000, Strasbourg, France",
      "cuisine": "Alsacien",
      "currency": "EUR",
      "avg_price": 32,
      "timeslots": [],
      "geolocation": {
        "latitude": 48.5803126,
        "longitude": 7.7464058,
        "__typename": "Coordinate"
      },
      "is_bookable": true,
      "reviews_count": 571,
      "review_snippets": [
        {
          "text": "très beau cadre vintage, très belle musique, très bon repas, accueil parfait, nous recommandons à 100%",
          "__typename": "SearchReviewSnippet",
          "highlights": [
            {
              "end": 59,
              "start": 45,
              "__typename": "SearchReviewSnippetHighlight"
            },
            {
              "end": 76,
              "start": 61,
              "__typename": "SearchReviewSnippetHighlight"
            }
          ],
          "review_snippet_uuid": "a114b6d4-f50f-4d74-9935-c5a6ed7f895f"
        }
      ],
      "reviews_summary": "Le Vintage charme par son ambiance rétro et intimiste, avec une décoration vintage de très bon goût, agrémentée de photos d’actrices mythiques. Les clients apprécient particulièrement les tartes flambées croustillantes et bien garnies, ainsi que le jarret grillé. Le service est impeccable et chaleureux, avec un personnel attentionné. Une adresse recommandée à Strasbourg pour une expérience culinaire authentique."
    },
    {
      "id": 832121,
      "url": "https://www.thefork.fr/restaurant/restaurant-et-cafe-aygui-r832121",
      "name": "RESTAURANT ET CAFÉ AYGUI",
      "slug": "restaurant-et-cafe-aygui",
      "uuid": "d34ce798-5ed7-4a0f-b014-eb2dbdd24476",
      "image": "https://cdn.thefork.com/tf-lab/image/upload/restaurant/d34ce798-5ed7-4a0f-b014-eb2dbdd24476/d524634e-094b-447f-bdc8-c2865bf506e3.png",
      "rating": 9.3,
      "address": "5 Rue du Faubourg-de-Saverne, 67000, Strasbourg, France",
      "cuisine": "Arménien",
      "currency": "EUR",
      "avg_price": 18,
      "timeslots": [],
      "geolocation": {
        "latitude": 48.584737,
        "longitude": 7.740534999999999,
        "__typename": "Coordinate"
      },
      "is_bookable": true,
      "reviews_count": 202,
      "review_snippets": [
        {
          "text": "Tout était parfait, mon amie a pris plaisir à découvrir la cuisine du Caucase.",
          "__typename": "SearchReviewSnippet",
          "highlights": [
            {
              "end": 18,
              "start": 11,
              "__typename": "SearchReviewSnippetHighlight"
            },
            {
              "end": 77,
              "start": 59,
              "__typename": "SearchReviewSnippetHighlight"
            }
          ],
          "review_snippet_uuid": "90058560-2c7f-4d07-8de4-91a5ab4a0c87"
        }
      ],
      "reviews_summary": "RESTAURANT ET CAFÉ AYGUI offre une belle découverte culinaire avec une cuisine caucasienne savoureuse et généreuse, notamment les délicieux raviolis arméniens et l'excellent baklava. Le cadre est chaleureux et agréable, bien que l'éclairage puisse être amélioré. Le service est accueillant et attentionné, malgré quelques retards. Une adresse recommandée pour explorer des mets authentiques."
    },
    {
      "id": 10892,
      "url": "https://www.thefork.fr/restaurant/salamboo-amilkar-r10892",
      "name": "Salamboo Amilkar",
      "slug": "salamboo-amilkar",
      "uuid": "b553d2bc-f24b-4f3d-bc40-e415dfc927cd",
      "image": "https://cdn.thefork.com/tf-lab/image/upload/restaurant/b553d2bc-f24b-4f3d-bc40-e415dfc927cd/f2041a2c-126f-4e38-9238-36f54d2a9077.jpg",
      "rating": 9.4,
      "address": "2, rue de la Croix, 67000, Strasbourg, France",
      "cuisine": "Tunisien",
      "currency": "EUR",
      "avg_price": 31,
      "timeslots": [],
      "geolocation": {
        "latitude": 48.582227484,
        "longitude": 7.754749775,
        "__typename": "Coordinate"
      },
      "is_bookable": true,
      "reviews_count": 1614,
      "review_snippets": [
        {
          "text": "Endroit magnifique et couscous excellent, service impeccable, toujours avec le sourire, c'est une belle adresse",
          "__typename": "SearchReviewSnippet",
          "highlights": [
            {
              "end": 18,
              "start": 8,
              "__typename": "SearchReviewSnippetHighlight"
            },
            {
              "end": 30,
              "start": 22,
              "__typename": "SearchReviewSnippetHighlight"
            }
          ],
          "review_snippet_uuid": "b31707a7-ba97-4121-8424-1a223fbe490e"
        }
      ],
      "reviews_summary": "Salamboo Amilkar séduit par son cadre raffiné et son ambiance chaleureuse, idéale pour s'évader le temps d'un repas. Les plats tunisiens, notamment le couscous, sont une explosion de saveurs et généreusement servis. Le personnel, toujours accueillant et souriant, assure un service impeccable. Une adresse à découvrir et à revisiter pour des moments inoubliables."
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "next_url": "https://www.thefork.fr/search?cityId=529135&date=2026-06-13&hour=660&partySize=8&timezone=Europe%2FParis#list25",
    "per_page": 25,
    "total_count": 185,
    "total_pages": 8,
    "has_next_page": true
  }
}
```

## Documentation

## Overview
Extract restaurant listings from any TheFork search or city browse page. Returns structured cards with ratings, cuisine, average price, address, geolocation, bookability, AI review summaries, and pagination metadata.

TheFork is a Next.js single-page application. Search results (`RestaurantCard` components) and availability data are loaded via GraphQL after the initial HTML shell. A plain HTTP request returns an empty page skeleton. Piloterr uses **website rendering** to execute JavaScript, wait for restaurant cards to render, and extract structured JSON from the live DOM.

## Quickstart
```
GET https://api.piloterr.com/v2/thefork/search?query=https://www.thefork.fr/search?cityId=529135&date=2026-06-13&hour=660&partySize=8&timezone=Europe%2FParis
```

Copy the full URL from thefork.fr. Use `pagination.next_url` for the next page (anchor-based: `#list25`, `#list50`, ...).

## Supported URL formats
| Format | Example |
|---|---|
| Search with filters | `https://www.thefork.fr/search?cityId=529135&date=2026-06-13&hour=660&partySize=8` |
| City listing | `https://www.thefork.fr/restaurants/strasbourg-c529135` |

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full TheFork `/search` or `/restaurants/{city}-c{id}` URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Restaurant listing cards |
| `results[].id` | integer | TheFork restaurant ID |
| `results[].url` | string | Restaurant page URL |
| `results[].name` | string | Restaurant name |
| `results[].slug` | string | URL slug |
| `results[].uuid` | string | TheFork UUID |
| `results[].image` | string | Main photo URL |
| `results[].rating` | number | TheFork score (0-10) |
| `results[].reviews_count` | integer | Number of reviews |
| `results[].cuisine` | string | Primary cuisine label |
| `results[].currency` | string | Price currency (e.g. `EUR`) |
| `results[].avg_price` | number | Average menu price |
| `results[].address` | string | Full formatted address |
| `results[].geolocation` | object | `{ latitude, longitude }` |
| `results[].is_bookable` | boolean | Online booking available |
| `results[].timeslots` | array | Available time slots when date/hour filters are set |
| `results[].review_snippets` | array | Highlighted customer review excerpts |
| `results[].reviews_summary` | string | AI-generated review summary |
| `pagination.current` | integer | Current page number |
| `pagination.next` | integer \| null | Next page number |
| `pagination.next_url` | string \| null | Next page URL with anchor |
| `pagination.total_pages` | integer | Total pages |
| `pagination.total_count` | integer | Total matching restaurants |
| `pagination.per_page` | integer | Results on this page |
| `pagination.has_next_page` | boolean | Whether a next page exists |

## Notes
- Works on all TheFork country domains (`thefork.fr`, `thefork.com`, `thefork.it`, ...).
- `hour` is minutes from midnight (`660` = 11:00).
- `timeslots` may be empty when no date/time filter is applied.
- Pass `results[].url` to **TheFork Restaurant** for tags, gallery, opening hours, and TripAdvisor ratings.

## Main use cases
- Build restaurant lead lists by city, cuisine, and availability
- Monitor competitor ratings and average prices across markets
- Feed hospitality analytics with geolocated dining data
- Check real-time bookability and time slots for a given date and party size