# Salary Data API manual Official pay figures from national statistics offices, through one API. Base address: https://api.salarydataapi.com/v1. Send your key in `Authorization: Bearer ` or `X-API-Key`. Every answer is `{"data": ..., "meta": {...}}`, or `{"error": {"code", "message", "docs"}}`. This file is made from the registry each time it is read. ## Quick start Three steps: a key, a call, an answer. Every endpoint page has Run, so you can also do all of this in the browser. ### 1. Get a key Sign in with Google at salarydataapi.com/signup. A free key is made at once and shown once; it is also saved in this browser, so every documentation page has it in Try it. ### 2. Make the first call A country's median yearly pay, the latest period: ``` curl "https://api.salarydataapi.com/v1/pay?country=gb&series=pay.median.yearly" \ -H "Authorization: Bearer YOUR_KEY" ``` ### 3. Read the answer Every answer has the same shape: the figures in `data`, the paging and any notes in `meta`. ``` { "data": [ { "series": "se_4762t04r", "name": "pay.median.yearly", "country": "gb", "period": "2025", "value": 32890.0, "currency": "GBP", "value_usd": null, "occupation": null, "sex": "all" } ], "meta": { "count": 1, "plan": "free", "value_usd": "In US dollars with Pro and above" } } ``` Next: how figures are named, every parameter of /v1/pay, and every country. ## Authentication Every call but `GET /` needs your key. Send it in one of two headers; both work the same. ``` Authorization: Bearer sda_live_... X-API-Key: sda_live_... ``` A key in the address (`?key=`) is refused with `bad_request`, so keys never end up in logs or browser history. ### Your key One key per account, made when you sign up. It is shown in full once, when it is made, and saved in that browser for these pages. We keep only a fingerprint of it, so we cannot show it again. ### Replacing it In your account, under Keys: Replace the key. A new key is made and shown once, and the old one stops at once, so anything still using it gets `unauthorized` until it has the new one. ### Your plan follows your account The plan is read from the account on every call, never from the key. An upgrade counts from the next call, with the same key. ## Plans and limits Each plan has an allowance of calls (a day for the free key, a month for the others) and a number of calls a second. Over the allowance, calls are refused with `quota_exceeded`: nothing is ever billed beyond the plan. PlanCallsPer secondPeriodsAdds | Free key | 50 a day | 1 | the latest | | Starter | 10,000 a month | 5 | the latest 3 years | breakdowns | Pro | 100,000 a month | 10 | full history | breakdowns, US dollars | Analyst | 500,000 a month | 20 | full history | breakdowns, US dollars, one role across countries, pay gaps, MCP ### The headers on every answer | X-RateLimit-Limit | Calls a second on this plan | X-RateLimit-Remaining | Calls left in this second | X-RateLimit-Reset | When this second ends (Unix seconds) | X-Quota-Limit | The day's or month's allowance | X-Quota-Remaining | Calls left in it | X-Quota-Reset | When it starts again (Unix seconds) | Retry-After | On a 429: seconds to wait ### What a smaller plan sees An endpoint above the plan answers `upgrade_required`, naming the plan that has it. Asking a plan for something it does not include (a breakdown on the free key, periods before its first year) does the same. A field the plan does not include, such as `value_usd` below Pro, comes back as `null` with a note in `meta`, so code written on one plan keeps working on the next. `GET /v1/usage` shows your plan, your calls today and this month, and when the allowance starts again. It never counts. Every plan in full on pricing. ## Pagination Every list takes `page` (from 1) and `per_page` (50 by default, at most 200), or a `cursor`. ### Pages The first answer's `meta` has `count`, `page`, `per_page`, `total`, `total_pages`, `next_page`, `prev_page` (null at the ends) and `next_cursor`. ``` "meta": { "count": 50, "next_cursor": "YzUw", "page": 1, "per_page": 50, "total": 140, "total_pages": 3, "next_page": 2, "prev_page": null } ``` ### Cursors Send `cursor=` with `next_cursor` as it came to carry on from where the last answer stopped. A cursor answer has only `count` and `next_cursor`, so it stays fast however far you go; `next_cursor` is null at the end. When `page` and `cursor` are both sent, `page` wins. ## Errors An error answer has no `data`, only `error`: a `code` that never changes, a `message` for people, and `docs`, a link to read more. `upgrade_required` also names the `plan`. ``` { "error": { "code": "upgrade_required", "message": "Rank countries comes with Pro and above. This key is on Free key.", "plan": "pro", "pricing": "https://salarydataapi.com/pricing", "docs": "https://salarydataapi.com/documentation/plans-and-limits" } } ``` CodeHTTPWhat it means, and what to do | bad_request | 400 | A value is not what the parameter takes, a required one is missing, or a key was sent in the address. Read the message: it names the parameter and what it should be. | unknown_parameter | 422 | The call has a parameter the endpoint does not take. The answer lists, in allowed, the parameters it does take. | unauthorized | 401 | No key was sent, or the key is not active. Send your key in Authorization: Bearer or X-API-Key. Your account shows your current key. | upgrade_required | 403 | The endpoint, or what you asked of it, comes with a bigger plan. The answer names the plan in plan, and links pricing. | not_found | 404 | No endpoint is at that address, or no record has that id. Ids look like se_7qk3m2xa; take them from an answer as they came. | rate_limited | 429 | More calls a second than the plan takes. Wait for Retry-After (a second) and go on more slowly. | quota_exceeded | 429 | The plan's calls for the day or the month are used up. It starts again at resets_at. Calls are refused, never billed. | server_error | 500 | Something went wrong on our side. It is logged. Try again in a moment. An empty result is not an error: it is a 200 with an empty `data` and `meta.count` 0, often with a `note` on what to ask instead. ## Pay figures Every figure has a name in one shape: `pay..`, with `.net` at the end for pay after tax. | pay.median.monthly | The middle of a month's pay | pay.mean.yearly | The average of a year's pay | pay.p90.hourly | The hourly pay that 90 per cent are paid less than | pay.mean.monthly.net | The average month's pay after tax | pay.monthly | A month's pay, published without naming its statistic The statistics are median, mean, p10 to p90, minimum (the legal minimum wage), starting and bonus; /v1/glossary explains each. ### Every figure keeps its own currency and period `value` is in the country's own currency, in whole units of money, as the office published it. Its `period` is a year (2025), a quarter (2025-Q2), a half (2025-H1) or a month (2025-06). Pro and Analyst add `value_usd` at the average rate of that period; Prices and money has the rest. ### How /v1/pay finds the series A country publishes many series for one name (by industry, sector, hours, groups). /v1/pay takes the one whose other parts are all totals where the country gives that, then the most recent, then everyone's hours. The same call always finds the same series, and the answer's `series` id lets you follow it over time with /v1/series/{id}/observations. Left out, `series` is pay.median.monthly; when a country does not publish that, the answer gives the nearest figure it does publish and says so in `meta.series`. ### The headline Each country's headline (/v1/countries/{cc}/headline) is its figure for everyone, every occupation, gross: its median where it publishes one, else its mean, and the most recent. ## Occupations Each country publishes pay by occupation in its own classification. Many use ISCO-08, the international standard, or a national version of it that keeps its codes; others have their own (the United States' SOC, Japan's, the UK's). ### Ids, slugs and codes Every occupation has an id (`oc_...`), a slug for addresses (`software-developers`), its classification and its code. /v1/occupations/search?q= finds one by its name or code; any parameter that takes an occupation takes the id or the slug. ### One role across countries An ISCO-08 occupation is the same occupation in every country that publishes by ISCO-08, so /v1/occupations/{id}/pay gives its pay in each of them in one call, with US dollars to compare (Analyst). `isco=` on /v1/pay asks for one by its code. ### The spread Where a country publishes percentiles, /v1/occupations/{id}/distribution gives the 10th, 25th, 50th, 75th and 90th, and the mean, for one period. ## Breakdowns Breakdowns come with Starter and above. Each country publishes its own: /v1/countries/{cc}/breakdowns lists its sexes, age bands, levels of schooling, hours and figures, and is the place to start. | occupation | An id or slug, or `isco=` with an ISCO-08 code | sex | all, female or male | age | An age band as the country publishes it, such as 25-34 | education | A level of schooling as the country publishes it | hours | all, full_time or part_time | area | An area id from /v1/countries/{cc}/areas ### Side by side /v1/pay/by-sex, /v1/pay/by-age and /v1/pay/by-education give a country's pay across one breakdown in one call. ### The gender pay gap /v1/pay/gender-gap (Analyst) is men's pay less women's, in per cent of men's, from figures the country publishes for both: by period for everyone, or by occupation or age band for the latest. A negative gap means women are paid more. ## Prices and money Every figure stays in its own currency. Next to it you can have: | value_usd | In US dollars at the average of that period's official daily rates (Pro and Analyst) | converted | A series in US dollars, euros or at purchasing power parity | real | A series in the prices of its latest period, from the country's own consumer price index ### The rates themselves Consumer prices come from each country's own statistics office. Exchange rates are by month, quarter and year, against the US dollar and the euro. Purchasing power is for private consumption, by year. ### Converting and adjusting an amount /v1/convert takes an amount from one currency to another at a period's rate. /v1/adjust takes an amount in one year's prices to another year's. ## Endpoints ### The API `GET /`. The API's name, its base address and where its documentation and status are. Plan: Free key. Returns: - `name` (string): The API - `base` (string): Base address - `documentation` (string): Documentation - `status` (string): Status page - `endpoints` (integer): Endpoints ### Your usage `GET /v1/usage`. Your plan, the calls made today and this month, your limits and when they reset. Free to call: it never counts. Plan: Free key. Returns: - `plan` (string): free, starter, pro or analyst - `allowance` (integer): Calls in the allowance - `per` (string): day or month - `used` (integer): Calls made in this day or month - `remaining` (integer): Calls left - `resets_at` (date): When the allowance starts again (UTC) - `per_second` (integer): Calls a second - `calls_today` (integer): Calls today - `calls_this_month` (integer): Calls this month - `periods` (string): How far back the figures reach on this plan - `features` (object): What the plan includes ### Status `GET /v1/status`. Whether the API is answering, and how current its figures are. Plan: Free key. Returns: - `state` (string): ok or degraded - `countries` (integer): Countries - `tables` (integer): Tables - `figures` (integer): Figures - `last_release_at` (date): When the latest release reached the API ### Changelog `GET /v1/changelog`. Every change to the API, newest first. v1 only ever gains fields. Plan: Free key. Parameters: - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `date` (date): The day - `change` (string): What changed ### Coverage `GET /v1/coverage`. For each country: its tables, series and figures, the years they reach and the breakdowns it publishes. Plan: Free key. Parameters: - `region` (string): Only one region One of: europe, asia, americas, middle-east, africa, oceania. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `country` (string): Two-letter country code, lower case - `name` (string): The country in English - `region` (string): Europe, Asia, Americas, Middle East, Africa or Oceania - `currency` (string): The currency its figures are in today (ISO 4217) - `tables` (integer): Tables - `series` (integer): Pay series - `figures` (integer): Figures - `first_year` (year): First year - `last_period` (period): Latest period - `breakdowns` (array): occupation, sex, age, education, area, industry: the ones it publishes ### Glossary `GET /v1/glossary`. Every statistic, pay period and word the API uses, in plain words. Plan: Free key. Returns: - `term` (string): The word - `kind` (string): statistic, per, field or value - `means` (string): What it means ### Pay `GET /v1/pay`. The pay figure you ask for: a country, a statistic and period of pay, and any breakdown. The latest period unless you ask for others. Plan: Free key. MCP tool: `get_pay`. Parameters: - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `occupation` (id): An occupation id (oc_...) or its slug, such as software-developers - `isco` (string): An ISCO-08 occupation code (1 to 4 digits), where the country publishes by ISCO - `sex` (string): Sex One of: all, female, male. - `age` (string): An age band as /v1/countries/{cc}/breakdowns lists it, such as 25-34 - `education` (string): A level of schooling as /v1/countries/{cc}/breakdowns lists it - `hours` (string): Full-time, part-time or everyone One of: all, full_time, part_time. - `area` (id): An area (ar_...); the whole country when left out - `period` (period): One period; the latest when left out - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Every country `GET /v1/countries`. Every country with figures, its region, its currency and how much it publishes. Plan: Free key. MCP tool: `list_countries`. Parameters: - `region` (string): Only one region One of: europe, asia, americas, middle-east, africa, oceania. - `sort` (string): The order One of: name, figures, latest. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `country` (string): Two-letter country code, lower case - `name` (string): The country in English - `region` (string): Europe, Asia, Americas, Middle East, Africa or Oceania - `currency` (string): The currency its figures are in today (ISO 4217) - `tables` (integer): Tables - `figures` (integer): Figures - `last_period` (period): Its latest period ### One country `GET /v1/countries/{cc}`. A country: its region, currency, tables, the years its figures reach and the breakdowns it publishes. Plan: Free key. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb Returns: - `country` (string): Two-letter country code, lower case - `name` (string): The country in English - `region` (string): Europe, Asia, Americas, Middle East, Africa or Oceania - `currency` (string): The currency its figures are in today (ISO 4217) - `tables` (integer): Tables - `series` (integer): Pay series - `figures` (integer): Figures - `first_year` (year): First year - `last_period` (period): Latest period - `breakdowns` (array): The breakdowns it publishes ### Headline pay `GET /v1/countries/{cc}/headline`. A country's headline pay figure: everyone, every occupation, the median where it publishes one, else the mean. Plan: Free key. MCP tool: `country_headline`. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### A country's tables `GET /v1/countries/{cc}/tables`. The pay tables a country publishes, each with its series, figures and the periods it covers. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The table (tb_...) - `country` (string): Two-letter country code - `title` (string): What it holds - `series` (integer): Pay series in it - `figures` (integer): Figures in it - `first_period` (period): Its first period - `last_period` (period): Its latest period - `updated_at` (date): When it last changed (UTC) ### A country's occupations `GET /v1/countries/{cc}/occupations`. The occupations a country publishes pay for, with their latest headline figure. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `q` (string): Words in the occupation's name - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The occupation (oc_...) - `slug` (string): Its name for addresses - `name` (string): The occupation as published, in English where the office gives it - `classification` (string): The classification its code belongs to: ISCO-08, SOC, a national one - `code` (string): Its code in that classification - `countries` (integer): How many countries publish pay for it - `series` (integer): How many series carry it - `latest` (object): The latest figure: period, value, currency ### A country's breakdowns `GET /v1/countries/{cc}/breakdowns`. Every value a country publishes pay by: its sexes, age bands, levels of schooling, hours and statistics. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb Returns: - `sex` (array): Sexes - `age` (array): Age bands - `education` (array): Levels of schooling - `hours` (array): Hours - `series` (array): The figures it publishes, as pay.. - `occupations` (integer): Occupations - `areas` (integer): Areas ### Headline history `GET /v1/countries/{cc}/history`. A country's headline pay over every period it has, oldest first. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): The figure in its own currency - `value_usd` (number): In US dollars at that period's rate (Pro and Analyst) - `area` (string): The area, or null for the whole country ### A country's releases `GET /v1/countries/{cc}/releases`. The releases from one country, newest first. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The release (rl_...) - `country` (string): Two-letter country code - `table` (id): The table (tb_...) - `title` (string): What it holds - `period` (period): The latest period it brought - `published_at` (date): When it reached the API (UTC) ### Regions `GET /v1/regions`. The six regions and how many countries each has. Plan: Free key. Returns: - `region` (string): Its name for addresses - `name` (string): The region - `countries` (integer): Countries - `figures` (integer): Figures ### One region `GET /v1/regions/{region}`. A region's countries, each with its headline pay figure. Plan: Starter and above. Parameters: - `region` (string, required): The region One of: europe, asia, americas, middle-east, africa, oceania. Returns: - `country` (string): Two-letter country code, lower case - `name` (string): The country in English - `region` (string): Europe, Asia, Americas, Middle East, Africa or Oceania - `currency` (string): The currency its figures are in today (ISO 4217) - `headline` (object): The headline figure ### Compare a region `GET /v1/regions/{region}/compare`. A region's countries side by side in US dollars, highest first, on one figure. Plan: Pro and above. Parameters: - `region` (string, required): The region One of: europe, asia, americas, middle-east, africa, oceania. - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country - `rank` (integer): Its place ### Find series `GET /v1/series`. Every pay series that matches what you ask for: a country, a statistic, a period of pay and any breakdown. Plan: Starter and above. MCP tool: `search_series`. Parameters: - `country` (country, required): Two-letter country code - `series` (string): pay.., or part of it: pay.median, pay.mean.yearly - `occupation` (id): An occupation id (oc_...) or its slug, such as software-developers - `isco` (string): An ISCO-08 occupation code (1 to 4 digits), where the country publishes by ISCO - `sex` (string): Sex One of: all, female, male. - `age` (string): An age band as /v1/countries/{cc}/breakdowns lists it, such as 25-34 - `education` (string): A level of schooling as /v1/countries/{cc}/breakdowns lists it - `hours` (string): Full-time, part-time or everyone One of: all, full_time, part_time. - `table` (id): Only one table (tb_...) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The series (se_...) - `name` (string): pay..[.net] - `statistic` (string): median, mean, p10 to p90, minimum, starting, bonus or reported - `per` (string): hour, day, week, month or year - `net` (boolean): True for pay after tax - `country` (string): Two-letter country code - `currency` (string): ISO 4217 currency - `occupation` (id): The occupation (oc_...), or null - `sex` (string): all, female or male - `age` (string): Age band, or null - `education` (string): Level of schooling, or null - `hours` (string): all, full_time or part_time - `table` (id): The table it belongs to (tb_...) - `first_period` (period): Its first period - `last_period` (period): Its latest period - `areas` (integer): How many areas it is published for ### One series `GET /v1/series/{id}`. A series: what it measures, who it covers, its table and the periods it has. Plan: Free key. Parameters: - `id` (id, required): The id (se_...) Returns: - `id` (id): The series (se_...) - `name` (string): pay..[.net] - `statistic` (string): median, mean, p10 to p90, minimum, starting, bonus or reported - `per` (string): hour, day, week, month or year - `net` (boolean): True for pay after tax - `country` (string): Two-letter country code - `currency` (string): ISO 4217 currency - `occupation` (id): The occupation (oc_...), or null - `sex` (string): all, female or male - `age` (string): Age band, or null - `education` (string): Level of schooling, or null - `hours` (string): all, full_time or part_time - `table` (id): The table it belongs to (tb_...) - `first_period` (period): Its first period - `last_period` (period): Its latest period - `areas` (integer): How many areas it is published for ### A series over time `GET /v1/series/{id}/observations`. Every figure of a series, oldest first, for the whole country or one area. Plan: Starter and above. MCP tool: `series_history`. Parameters: - `id` (id, required): The id (se_...) - `area` (id): An area (ar_...); the whole country when left out - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): The figure in its own currency - `value_usd` (number): In US dollars at that period's rate (Pro and Analyst) - `area` (string): The area, or null for the whole country ### A series' latest figure `GET /v1/series/{id}/latest`. The latest figure of a series for the whole country. Plan: Free key. Parameters: - `id` (id, required): The id (se_...) Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Change over time `GET /v1/series/{id}/change`. How a series moved: each period against the one a year before, in money and per cent. Plan: Starter and above. Parameters: - `id` (id, required): The id (se_...) - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): The figure - `year_before` (number): The figure a year before - `change` (number): The difference - `change_pct` (number): The difference in per cent ### In today's prices `GET /v1/series/{id}/real`. A series in the prices of the latest period, from the country's own consumer price index, so the years compare. Plan: Starter and above. Parameters: - `id` (id, required): The id (se_...) - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): The figure as published - `value_real` (number): In the prices of price_period - `price_period` (period): The prices it is given in ### In another currency `GET /v1/series/{id}/converted`. A series in US dollars or euros at each period's rate, or at purchasing power parity. Plan: Pro and above. Parameters: - `id` (id, required): The id (se_...) - `to` (string): What to convert to One of: usd, eur, ppp. - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): As published - `converted` (number): Converted - `to` (string): usd, eur or ppp (international dollars) - `rate` (number): Units of the currency to one ### A series by area `GET /v1/series/{id}/areas`. A series' latest figure in every area it is published for. Plan: Starter and above. Parameters: - `id` (id, required): The id (se_...) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `area` (id): The area (ar_...) - `name` (string): The area - `national` (boolean): The whole country - `period` (period): The period - `value` (number): The figure ### Every table `GET /v1/tables`. Every pay table, newest changes first. Plan: Starter and above. Parameters: - `country` (country): Only one country - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The table (tb_...) - `country` (string): Two-letter country code - `title` (string): What it holds - `series` (integer): Pay series in it - `figures` (integer): Figures in it - `first_period` (period): Its first period - `last_period` (period): Its latest period - `updated_at` (date): When it last changed (UTC) ### One table `GET /v1/tables/{id}`. A table: what it holds, its periods and what it is broken down by. Plan: Starter and above. Parameters: - `id` (id, required): The id (tb_...) Returns: - `id` (id): The table (tb_...) - `country` (string): Two-letter country code - `title` (string): What it holds - `series` (integer): Pay series in it - `figures` (integer): Figures in it - `first_period` (period): Its first period - `last_period` (period): Its latest period - `updated_at` (date): When it last changed (UTC) - `breakdowns` (array): What it is broken down by ### A table's series `GET /v1/tables/{id}/series`. The pay series in a table. Plan: Starter and above. Parameters: - `id` (id, required): The id (tb_...) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The series (se_...) - `name` (string): pay..[.net] - `statistic` (string): median, mean, p10 to p90, minimum, starting, bonus or reported - `per` (string): hour, day, week, month or year - `net` (boolean): True for pay after tax - `country` (string): Two-letter country code - `currency` (string): ISO 4217 currency - `occupation` (id): The occupation (oc_...), or null - `sex` (string): all, female or male - `age` (string): Age band, or null - `education` (string): Level of schooling, or null - `hours` (string): all, full_time or part_time - `table` (id): The table it belongs to (tb_...) - `first_period` (period): Its first period - `last_period` (period): Its latest period - `areas` (integer): How many areas it is published for ### A table's figures `GET /v1/tables/{id}/observations`. Every figure in a table for one period, the latest when left out, each with its series. Plan: Starter and above. Parameters: - `id` (id, required): The id (tb_...) - `period` (period): One period; the latest when left out - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Every occupation `GET /v1/occupations`. Every occupation with pay, in every classification, the most widely published first. Plan: Free key. Parameters: - `country` (country): Only those one country publishes - `classification` (string): Only one classification, such as ISCO-08 - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The occupation (oc_...) - `slug` (string): Its name for addresses - `name` (string): The occupation as published, in English where the office gives it - `classification` (string): The classification its code belongs to: ISCO-08, SOC, a national one - `code` (string): Its code in that classification - `countries` (integer): How many countries publish pay for it - `series` (integer): How many series carry it ### Find an occupation `GET /v1/occupations/search`. Occupations whose name or code matches what you type. Plan: Free key. MCP tool: `find_occupation`. Parameters: - `q` (string, required): Words or a code, such as nurse, software or 2221 - `country` (country): Only those one country publishes - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The occupation (oc_...) - `slug` (string): Its name for addresses - `name` (string): The occupation as published, in English where the office gives it - `classification` (string): The classification its code belongs to: ISCO-08, SOC, a national one - `code` (string): Its code in that classification - `countries` (integer): How many countries publish pay for it - `series` (integer): How many series carry it ### One occupation `GET /v1/occupations/{id}`. An occupation: its classification and code, and the countries that publish pay for it. Plan: Free key. Parameters: - `id` (id, required): The id (oc_...) Returns: - `id` (id): The occupation (oc_...) - `slug` (string): Its name for addresses - `name` (string): The occupation as published, in English where the office gives it - `classification` (string): The classification its code belongs to: ISCO-08, SOC, a national one - `code` (string): Its code in that classification - `countries` (integer): How many countries publish pay for it - `series` (integer): How many series carry it - `in` (array): The countries that publish it ### One role across countries `GET /v1/occupations/{id}/pay`. An occupation's latest pay in every country that publishes it, in one call, with US dollars to compare. Plan: Analyst and above. MCP tool: `occupation_across_countries`. Parameters: - `id` (id, required): The id (oc_...) - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Where it is published `GET /v1/occupations/{id}/countries`. The countries that publish an occupation, with the series and periods each has. Plan: Analyst and above. Parameters: - `id` (id, required): The id (oc_...) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `country` (string): Two-letter country code, lower case - `name` (string): The country in English - `region` (string): Europe, Asia, Americas, Middle East, Africa or Oceania - `currency` (string): The currency its figures are in today (ISO 4217) - `series` (integer): Series - `first_period` (period): First period - `last_period` (period): Latest period ### An occupation over time `GET /v1/occupations/{id}/history`. An occupation's pay in one country over every period it has. Plan: Starter and above. Parameters: - `id` (id, required): The id (oc_...) - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `value` (number): The figure in its own currency - `value_usd` (number): In US dollars at that period's rate (Pro and Analyst) - `area` (string): The area, or null for the whole country ### The spread of pay `GET /v1/occupations/{id}/distribution`. An occupation's pay from the 10th to the 90th percentile, where the country publishes them. Plan: Starter and above. MCP tool: `occupation_distribution`. Parameters: - `id` (id, required): The id (oc_...) - `country` (country, required): Two-letter country code - `per` (string): Pay per One of: hour, week, month, year. Returns: - `period` (period): The period - `currency` (string): Currency - `per` (string): Pay per - `p10` (number): 10th percentile - `p25` (number): 25th percentile - `median` (number): Median - `p75` (number): 75th percentile - `p90` (number): 90th percentile - `mean` (number): Mean ### Compare a role `GET /v1/occupations/{id}/compare`. An occupation in the countries you name, side by side in US dollars. Plan: Analyst and above. Parameters: - `id` (id, required): The id (oc_...) - `countries` (countries, required): Two to ten country codes, comma separated: gb,fi,jp - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### A role by area `GET /v1/occupations/{id}/areas`. An occupation's latest pay in each area of one country. Plan: Starter and above. Parameters: - `id` (id, required): The id (oc_...) - `country` (country, required): Two-letter country code - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `area` (id): The area (ar_...) - `name` (string): The area - `period` (period): Period - `value` (number): The figure - `currency` (string): Currency - `name_of_figure` (string): pay.. ### Every headline `GET /v1/pay/headline`. Every country's headline pay figure in one call. Plan: Free key. Parameters: - `region` (string): Only one region One of: europe, asia, americas, middle-east, africa, oceania. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Pay by sex `GET /v1/pay/by-sex`. Women's and men's pay in a country, side by side, for everyone or one occupation. Plan: Starter and above. Parameters: - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `occupation` (id): An occupation (oc_...) or its slug - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `female` (number): Women - `male` (number): Men - `all` (number): Everyone - `currency` (string): Currency - `occupation` (id): The occupation, or null ### Pay by age `GET /v1/pay/by-age`. Pay in each age band of a country, youngest first. Plan: Starter and above. Parameters: - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `sex` (string): Sex One of: all, female, male. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `age` (string): The age band - `period` (period): The period - `value` (number): The figure - `currency` (string): Currency - `series` (id): The series ### Pay by schooling `GET /v1/pay/by-education`. Pay at each level of schooling in a country. Plan: Starter and above. Parameters: - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `education` (string): The level - `period` (period): The period - `value` (number): The figure - `currency` (string): Currency - `series` (id): The series ### The gender pay gap `GET /v1/pay/gender-gap`. How much less women are paid than men, in per cent of men's pay, by period, for everyone or each occupation and age band. Plan: Analyst and above. MCP tool: `gender_gap`. Parameters: - `country` (country, required): Two-letter country code - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... - `by` (string): Everyone, or by occupation or age band One of: all, occupation, age. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `female` (number): Women - `male` (number): Men - `gap_pct` (number): Men's pay less women's, in per cent of men's - `occupation` (id): The occupation, when by occupation - `age` (string): The age band, when by age ### A country's areas `GET /v1/countries/{cc}/areas`. The areas a country publishes pay for: its regions, states, counties or cities. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The area (ar_...) - `country` (string): Two-letter country code - `name` (string): The area as published - `national` (boolean): True for the whole country - `series` (integer): Pay series published for it ### One area `GET /v1/areas/{id}`. An area: its country and how many pay series it has. Plan: Starter and above. Parameters: - `id` (id, required): The id (ar_...) Returns: - `id` (id): The area (ar_...) - `country` (string): Two-letter country code - `name` (string): The area as published - `national` (boolean): True for the whole country - `series` (integer): Pay series published for it ### Occupations in an area `GET /v1/areas/{id}/occupations`. The latest pay of each occupation published for an area. Plan: Starter and above. Parameters: - `id` (id, required): The id (ar_...) - `q` (string): Words in the occupation's name - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `occupation` (id): The occupation - `name` (string): Its name - `period` (period): Period - `value` (number): The figure - `currency` (string): Currency - `name_of_figure` (string): pay.. ### Industries `GET /v1/industries`. The industries pay is published by, where a country publishes pay by industry. Plan: Starter and above. Parameters: - `country` (country): Only one country - `q` (string): Words in the industry's name - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The industry (in_...) - `country` (string): Two-letter country code - `code` (string): Its code in the country's industry classification - `name` (string): The industry ### One industry `GET /v1/industries/{id}`. An industry, with its pay for every occupation together. Plan: Starter and above. Parameters: - `id` (id, required): The id (in_...) Returns: - `id` (id): The industry (in_...) - `country` (string): Two-letter country code - `code` (string): Its code in the country's industry classification - `name` (string): The industry - `employment` (integer): People employed - `mean` (number): Mean yearly pay - `median` (number): Median yearly pay - `period` (period): The period - `currency` (string): Currency ### Occupations in an industry `GET /v1/industries/{id}/occupations`. Pay for each occupation in an industry, the best paid first. Plan: Starter and above. Parameters: - `id` (id, required): The id (in_...) - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `occupation` (id): The occupation - `name` (string): Its name - `employment` (integer): People employed - `period` (period): Period - `currency` (string): Currency - `p10` (number): 10th percentile - `p25` (number): 25th percentile - `median` (number): Median - `p75` (number): 75th percentile - `p90` (number): 90th percentile - `mean` (number): Mean ### Compare countries `GET /v1/compare/countries`. The countries you name side by side on one figure, in their own currency and in US dollars. Plan: Pro and above. MCP tool: `compare_countries`. Parameters: - `countries` (countries, required): Two to ten country codes, comma separated: gb,fi,jp - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Compare occupations `GET /v1/compare/occupations`. The occupations you name side by side in one country. Plan: Starter and above. Parameters: - `country` (country, required): Two-letter country code - `occupations` (ids, required): Two to ten occupations (oc_...), comma separated - `series` (string): The figure wanted, as pay..: pay.median.monthly, pay.mean.yearly, pay.median.hourly, pay.p90.yearly... Returns: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country ### Compare two periods `GET /v1/compare/periods`. A series in two periods, with the change between them as published and in today's prices. Plan: Starter and above. Parameters: - `series` (id, required): The series (se_...) - `from` (period, required): The earlier period - `to` (period): The later period; the latest when left out Returns: - `from` (object): The earlier figure - `to` (object): The later figure - `change` (number): The difference - `change_pct` (number): In per cent - `real_change_pct` (number): In per cent, after prices ### Rank countries `GET /v1/rank`. Every country ranked on its headline pay in US dollars, a year's pay, highest first. Plan: Pro and above. MCP tool: `rank_countries`. Parameters: - `region` (string): Only one region One of: europe, asia, americas, middle-east, africa, oceania. - `by` (string): In US dollars or at purchasing power One of: usd, ppp. - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `series` (id): The series (se_...) - `name` (string): What the figure is, as pay.., for example pay.median.monthly - `country` (string): Two-letter country code - `period` (period): The period the figure covers: 2025, 2025-Q2 or 2025-06 - `value` (number): The figure in its own currency, in whole units of money - `currency` (string): ISO 4217 currency - `value_usd` (number): The figure in US dollars at that period's rate (Pro and Analyst; null on other plans) - `occupation` (id): The occupation (oc_...), or null for all occupations - `sex` (string): all, female or male - `age` (string): The age band, or null for all ages - `education` (string): The level of schooling, or null for all levels - `hours` (string): all, full_time or part_time - `area` (string): The area, or null for the whole country - `rank` (integer): Its place - `yearly_usd` (number): A year's pay in US dollars (or international dollars with by=ppp) ### Consumer prices `GET /v1/context/prices/{cc}`. A country's consumer price index from its own statistics office, by period. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `index` (number): The index - `base` (string): Its base, such as 2015=100 ### Exchange rates `GET /v1/context/exchange/{currency}`. A currency against the US dollar and the euro, by month, quarter and year: the average of each period's official daily rates. Plan: Starter and above. Parameters: - `currency` (string, required): ISO 4217 currency, such as jpy - `freq` (string): By month, quarter or year One of: month, quarter, year. - `from` (period): The first period wanted (2019, 2019-Q1 or 2019-01) - `to` (period): The last period wanted - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `period` (period): The period - `per_usd` (number): Units to one US dollar - `per_eur` (number): Units to one euro ### Purchasing power `GET /v1/context/ppp/{cc}`. A country's purchasing power parity for private consumption: units of its currency to one international dollar, by year. Plan: Starter and above. Parameters: - `cc` (country, required): Two-letter country code, such as jp or gb - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `year` (year): The year - `per_intl_dollar` (number): Units of its currency to one international dollar ### Currencies `GET /v1/currencies`. Every currency the figures are in, with the latest rate to the US dollar. Plan: Free key. Parameters: - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `currency` (string): ISO 4217 - `per_usd` (number): Units to one US dollar - `period` (period): The rate's period - `countries` (array): Countries with figures in it ### Convert money `GET /v1/convert`. An amount from one currency to another at a period's average rate. Plan: Pro and above. MCP tool: `convert_money`. Parameters: - `amount` (number, required): The amount - `from` (string, required): Its currency (ISO 4217) - `to` (string, required): The currency wanted - `period` (period): The period's rate; the latest when left out Returns: - `amount` (number): The amount - `from` (string): From - `to` (string): To - `converted` (number): The result - `rate` (number): Units of to for one of from - `period` (period): The rate used ### Adjust for prices `GET /v1/adjust`. An amount of a country's money in one year, in the prices of another year, from its consumer price index. Plan: Starter and above. MCP tool: `adjust_for_prices`. Parameters: - `country` (country, required): Two-letter country code - `amount` (number, required): The amount - `from` (period, required): The year (or month) of the amount - `to` (period): The prices wanted; the latest when left out Returns: - `amount` (number): The amount - `from` (period): Its period - `to` (period): The prices given - `adjusted` (number): The result - `factor` (number): Prices at to over prices at from ### Releases `GET /v1/releases`. New and changed pay tables as they reach the API, newest first. Plan: Free key. MCP tool: `latest_releases`. Parameters: - `country` (country): Only one country - `since` (date): Only since a day, YYYY-MM-DD - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The release (rl_...) - `country` (string): Two-letter country code - `table` (id): The table (tb_...) - `title` (string): What it holds - `period` (period): The latest period it brought - `published_at` (date): When it reached the API (UTC) ### The latest from each country `GET /v1/releases/latest`. Each country's latest release. Plan: Free key. Parameters: - `page` (integer): The page, from 1 - `per_page` (integer): Items a page, at most 200 - `cursor` (string): From next_cursor in the last answer; page wins when both are sent Returns a list, each item: - `id` (id): The release (rl_...) - `country` (string): Two-letter country code - `table` (id): The table (tb_...) - `title` (string): What it holds - `period` (period): The latest period it brought - `published_at` (date): When it reached the API (UTC) ### One release `GET /v1/releases/{id}`. A release: its table, the periods it brought and its headline figures. Plan: Free key. Parameters: - `id` (id, required): The id (rl_...) Returns: - `id` (id): The release (rl_...) - `country` (string): Two-letter country code - `table` (id): The table (tb_...) - `title` (string): What it holds - `period` (period): The latest period it brought - `published_at` (date): When it reached the API (UTC) - `first_period` (period): The table's first period - `series` (integer): Series - `figures` (integer): Figures ## MCP server https://salarydataapi.com/mcp. Tools: - `get_pay`: The pay figure you ask for: a country, a statistic and period of pay, and any breakdown. The latest period unless you ask for others. (calls `/v1/pay`) - `list_countries`: Every country with figures, its region, its currency and how much it publishes. (calls `/v1/countries`) - `country_headline`: A country's headline pay figure: everyone, every occupation, the median where it publishes one, else the mean. (calls `/v1/countries/{cc}/headline`) - `search_series`: Every pay series that matches what you ask for: a country, a statistic, a period of pay and any breakdown. (calls `/v1/series`) - `series_history`: Every figure of a series, oldest first, for the whole country or one area. (calls `/v1/series/{id}/observations`) - `find_occupation`: Occupations whose name or code matches what you type. (calls `/v1/occupations/search`) - `occupation_across_countries`: An occupation's latest pay in every country that publishes it, in one call, with US dollars to compare. (calls `/v1/occupations/{id}/pay`) - `occupation_distribution`: An occupation's pay from the 10th to the 90th percentile, where the country publishes them. (calls `/v1/occupations/{id}/distribution`) - `gender_gap`: How much less women are paid than men, in per cent of men's pay, by period, for everyone or each occupation and age band. (calls `/v1/pay/gender-gap`) - `compare_countries`: The countries you name side by side on one figure, in their own currency and in US dollars. (calls `/v1/compare/countries`) - `rank_countries`: Every country ranked on its headline pay in US dollars, a year's pay, highest first. (calls `/v1/rank`) - `convert_money`: An amount from one currency to another at a period's average rate. (calls `/v1/convert`) - `adjust_for_prices`: An amount of a country's money in one year, in the prices of another year, from its consumer price index. (calls `/v1/adjust`) - `latest_releases`: New and changed pay tables as they reach the API, newest first. (calls `/v1/releases`) ## Errors - `bad_request` (400): A value is not what the parameter takes, a required one is missing, or a key was sent in the address. Read the message: it names the parameter and what it should be. - `unknown_parameter` (422): The call has a parameter the endpoint does not take. The answer lists, in allowed, the parameters it does take. - `unauthorized` (401): No key was sent, or the key is not active. Send your key in Authorization: Bearer or X-API-Key. Your account shows your current key. - `upgrade_required` (403): The endpoint, or what you asked of it, comes with a bigger plan. The answer names the plan in plan, and links pricing. - `not_found` (404): No endpoint is at that address, or no record has that id. Ids look like se_7qk3m2xa; take them from an answer as they came. - `rate_limited` (429): More calls a second than the plan takes. Wait for Retry-After (a second) and go on more slowly. - `quota_exceeded` (429): The plan's calls for the day or the month are used up. It starts again at resets_at. Calls are refused, never billed. - `server_error` (500): Something went wrong on our side. It is logged. Try again in a moment.