> ## 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/leaderboard — community contributor rankings

> Retrieve PRIXO's community leaderboard of top price contributors. Filter by country, city, or district. Returns contribution counts and trust levels.

The Leaderboard endpoint returns a ranked list of PRIXO's most active price contributors for any geographic scope. Use it to celebrate top contributors in a specific district, show a community-wide ranking, or surface your users' relative standing. Only contributors who have opted in to public visibility appear here — no private user data is ever exposed.

## Endpoint

```
GET /api/leaderboard
```

**Authentication:** Not required

***

## Query parameters

<ParamField query="scope" type="string" default="country">
  The geographic level to rank contributors within. Accepted values:

  * `country` — all of Saudi Arabia
  * `city` — a specific city (pair with `area`)
  * `district` — a specific district (pair with `area`)
</ParamField>

<ParamField query="area" type="string">
  The name of the city or district to filter by, in Arabic. Required when
  `scope` is `city` or `district`. Example: `العليا`
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of contributors to return. Accepted range is 1–100.
</ParamField>

***

## Response fields

<ResponseField name="leaderboard" type="array">
  Ordered array of contributor objects, ranked by contribution count
  (descending).

  <Expandable title="Contributor object fields">
    <ResponseField name="username" type="string">
      The contributor's public username.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The contributor's chosen display name.
    </ResponseField>

    <ResponseField name="avatar_url" type="string">
      URL of the contributor's avatar image.
    </ResponseField>

    <ResponseField name="contribution_count" type="number">
      Total number of accepted price contributions by this user within the
      requested scope.
    </ResponseField>

    <ResponseField name="points_balance" type="number">
      Current points balance earned by this user.
    </ResponseField>

    <ResponseField name="trust_level" type="object">
      The user's current trust level badge.

      <Expandable title="Trust level fields">
        <ResponseField name="name_ar" type="string">
          Trust level name in Arabic, e.g. `خبير`.
        </ResponseField>

        <ResponseField name="name_en" type="string">
          Trust level name in English, e.g. `Expert`.
        </ResponseField>

        <ResponseField name="icon" type="string">
          Emoji icon representing the trust level, e.g. `⭐`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rank" type="number">
      The contributor's numeric rank position within the returned list,
      starting at `1`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of eligible public contributors in the requested scope, before
  the `limit` is applied. Useful for pagination or showing "X of Y
  contributors".
</ResponseField>

***

## Privacy

<Note>
  Only users who have explicitly set `show_public_profile` to `true` are
  included in leaderboard results. The following fields are **never returned**
  by this endpoint: email address, phone number, physical location data, and
  points ledger history.
</Note>

***

## Example

### Request

```bash theme={null}
GET /api/leaderboard?scope=district&area=العليا&limit=10
```

### Response

```json theme={null}
{
  "leaderboard": [
    {
      "username": "user123",
      "display_name": "Ahmed",
      "avatar_url": "https://cdn.prixo.ai/avatars/user123.jpg",
      "contribution_count": 142,
      "points_balance": 3850,
      "trust_level": {
        "name_ar": "خبير",
        "name_en": "Expert",
        "icon": "⭐"
      },
      "rank": 1
    },
    {
      "username": "sara_r",
      "display_name": "Sara",
      "avatar_url": "https://cdn.prixo.ai/avatars/sara_r.jpg",
      "contribution_count": 98,
      "points_balance": 2410,
      "trust_level": {
        "name_ar": "محترف",
        "name_en": "Pro",
        "icon": "🏆"
      },
      "rank": 2
    }
  ],
  "total": 47
}
```

***

## Use cases

<Tip>
  Combine the `scope=district` leaderboard with the [Popular Intents
  endpoint](/api/intents) to build a neighborhood dashboard — show who's
  contributing the most prices for the foods trending near the user.
</Tip>

* **Community pages** — display top contributors per district to drive healthy competition.
* **In-app leaderboard widget** — show a user their rank and the two people just above them to encourage more contributions.
* **Country-wide rankings** — use the default `scope=country` call to feature PRIXO's most dedicated contributors platform-wide.