Developer Platform · v1 · Stable

The WorthOf API

A simple, well-cached REST API for global net salary calculations, progressive tax brackets, cost-of-living indexes, and FX rates. JSON in, JSON out.

Explore endpoints →Get an API key →

curl -H "X-API-Key: wio_live_…" \
  https://api.worthof.io/v1/cities/lisbon/col

Authentication

Every request requires an API key sent in the X-API-Key header. Keys are issued from the pricing page — the free tier gives you 100 calls/day with no card required.

X-API-Key: wio_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6

Treat keys like passwords — never embed them in client-side JavaScript. Proxy calls through your backend.

Rate limits

Tier	Daily limit	Attribution	Price
Free	100 req / day	Attribution required	€0
Pro	10,000 req / day	No attribution	€29 / mo
Enterprise	100,000 req / day	Custom + SLA	€199 / mo

When a limit is exceeded the API responds with HTTP 429 and a Retry-After header indicating seconds until reset.

Endpoints

Base URL: https://api.worthof.io/v1

GET/citiesList cities

Returns all cities with the latest cost-of-living headline metrics.

Name	Type	Required	Description
region	string	no	Filter by region (europe, asia, americas, africa, oceania).
limit	integer	no	Page size (default 50, max 250).
offset	integer	no	Pagination offset (default 0).

curl

curl "https://api.worthof.io/v1/cities" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/cities", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/cities",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "cities": [
    {
      "slug": "lisbon",
      "name": "Lisbon",
      "country": "Portugal",
      "iso2": "PT",
      "region": "europe",
      "col_index": 58.4,
      "rent_1br_centre": 1450
    }
  ],
  "total": 240,
  "limit": 50,
  "offset": 0
}

GET/cities/{slug}Get city

Full city record including the most recent cost-of-living snapshot.

curl

curl "https://api.worthof.io/v1/cities/{slug}" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/cities/{slug}", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/cities/{slug}",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "city": {
    "slug": "lisbon",
    "name": "Lisbon",
    "country": { "slug": "portugal", "name": "Portugal", "iso2": "PT" },
    "lat": 38.722, "lng": -9.139,
    "col_data": { "col_index": 58.4, "rent_1br_centre": 1450, "period": "2026-01-01" }
  }
}

GET/cities/{slug}/colCity cost-of-living breakdown

Detailed cost-of-living basket for a single city.

curl

curl "https://api.worthof.io/v1/cities/{slug}/col" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/cities/{slug}/col", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/cities/{slug}/col",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "city": { "slug": "lisbon", "name": "Lisbon" },
  "col_index": 58.4,
  "rent_1br_centre": 1450,
  "rent_1br_outside": 1050,
  "groceries_monthly": 320,
  "restaurant_meal": 14,
  "utilities_monthly": 110,
  "transport_monthly": 40
}

GET/countriesList countries

All covered countries with tax system metadata.

curl

curl "https://api.worthof.io/v1/countries" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/countries", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/countries",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "countries": [
    {
      "slug": "portugal",
      "name": "Portugal",
      "currency_code": "EUR",
      "ss_rate": 0.11,
      "has_14_payments": true
    }
  ]
}

GET/countries/{slug}/tax-bracketsCountry tax brackets

Progressive income tax brackets for a country.

Name	Type	Required	Description
year	integer	no	Tax year (default 2026).
filer_type	string	no	single \| married (default single).

curl

curl "https://api.worthof.io/v1/countries/{slug}/tax-brackets" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/countries/{slug}/tax-brackets", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/countries/{slug}/tax-brackets",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "country": { "slug": "portugal", "name": "Portugal", "currency": "EUR" },
  "tax_year": 2026,
  "brackets": [
    { "order": 1, "min": 0, "max": 7703, "rate": 0.1325 },
    { "order": 2, "min": 7703, "max": 11623, "rate": 0.18 }
  ]
}

POST/calculate/net-salaryNet salary calculator

The flagship endpoint. Apply social security + progressive brackets to a gross salary and return a full breakdown with the bracket-by-bracket waterfall.

curl

