# Gini Index (Income Inequality) API
> Income-inequality data for every country as an API — the World Bank Gini index, the standard measure of how evenly income is distributed. The coefficient runs from 0 (perfect equality) to 100 (one person holds all income); a higher number means a more unequal society. For each of 170+ countries the API returns the latest available value, the full year-by-year history and the all-time minimum and maximum, enriched with the ISO 3166-1 alpha-2 code and flag emoji. Look a country up by name or code, RANK countries by their latest inequality (the most or least equal in the world), search, or list them all. The reference an economics dashboard, data-journalism piece or research tool needs. Distinct from countrystats-api (area, population, life expectancy) — this is the inequality series specifically, with per-country history. Served from memory — always fast.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/gini-api/..."
```

## Pricing
- **Free** (Free) — 14,000 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 160,000 calls/Mo, 10 req/s
- **Pro** ($20/Mo) — 800,000 calls/Mo, 25 req/s
- **Mega** ($46/Mo) — 4,000,000 calls/Mo, 60 req/s

## Endpoints

### Lookup

#### `GET /v1/country` — Gini data for a country

**Parameters:**
- `country` (query, optional, string) — Country name Example: `Brazil`
- `code` (query, optional, string) — ISO alpha-2 or alpha-3 code Example: `BRA`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gini-api/v1/country?country=Brazil&code=BRA"
```

**Response:**
```json
{
    "data": {
        "country": {
            "max": 63.2,
            "min": 48.9,
            "code": "BR",
            "emoji": "🇧🇷",
            "alpha3": "BRA",
            "latest": {
                "gini": 51.6,
                "year": 2023
            },
            "country": "Brazil",
            "history": [
                {
                    "gini": 57.9,
                    "year": 1981
                },
                {
                    "gini": 58.4,
                    "year": 1982
                },
                {
                    "gini": 58.9,
                    "year": 1983
                },
                {
                    "gini": 58.3,
                    "year": 1984
                },
                {
                    "gini": 55.5,
                    "year": 1985
                },
                {
                    "gini": 58.4,
                    "year": 1986
                },
                {
                    "gini": 59.6,
                    "year": 1987
                },
                {
                    "gini": 61.4,
                    "year": 1988
                },
                {
                    "gini": 63.2,
                    "year": 1989
                },
                {
                    "gini": 60.5,
                    "year": 1990
                },
                {
                    "gini": 53.1,
                    "year": 1992
                },
                {
       
…(truncated, see openapi.json for full schema)
```

### Rank

#### `GET /v1/rank` — Rank countries by latest Gini

**Parameters:**
- `order` (query, optional, string) — desc (most unequal) or asc (most equal) Example: `desc`
- `limit` (query, optional, string) — How many (1-250) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gini-api/v1/rank?order=desc&limit=10"
```

**Response:**
```json
{
    "data": {
        "basis": "latest available Gini index",
        "count": 10,
        "order": "desc",
        "ranking": [
            {
                "max": 64.8,
                "min": 57.8,
                "code": "ZA",
                "gini": 63,
                "rank": 1,
                "year": 2014,
                "emoji": "🇿🇦",
                "alpha3": "ZAF",
                "latest": {
                    "gini": 63,
                    "year": 2014
                },
                "country": "South Africa",
                "history": [
                    {
                        "gini": 59.3,
                        "year": 1993
                    },
                    {
                        "gini": 57.8,
                        "year": 2000
                    },
                    {
                        "gini": 64.8,
                        "year": 2005
                    },
                    {
                        "gini": 63,
                        "year": 2008
                    },
                    {
                        "gini": 63.4,
                        "year": 2010
                    },
                    {
                        "gini": 63,
                        "year": 2014
                    }
                ]
            },
            {
                "max": 71.1,
                "min": 59.1,
                "code": "NA",
                "gini": 59.1,
                "rank": 2,
                "year
…(truncated, see openapi.json for full schema)
```

### Search

#### `GET /v1/search` — Search by country name or code

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `south`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gini-api/v1/search?q=south&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "query": "south",
        "total": 2,
        "countries": [
            {
                "max": 64.8,
                "min": 57.8,
                "code": "ZA",
                "emoji": "🇿🇦",
                "alpha3": "ZAF",
                "latest": {
                    "gini": 63,
                    "year": 2014
                },
                "country": "South Africa",
                "history": [
                    {
                        "gini": 59.3,
                        "year": 1993
                    },
                    {
                        "gini": 57.8,
                        "year": 2000
                    },
                    {
                        "gini": 64.8,
                        "year": 2005
                    },
                    {
                        "gini": 63,
                        "year": 2008
                    },
                    {
                        "gini": 63.4,
                        "year": 2010
                    },
                    {
                        "gini": 63,
                        "year": 2014
                    }
                ]
            },
            {
                "max": 46.3,
                "min": 44,
                "code": "SS",
                "emoji": "🇸🇸",
                "alpha3": "SSD",
                "latest": {
                    "gini": 44,
                    "year": 2016
                },
         
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List all countries

**Parameters:**
- `limit` (query, optional, string) — Page size (1-300) Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gini-api/v1/list?limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 171,
        "countries": [
            {
                "max": 34.6,
                "min": 27,
                "code": "AL",
                "emoji": "🇦🇱",
                "alpha3": "ALB",
                "latest": {
                    "gini": 29.4,
                    "year": 2020
                },
                "country": "Albania",
                "history": [
                    {
                        "gini": 27,
                        "year": 1996
                    },
                    {
                        "gini": 31.7,
                        "year": 2002
                    },
                    {
                        "gini": 30.6,
                        "year": 2005
                    },
                    {
                        "gini": 30,
                        "year": 2008
                    },
                    {
                        "gini": 29,
                        "year": 2012
                    },
                    {
                        "gini": 34.6,
                        "year": 2014
                    },
                    {
                        "gini": 32.8,
                        "year": 2015
                    },
                    {
                        "gini": 33.7,
                        "year": 2016
                    },
                    {
                        "gini": 33.1,
                        "year": 2017
                
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gini-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "gini-api",
        "endpoints": {
            "GET /v1/list": "List all countries (limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/rank": "Rank countries by latest Gini (order=desc most unequal | asc most equal, limit).",
            "GET /v1/search": "Search by country name or code (q=).",
            "GET /v1/country": "Gini data for a country: latest, history, min/max (country=, e.g. Brazil — or code=, e.g. BR/BRA)."
        },
        "description": "World Bank Gini-index (income inequality, 0=perfect equality … 100=maximal inequality) for every country: latest value, full year-by-year history and all-time min/max, enriched with ISO 3166-1 alpha-2 code and flag emoji. Look up by country or code, rank by latest inequality, search or list. No key.",
        "total_countries": 171,
        "most_recent_year": 2024
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:06.785Z",
        "request_id": "9a45d01c-e8c8-4648-9b35-11ac8acc1fa9"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/gini-api
OpenAPI spec: https://www.oanor.com/api/gini-api/openapi.json