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

# NaijaTaste REST API overview

> What the NaijaTaste REST API does, the base URL, the six endpoints for recommendations and reviews, request formats, and how errors are returned.

The NaijaTaste REST API lets you programmatically generate Nigerian-style restaurant reviews and get personalized restaurant recommendations powered by the Nigerian Persona Engine. You can integrate review simulation, location-based discovery, and restaurant detail lookups directly into your own application using standard HTTP requests.

## Base URL

All API requests go to the following base URL:

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

<Tip>
  Use the interactive Swagger UI at [https://naijataste-api-vcp4-vcp4.onrender.com/docs](https://naijataste-api-vcp4.onrender.com/docs) to explore and test all endpoints without writing any code.
</Tip>

## Making requests

Every request and response uses JSON. Set the `Content-Type` header to `application/json` on all requests that include a body.

```bash theme={null}
curl -X GET https://naijataste-api-vcp4.onrender.com/health
```

The API returns a JSON object for every response, including errors.

## Available endpoints

| Method | Path                        | Description                                 |
| ------ | --------------------------- | ------------------------------------------- |
| `POST` | `/simulate-review`          | Generate a Nigerian-style restaurant review |
| `POST` | `/recommend`                | Get personalized restaurant recommendations |
| `GET`  | `/places/top-picks`         | Get top-rated nearby restaurants            |
| `GET`  | `/place-details/{place_id}` | Get full details for a specific restaurant  |
| `GET`  | `/cache/stats`              | View cached Google Places query statistics  |
| `GET`  | `/health`                   | API health check                            |

## Error codes

The API uses standard HTTP status codes. When a request fails, the response body contains a JSON object with details about the error.

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `422` | Invalid or missing request fields |
| `500` | Internal server error             |
| `502` | Unexpected AI response            |
| `503` | External service unavailable      |

**422 Unprocessable Entity** is returned when required fields are missing from the request body — for example, when neither `user_id` nor `persona` is provided to `/simulate-review`, or when neither `user_id` nor `cold_start_signals` is provided to `/recommend`.

**503 Service Unavailable** is returned when an external dependency — Google Places or Gemini AI — cannot be reached or is not configured.

## Rate limiting

During high-traffic periods, the API's AI service layer may become temporarily rate-limited. If this happens, you will receive a `502` or `503` error response. Wait approximately 60 seconds before retrying your request.

<Warning>
  Implement retry logic with a short delay in production integrations. A 60-second wait before retrying is usually sufficient during peak periods.
</Warning>