POST /simulate-review — Generate a Nigerian review

Generate an authentic Nigerian restaurant review with a star rating, review text, and tone label by supplying a user persona and restaurant features.

The /simulate-review endpoint takes a user persona and a set of restaurant features, then returns a contextually authentic Nigerian restaurant review. The persona drives the reviewer’s tone, price sensitivity, and rating tendency, while the features shape what the review focuses on. Most integrations supply a persona object directly; the user_id field is an alternative that resolves a persona from the built-in review dataset.

Request

POST https://naijataste-api-vcp4.onrender.com/simulate-review

You must provide either user_id or persona — not both, not neither. The API returns 422 if neither field is present.

Body

user_id · string

An ID from the built-in review dataset. The API resolves the full persona automatically. Use this or persona, not both. Most integrations should use persona directly.

persona · object

A persona object supplied directly. Use this or user_id, not both.

Show persona properties

user_id · string

An optional identifier for this persona, used for traceability.

avg_rating · number

The reviewer’s historical average star rating (e.g. 3.2).

rating_tendency · string

How the reviewer typically skews their ratings. One of "harsh", "balanced", or "generous".

price_sensitivity · string

How strongly the reviewer reacts to price. One of "high", "medium", or "low".

tone_keywords · string[]

A list of topics this reviewer commonly mentions, such as ["jollof", "service", "price", "portion"].

total_reviews · number

The total number of reviews this persona has written.

sample_reviews · string[]

One or more example reviews written by this persona, used to calibrate writing style.

item_name · string · required

The name of the restaurant or food item being reviewed (e.g. "Yellow Chilli Victoria Island").

item_type · string · required

The type of item. Typically "restaurant".

location · string · required

The city or area where the restaurant is located (e.g. "Lagos").

features · string[] · required

A list of attributes describing the restaurant’s experience (e.g. ["expensive", "nice ambience", "average food", "fast service"]). These shape what the generated review focuses on.

Response

rating · number · required

An integer star rating from 1 to 5, consistent with the persona’s rating tendency and the provided features.

review_text · string · required

The generated review text, written in a tone matching the persona. May include Nigerian Pidgin English phrases.

tone_label · string · required

Describes the language style of the generated review. One of "pidgin-heavy", "mixed", "formal", or "casual".

Example

cURL

curl -X POST https://naijataste-api-vcp4.onrender.com/simulate-review \
  --header "Content-Type: application/json" \
  --data '{
    "persona": {
      "user_id": "demo_user",
      "avg_rating": 3.2,
      "rating_tendency": "harsh",
      "price_sensitivity": "high",
      "tone_keywords": ["jollof", "service", "price", "portion"],
      "total_reviews": 45,
      "sample_reviews": ["The food was okay but too expensive for the portion size"]
    },
    "item_name": "Yellow Chilli Victoria Island",
    "item_type": "restaurant",
    "location": "Lagos",
    "features": ["expensive", "nice ambience", "average food", "fast service"]
  }'

Errors

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