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

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

user_id · 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.

cold_start_signals · object

Preference signals for a new user with no review history. Use this or user_id, not both.

Show cold_start_signals properties

city · string · required

The city to search in (e.g. "Lagos").

preferred_food · string · required

A description of the user’s food preference (e.g. "local Nigerian buka amala").

price_range · string · required

The user’s preferred price range. One of "budget", "mid", "moderate", "premium", or "luxury".

query · string

An optional free-text search query to further narrow results (e.g. "suya near Wuse").

user_lat · number

Optional GPS latitude of the user’s current location (e.g. 6.4281). Used to prioritize nearby restaurants.

user_lng · number

Optional GPS longitude of the user’s current location (e.g. 3.4219). Used together with user_lat.

Response

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

item_name · string · required

The name of the recommended restaurant.

business_id · string

The Google Places place_id for this restaurant (e.g. "ChIJxxxxxxx"). May be null if no Places match was found.

reason · string · required

A short explanation of why this restaurant was recommended, taking the user’s preferences into account.

predicted_rating · number · required

The predicted star rating this user would give the restaurant, on a 1–5 scale.

cultural_note · string

An optional tip about visiting this restaurant — for example, the best time to go or crowds to expect.

Example

cURL

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
  }'

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.