> ## Documentation Index
> Fetch the complete documentation index at: https://trailblazer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /recommend — Get restaurant recommendations

> Get up to five personalized Nigerian restaurant recommendations from review history or cold-start signals including city, food preference, and price range.

The `/recommend` endpoint returns up to five restaurant recommendations tailored to a specific user. For existing users in the dataset, pass their `user_id` and the API infers preferences from their review history. For new users with no history, pass `cold_start_signals` — a city, food preference, and price range — to get sensible recommendations right away. You can also provide an optional free-text query or GPS coordinates to further refine results.

## Request

```text theme={null}
POST https://naijataste-api-vcp4.onrender.com/recommend
```

You must provide either `user_id` or `cold_start_signals`. The API returns `422` if neither is present.

### Body

<ParamField body="user_id" type="string">
  An ID from the built-in review dataset. The API derives preferences from this user's review history. Use this or `cold_start_signals`, not both. For new users or custom integrations, use `cold_start_signals` instead.
</ParamField>

<ParamField body="cold_start_signals" type="object">
  Preference signals for a new user with no review history. Use this or `user_id`, not both.

  <Expandable title="cold_start_signals properties">
    <ParamField body="city" type="string" required>
      The city to search in (e.g. `"Lagos"`).
    </ParamField>

    <ParamField body="preferred_food" type="string" required>
      A description of the user's food preference (e.g. `"local Nigerian buka amala"`).
    </ParamField>

    <ParamField body="price_range" type="string" required>
      The user's preferred price range. One of `"budget"`, `"mid"`, `"moderate"`, `"premium"`, or `"luxury"`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="query" type="string">
  An optional free-text search query to further narrow results (e.g. `"suya near Wuse"`).
</ParamField>

<ParamField body="user_lat" type="number">
  Optional GPS latitude of the user's current location (e.g. `6.4281`). Used to prioritize nearby restaurants.
</ParamField>

<ParamField body="user_lng" type="number">
  Optional GPS longitude of the user's current location (e.g. `3.4219`). Used together with `user_lat`.
</ParamField>

## Response

The response is an array of up to five recommendation objects.

<ResponseField name="item_name" type="string" required>
  The name of the recommended restaurant.
</ResponseField>

<ResponseField name="business_id" type="string">
  The Google Places `place_id` for this restaurant (e.g. `"ChIJxxxxxxx"`). May be `null` if no Places match was found.
</ResponseField>

<ResponseField name="reason" type="string" required>
  A short explanation of why this restaurant was recommended, taking the user's preferences into account.
</ResponseField>

<ResponseField name="predicted_rating" type="number" required>
  The predicted star rating this user would give the restaurant, on a 1–5 scale.
</ResponseField>

<ResponseField name="cultural_note" type="string">
  An optional tip about visiting this restaurant — for example, the best time to go or crowds to expect.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://naijataste-api-vcp4.onrender.com/recommend \
    --header "Content-Type: application/json" \
    --data '{
      "cold_start_signals": {
        "city": "Lagos",
        "preferred_food": "local Nigerian buka amala",
        "price_range": "budget"
      },
      "query": "suya near Wuse",
      "user_lat": 6.4281,
      "user_lng": 3.4219
    }'
  ```

  ```json Response theme={null}
  [
    {
      "item_name": "Mama Cass Restaurant",
      "business_id": "ChIJxxxxxxx",
      "reason": "Affordable local Nigerian food matching budget preference",
      "predicted_rating": 4.2,
      "cultural_note": "Best for weekday lunch, avoid weekend rush"
    }
  ]
  ```
</CodeGroup>

## Errors

| Status | Cause                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------- |
| `422`  | Neither `user_id` nor `cold_start_signals` was provided, or required `cold_start_signals` fields are missing. |
| `502`  | The Gemini AI layer returned an unexpected or unparseable response.                                           |
| `503`  | The Gemini AI service is unavailable or not configured.                                                       |