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

# GET /api/intents/popular — trending food intent queries

> Retrieve trending food delivery queries for a district, city, or country, ranked by unique user demand. Use them as chat suggestions or trend feeds.

The Popular Intents endpoint surfaces the food queries that real users in a given area are actively searching for. You can use it to build trend feeds, auto-populate chat starter chips, or understand what dishes are in demand at any geographic level — from a single Riyadh district down to a country-wide view.

## Endpoint

```
GET /api/intents/popular
```

**Authentication:** Not required

**Rate limit:** 60 requests per minute

***

## Query parameters

<ParamField query="district" type="string">
  Filter results to a specific district, provided in Arabic. When a qualifying
  number of signals exist at this level, the response scope resolves to
  `district`. Example: `العليا`
</ParamField>

<ParamField query="city" type="string">
  Filter results to a city, provided in Arabic. Used as a fallback scope when
  district-level data does not meet the minimum signal threshold. Example:
  `الرياض`
</ParamField>

<ParamField query="limit" type="number" default="10">
  Maximum number of intent records to return. Accepted range is 1–50.
</ParamField>

***

## Scope resolution

PRIXO resolves the narrowest scope that holds enough qualifying data before widening outward:

1. **District** — used when the district has sufficient unique-user signals
2. **City** — used as a fallback when the district does not qualify
3. **Country** — the default when neither district nor city qualifies

Each intent in the response includes a `scope` field that tells you which level the result came from, and a `scope_name` field that names it.

***

## Tier values

Every intent carries a `tier` that reflects how many unique users drove it:

| Tier     | Minimum unique users |
| -------- | -------------------- |
| `high`   | 10 or more           |
| `medium` | 5 or more            |
| `low`    | 3 or more            |

<Note>
  Intents with fewer than 3 unique user signals are assigned the `hidden` tier
  internally and are **never returned** by this endpoint. All results you
  receive are from actively trending queries.
</Note>

***

## Response fields

<ResponseField name="intents" type="array">
  Ordered array of trending intent objects, ranked by unique user demand
  (descending).

  <Expandable title="Intent object fields">
    <ResponseField name="intent_slug" type="string">
      URL-safe identifier for the intent, e.g. `shawarma`.
    </ResponseField>

    <ResponseField name="label" type="string">
      Human-readable display label in Arabic, e.g. `شاورما`.
    </ResponseField>

    <ResponseField name="tier" type="string">
      Demand tier: `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="scope" type="string">
      The geographic level this result was resolved at: `district`, `city`, or
      `country`.
    </ResponseField>

    <ResponseField name="scope_name" type="string">
      The name of the resolved scope area, e.g. `العليا` or `الرياض`.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Example

### Request

```bash theme={null}
GET /api/intents/popular?district=العليا&limit=5
```

### Response

```json theme={null}
{
  "intents": [
    {
      "intent_slug": "shawarma",
      "label": "شاورما",
      "tier": "high",
      "scope": "district",
      "scope_name": "العليا"
    },
    {
      "intent_slug": "burger",
      "label": "برجر",
      "tier": "medium",
      "scope": "city",
      "scope_name": "الرياض"
    },
    {
      "intent_slug": "kabsa",
      "label": "كبسة",
      "tier": "medium",
      "scope": "district",
      "scope_name": "العليا"
    },
    {
      "intent_slug": "pizza",
      "label": "بيتزا",
      "tier": "low",
      "scope": "city",
      "scope_name": "الرياض"
    },
    {
      "intent_slug": "sushi",
      "label": "سوشي",
      "tier": "low",
      "scope": "country",
      "scope_name": "SA"
    }
  ]
}
```

***

## Freshness

<Note>
  Popular intents are rebuilt **hourly** from accumulated user signals. Newly
  trending queries may take up to 60 minutes to appear in responses.
</Note>

***

## Use cases

<Tip>
  Embed this endpoint in your own app to power a live trending-food widget,
  or use the returned `intent_slug` values as pre-filled queries to the PRIXO
  [chat endpoint](/api/chat) so users jump straight to relevant price
  comparisons.
</Tip>

* **Chat starter chips** — fetch the top 5–8 intents for the user's district and display them as quick-tap suggestions before they type anything.
* **Trending feed** — build a "what's popular near you" section that refreshes hourly.
* **Analytics** — track which food categories trend in different Riyadh districts over time.