---
title: "World Bank Poverty and Inequality"
method: POST
path: "/global/world-bank/poverty/v1"
tags: ["Global", "World Bank"]
---

# World Bank Poverty and Inequality

`POST /global/world-bank/poverty/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/global/world-bank/poverty/v1`
- Auth: HTTP bearer

Poverty and inequality estimates from the World Bank's Poverty and Inequality Platform, country by year: the share of people below $3.00, $4.20 and $8.30 a day (2021 PPP), the poverty gap at each line, the Gini index, mean and median welfare, deciles, and the household survey behind each estimate. Filter by `country_code` (ISO3), `year` or `year_from`/`year_to`, `reporting_level` (`national`, `urban`, `rural`) and `welfare_type` (`income`, `consumption`). Served by Croma from its copy (`as_of` says how current the data is).

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `country_code` string: Optional three-letter ISO 3166-1 country code, e.g. `COL`, `BRA`, `MEX`.
  - `year` integer: Optional single year, e.g. `2024`. 0 means every year.
  - `year_from` integer: Optional first year of a range, e.g. `2015`. 0 means no lower bound.
  - `year_to` integer: Optional last year of a range, e.g. `2024`. 0 means no upper bound.
  - `reporting_level` '' | 'national' | 'urban' | 'rural': Optional coverage of the estimate: `national`, `urban` or `rural`. Some countries are covered by urban surveys only (Argentina), so leaving it empty returns every level.
  - `welfare_type` '' | 'income' | 'consumption': Optional welfare measure the survey records: `income` (most of Latin America) or `consumption`.
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-200).

## Response `200`

Successful response

- WorldBankPovertyResponse
  - `data` WorldBankPovertyData, required
    - `as_of` string, nullable, required: How current the data in this response is.
    - `country_code` string, nullable, required
    - `year` number, nullable, required
    - `year_from` number, nullable, required
    - `year_to` number, nullable, required
    - `reporting_level` string, nullable, required
    - `welfare_type` string, nullable, required
    - `total` number, required: Matches, counted up to 1000.
    - `total_is_exact` boolean, required: False when more than 1000 match: `total` is then 1000, and the pages go on.
    - `page` number, required
    - `per_page` number, required
    - `total_pages` number, required: Pages over `total`; there are more when `total_is_exact` is false.
    - `count` number, required
    - `results` object[], required
      - `id` string, required: The country, the year, the coverage and the welfare measure, e.g. "COL:2024:national:income".
      - `country_code` string, required: ISO 3166-1 three-letter code, e.g. "COL".
      - `country` string, required: The country's name, e.g. "Colombia".
      - `region_code` string, nullable, required: The World Bank region, e.g. "LCN" (Latin America and the Caribbean).
      - `year` number, required: The year the estimate refers to.
      - `survey_year` number, nullable, required: The year of the household survey behind the estimate; a fraction when the fieldwork spans two years (e.g. 2019.5).
      - `survey_acronym` string, nullable, required: The household survey, e.g. "GEIH" (Colombia), "PNADC" (Brazil), "ENIGH" (Mexico).
      - `survey_coverage` string, nullable, required: What the survey covers: "national", "urban" or "rural".
      - `reporting_level` string, required: The coverage of this estimate: "national", "urban" or "rural".
      - `welfare_type` string, required: The welfare measure: "income" or "consumption".
      - `comparable_spell` string, nullable, required: The run of years whose surveys are comparable with this one, e.g. "2021 - 2024". Compare across years only within a spell.
      - `headcount_300` number, nullable, required: Share of the population living below $3.00 a day per person (2021 PPP), from 0 to 1.
      - `headcount_420` number, nullable, required: Share of the population living below $4.20 a day per person (2021 PPP), from 0 to 1.
      - `headcount_830` number, nullable, required: Share of the population living below $8.30 a day per person (2021 PPP), from 0 to 1.
      - `poverty_gap_300` number, nullable, required: Poverty gap at $3.00 a day: the mean shortfall below the line as a share of it, from 0 to 1.
      - `poverty_gap_420` number, nullable, required: Poverty gap at $4.20 a day: the mean shortfall below the line as a share of it, from 0 to 1.
      - `poverty_gap_830` number, nullable, required: Poverty gap at $8.30 a day: the mean shortfall below the line as a share of it, from 0 to 1.
      - `gini` number, nullable, required: Gini index of the welfare distribution, from 0 (equality) to 1.
      - `mean` number, nullable, required: Mean welfare, in 2021 PPP dollars a day per person.
      - `median` number, nullable, required: Median welfare, in 2021 PPP dollars a day per person.
      - `mld` number, nullable, required: Mean log deviation, another inequality measure.
      - `polarization` number, nullable, required: Wolfson polarization index.
      - `deciles` number[], required: Share of total welfare held by each tenth of the population, poorest first.
      - `societal_poverty_line` number, nullable, required: The societal poverty line for the year, in 2021 PPP dollars a day.
      - `population` number, nullable, required: The population the estimate covers.
      - `is_interpolated` boolean, required: True when the estimate is interpolated between surveys rather than read from one.
      - `estimation_type` string, nullable, required: "survey" when read from a survey of that year, otherwise how it was estimated.
      - `distribution_type` string, nullable, required: "micro" (survey microdata), "group" (grouped data) or "aggregate".

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)