# Salary statistics

> GET /v1/insights/salaries returns yearly pay statistics from public jobs that state pay: minimum, quartiles, median and maximum by category and country.

- Source: https://greenhired.com/developers/api/v1/salaries/
- Section: GreenHired developers · API · Public jobs API
- Last updated: 2026-11-21

## The request

`GET /v1/insights/salaries` returns yearly pay statistics from the live jobs that state pay. Groups are by category, by country or by both. Currencies are never mixed or converted, so every figure is for one currency.

**`GET https://api.greenhired.com/v1/insights/salaries`** (permission `insights:read`): Yearly pay statistics from advertised pay.

| Parameter | Meaning |
| --- | --- |
| `group_by` | `category` (the default), `country`, or both: `category,country` |
| `category` | Filter to these category slugs |
| `country` | Filter to these countries, as written on the jobs |
| `currency` | An ISO 4217 code such as `EUR` |

*curl*

```bash
curl -s "https://api.greenhired.com/v1/insights/salaries?group_by=category,country&currency=EUR" \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/insights/salaries?group_by=category,country&currency=EUR', {
  headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY },
});
const { data, meta } = await res.json();
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/insights/salaries",
    params={"group_by": "category,country", "currency": "EUR"},
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
    timeout=15,
)
body = res.json()
```

## What you get

Each group has `category`, `country`, `currency`, `period` (always `year`), `sample_size`, `min`, `p25`, `median`, `p75` and `max`. The answer is `{ "data": [ ... ], "meta": { ... } }`, where `meta` has `period`, `min_sample_size`, `group_by` and `truncated`. The figures can be up to five minutes old.

**One group (the numbers are an example)**

```json
{
  "category": "renewable-energy",
  "country": "Germany",
  "currency": "EUR",
  "period": "year",
  "sample_size": 18,
  "min": 41000,
  "p25": 52000,
  "median": 63000,
  "p75": 74000,
  "max": 98000
}
```

> **Note:** These are statistics of advertised pay, not of what people are paid.

## How salary figures are made

1. **Which jobs:** the jobs `/v1/jobs` would show (live, one copy each, only sources the API may serve) that state a pay range or a single amount with a currency and a known period.
2. **One number per job:** the middle of `min` and `max`, or the one amount given.
3. **To a year:** year x 1, month x 12, week x 52, day x 260, hour x 2080 (a full-time year). A job whose period is missing or unknown is left out, never guessed. `salary_min` on `/v1/jobs` uses the same factors.
4. **Currencies are never mixed or converted:** a group exists once per currency.
5. **Groups:** by category, by country (as written on the job, letter case ignored; a job without a country is left out when grouping by country), or by both.
6. **Privacy and noise:** a group with fewer than 5 jobs is not returned at all, so `sample_size` is always 5 or more.
7. **Statistics:** `min` and `max` are the lowest and highest yearly figure. `p25`, `median` and `p75` use linear interpolation between the two nearest values. All are rounded to whole numbers.
8. **Size:** one answer reads at most the 20,000 most recent salary jobs. `meta.truncated` tells you if that cut anything.

## Frequently asked questions

**Why is my category or country missing from the answer?**

A group with fewer than 5 jobs that state pay is not returned, to keep the figures meaningful and to avoid pointing at one employer. Try grouping by category only, or removing the country filter.

**Are the figures converted to one currency?**

No. Every group is for one currency, and a category with pay in EUR and GBP appears twice. Convert on your side if you need one number, and say which rates you used.

**Are these real salaries?**

No. They describe the pay employers advertised in live jobs. Actual pay can differ.

**How often do the figures change?**

They can be up to five minutes old. Cache them for at least that long.

## Related pages

- https://greenhired.com/developers/api/v1/jobs/
- https://greenhired.com/developers/api/v1/categories/
- https://greenhired.com/developers/api/v1/limits/