curl -X POST "https://api.worthof.io/v1/calculate/net-salary" \
  -H "X-API-Key: $WORTHOF_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gross": 50000, "country_slug": "portugal", "filer_type": "single" }'

JavaScript

const res = await fetch("https://api.worthof.io/v1/calculate/net-salary", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.WORTHOF_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ "gross": 50000, "country_slug": "portugal", "filer_type": "single" }),
});
const data = await res.json();

Python

import os, requests
r = requests.post(
    "https://api.worthof.io/v1/calculate/net-salary",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
    json={ "gross": 50000, "country_slug": "portugal", "filer_type": "single" },
)
data = r.json()

Response

{
  "input": { "gross": 50000, "country_slug": "portugal" },
  "country": { "slug": "portugal", "name": "Portugal", "currency": "EUR" },
  "result": {
    "gross": 50000,
    "socialSec": 5500,
    "incomeTax": { "total": 11240, "brackets": [ ... ] },
    "netAnnual": 33260,
    "netMonthly": 2375.71,
    "paymentsPerYear": 14,
    "effectiveRate": 0.3348
  }
}

GET/compare/citiesCompare two cities

Side-by-side comparison with computed absolute and percentage differences.

Name	Type	Required	Description
city_a	string	yes	Slug of the first city.
city_b	string	yes	Slug of the second city.

curl

curl "https://api.worthof.io/v1/compare/cities" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/compare/cities", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/compare/cities",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "city_a": { "slug": "lisbon", ... },
  "city_b": { "slug": "berlin", ... },
  "differences": {
    "col_index": { "absolute": -12.3, "percent": -0.174 },
    "rent_1br_centre": { "absolute": -650, "percent": -0.31 }
  }
}

GET/fx-ratesExchange rates

Latest exchange rates from the European Central Bank, with optional base and date.

Name	Type	Required	Description
base	string	no	Base currency (default EUR).
date	string	no	ISO date or 'latest' (default latest).

curl

curl "https://api.worthof.io/v1/fx-rates" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/fx-rates", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/fx-rates",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "base": "EUR",
  "date": "2026-01-31",
  "source": "ECB",
  "rates": { "USD": 1.08, "GBP": 0.84, "JPY": 162.4 }
}

GET/col-indexFull cost-of-living ranking

Every tracked city ranked by cost-of-living index (NYC = 100 baseline).

Name	Type	Required	Description
region	string	no	Filter by region.
limit	integer	no	Max rows (default 250, max 500).

curl

curl "https://api.worthof.io/v1/col-index" -H "X-API-Key: $WORTHOF_KEY"

JavaScript

const res = await fetch("https://api.worthof.io/v1/col-index", {
  headers: { "X-API-Key": process.env.WORTHOF_KEY },
});
const data = await res.json();

Python

import os, requests
r = requests.get(
    "https://api.worthof.io/v1/col-index",
    headers={"X-API-Key": os.environ["WORTHOF_KEY"]},
)
data = r.json()

Response

{
  "total": 240,
  "ranking": [
    { "slug": "zurich", "name": "Zurich", "country": "Switzerland", "col_index": 124.1 }
  ]
}

SDKs

Official SDKs are coming soon (Node, Python, Go). Meanwhile, use the REST API directly — any HTTP client works. We'll publish typed clients before GA.

What people build

Salary negotiation tools

Show candidates exactly what an offer is worth net, in any country.

Relocation calculators

Embed live net-salary + cost-of-living deltas inside HR onboarding flows.

Financial planning apps

Power retirement-abroad and FIRE scenarios with authoritative tax + COL data.

Real-estate widgets

Augment listings with live cost-of-living context — groceries, transport, utilities.

Pricing

Free tier is generous enough for prototyping and personal projects. Pro removes attribution and unlocks the full daily volume.

View plans →

Terms of use

Free-tier responses must visibly credit "Data: WorthOf" near the surfaced numbers.
Data is provided under CC-BY-4.0 for the public datasets and a permissive commercial license for paid tiers.
No reselling of raw API responses as a competing dataset product.
Cache responses where possible; do not abuse the rate limit.
Numbers are best-effort estimates from public sources (ECB, Numbeo, national tax authorities). Do not use as legal or financial advice.