# /ppp Endpoint

> Look up a country's PPP factor for a year and read the default year, alpha-3 handling, projection flag, and response fields.

Canonical: https://currency-core.com/docs/ppp-endpoint/
Updated: 2026-11-10
Published: 2026-11-10

---
## Endpoint

```
GET https://api.currency-core.com/v1/ppp
```

Returns the purchasing-power-parity (PPP) conversion factor for one country in one year. The factor is **local currency units per international dollar**, sourced from the IMF World Economic Outlook. It is the same factor used by [`/v1/convert?ppp=true`](/docs/convert-endpoint/).

This is a single-point lookup, not a time series. For trends, country comparisons, and movers, use [`/v1/ppp/analysis`](/docs/ppp-analysis-endpoint/). For FX rates, use [`/v1/rates`](/docs/rates-endpoint/).

## Plan requirement

`/v1/ppp` requires a valid API key but has **no Growth tier gate**. It is metered like any other keyed request: one call consumes one request against your monthly quota and the per-minute rate limit. On the Free plan, use a test key, because live keys require a paid plan. See [Pricing](/pricing/) for quotas.

## Query parameters

| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| `country` | string | Yes | none | ISO 3166-1 **alpha-3** country code, e.g. `IND`, `USA`, `DEU`. The value is uppercased and used as-is. Alpha-2 codes and country names are not resolved by this endpoint. |
| `year` | number | No | `2024` | Four-digit integer year. Must be between `1980` and `2100`. Fractional values and non-4-digit strings are rejected. |

Only **one country per request** is accepted. To compare countries or fetch a range of years, call [`/v1/ppp/analysis`](/docs/ppp-analysis-endpoint/) instead.

## Country and currency handling

`/v1/ppp` has no `currency` parameter. The response identifies the country, and the factor is denominated in that country's local currency. To see which currency a country uses, call [`/v1/countries`](/docs/countries/) and read its `currencies` array.

For a PPP-adjusted amount in a specific currency, use [`/v1/convert?ppp=true`](/docs/convert-endpoint/), which takes `currency:country` pairs such as `INR:IND`. The raw factor endpoint is useful when you want the price level itself rather than a converted amount.

## Response

```json
{
  "year": 2024,
  "countryCode": "IND",
  "pppFactor": 20.397,
  "projected": false
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `year` | number | The year the factor applies to. Echoes the requested year, or the configured default when omitted. |
| `countryCode` | string | The uppercased alpha-3 country code used for the lookup. |
| `pppFactor` | number | PPP conversion factor: local currency units per international dollar. |
| `projected` | boolean | `true` when the value is an IMF projection (forecast), `false` when it is actual data. |

## Reading the factor

A PPP factor is a **price level**, not an exchange rate. A factor of `20.4` for India means that goods costing one international dollar in the United States would cost about 20.4 units of Indian currency in India at PPP. The market FX rate can be very different, so do not use this number as a currency quote.

- A **rising** factor over time means the country's price level rose relative to the international dollar.
- A **falling** factor means its price level fell relative to the international dollar.
- `projected: true` marks forecast years. For historical analysis, prefer actual values or treat projections separately.

The endpoint returns the figure objectively; whether a change is "good" or "bad" depends on your use case.

## Example requests

<CodeTabs>
<Fragment slot="curl">

```bash
curl "https://api.currency-core.com/v1/ppp?country=IND&year=2024" \
  -H "Authorization: Bearer cc_live_your_key"
```

</Fragment>
<Fragment slot="js">

```js
const res = await fetch(
  "https://api.currency-core.com/v1/ppp?country=IND&year=2024",
  { headers: { Authorization: "Bearer cc_live_your_key" } },
);
const { countryCode, pppFactor, projected } = await res.json();
console.log(countryCode, pppFactor, projected);
```

</Fragment>
<Fragment slot="python">

```python

res = requests.get(
    "https://api.currency-core.com/v1/ppp",
    params={"country": "IND", "year": 2024},
    headers={"Authorization": "Bearer cc_live_your_key"},
)
print(res.json()["pppFactor"])
```

</Fragment>
</CodeTabs>

Use the default year by omitting `year`:

```bash
curl "https://api.currency-core.com/v1/ppp?country=DEU" \
  -H "Authorization: Bearer cc_live_your_key"
```

## Common uses

- **Price-level research:** compare a country's PPP factor across years without converting an amount.
- **Validation:** confirm the factor behind a `/convert?ppp=true` result for the same country and year.
- **Dashboards:** cache one factor per country and year, then label it clearly as a price level, not an FX rate.

Do not use this endpoint as a substitute for a market exchange rate. Use [`/v1/rates`](/docs/rates-endpoint/) or [`/v1/convert`](/docs/convert-endpoint/) for nominal FX.

## Errors

| Status | Code | When |
|---|---|---|
| `400` | `invalid_input` | `country` is missing, or `year` is not a 4-digit integer, is below `1980`, or is above `2100`. |
| `401` | `unauthorized` | The `Authorization` header is missing or the key is invalid. |
| `403` | `forbidden` | The key is disabled, billing is past due, or a live key is used on the Free plan. |
| `404` | `unknown_ppp` | No PPP factor exists for that country and year. |
| `429` | `rate_limited` | The per-minute rate limit was exceeded. Honor the `Retry-After` header. |

A country that is not in the dataset and a country with no data for the requested year both return `404 unknown_ppp`.

## Limits and related

- One country and one year per request; there is no batch mode on this path.
- The default year comes from the deployed configuration (`PPP_YEAR`), currently `2024`.
- Factors are read from the same PPP dataset used by conversions and analysis, so a factor returned here matches the one used by `/v1/convert?ppp=true` for that year.

Related pages:

- [`/v1/ppp/analysis`](/docs/ppp-analysis-endpoint/) for trends and comparisons
- [`/v1/convert`](/docs/convert-endpoint/) for PPP-adjusted amounts
- [`/v1/countries`](/docs/countries/) for country codes and official currencies
- [PPP calculator](/tools/ppp-calculator/) for a no-code check
- [Pricing](/pricing/) and [rate limits](/docs/authentication/) for quotas