> ## 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.

# Recommendation Engine: Find Nigerian Restaurants

> Get ranked Nigerian restaurant picks from real Google Places data, personalised by your taste persona, city preference, or live GPS location.

The Recommendation Engine finds real Nigerian restaurants and ranks them by how well they match your taste profile. It pulls live data from the Google Places API, filters it for cultural relevance, and returns up to five picks with a reason, a predicted rating, and a cultural note for each. You can use it through the web app or call it directly from the API.

## How it works

The engine takes signals about what you want — your city, food preference, price range, and optionally your GPS coordinates — and queries Google Places for matching restaurants. It then scores each result against your persona or cold-start signals to produce a ranked list. Each recommendation includes why it was picked and practical cultural context, like the best time to visit.

<Info>
  Recommendations are powered by real-time Google Places data, so results reflect currently operating restaurants and may change over time.
</Info>

## Two ways to get recommendations in the app

You can reach the recommendation engine through either interface in the app:

<CardGroup cols={2}>
  <Card title="Chat mode" icon="message-circle" href="/guides/chat-mode">
    Type your craving in plain language — "cheap suya near me" or "family spot in Abuja" — and the engine interprets your intent automatically.
  </Card>

  <Card title="Form mode" icon="sliders-horizontal" href="/guides/form-mode">
    Fill in structured fields for city, food type, and price range. Good for precise queries when you know exactly what you want.
  </Card>
</CardGroup>

## Cold-start recommendations

New users without a review history can still get accurate picks. You provide a few signals — city, preferred food, and price range — and the engine uses those directly to find matches. This is called a cold-start request.

Cold-start signals are passed under the `cold_start_signals` key in the API request body. You don't need a `user_id`.

## GPS recommendations

When you grant location access in the app, your coordinates are included in the request. The engine uses them to surface restaurants within a short distance of where you are, ranked by proximity alongside cultural fit.

If you deny location access, the engine falls back to city-level recommendations using the city you specify or select. You still get relevant results — just not hyper-local ones.

## Supported cities

| City          | Country |
| ------------- | ------- |
| Lagos         | Nigeria |
| Abuja         | Nigeria |
| Port Harcourt | Nigeria |
| Ibadan        | Nigeria |
| Kano          | Nigeria |

## API usage

Send a `POST` request to `https://naijataste-api-vcp4.onrender.com/recommend`. The examples below show a cold-start request and a GPS-enabled request.

<CodeGroup>
  ```json Cold-start request theme={null}
  {
    "cold_start_signals": {
      "city": "Lagos",
      "preferred_food": "local Nigerian buka amala",
      "price_range": "budget"
    }
  }
  ```

  ```json GPS request theme={null}
  {
    "cold_start_signals": {
      "city": "Lagos",
      "preferred_food": "suya"
    },
    "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>

## Response fields

Each object in the response array contains these fields:

| Field              | Type   | Description                                                                                            |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| `item_name`        | string | The name of the restaurant as it appears in Google Places.                                             |
| `reason`           | string | A brief explanation of why this restaurant was recommended for your query.                             |
| `predicted_rating` | number | The engine's predicted rating for this restaurant given your persona or signals, on a scale of 1 to 5. |
| `cultural_note`    | string | Practical local context — for example, the best time to visit or what the crowd is typically like.     |