Skip to content
calcbloc
API V1.2.0 / 37 COUNTRIES / FREE KEYS

The CalcBloc API

Take-home pay, employer cost and the official tax tables behind every CalcBloc calculator, as JSON or CSV. Free to use with a visible link back to calcbloc.com.

Get a free keyOpenAPI 3.1 file
Start here

Quick start

  1. Get a free key (instant, no email needed).
  2. Send it in the X-API-Key header. Keys in the URL (?key=) are refused, because URLs end up in logs and browser history.
  3. Show "Data by CalcBloc" with a link to calcbloc.com wherever you display the figures.
Reference

Endpoints

  • GET /api/v1/countries

    Supported countries, regions, years and parameters

    Lists every country with its tax year, the regions and parameters each endpoint accepts, and links to the matching calculator and tax-table pages.

    Key optional

  • GET /api/v1/net-salary

    Take-home pay for a salary

    Runs the country's take-home pay engine (the same code and official data as the calculator on calcbloc.com) and returns net pay, taxes and contributions. Per-country parameters are whitelisted; see /api/v1/countries.

    Needs a key

  • GET /api/v1/employer-cost

    Total cost of employing someone

    Runs the country's employer-cost engine: salary plus employer social security, payroll taxes, pension and other on-costs, as on the calcbloc.com employer cost calculators.

    Needs a key

  • GET /api/v1/compare

    Same salary, two countries

    Converts the salary at the European Central Bank reference rate and runs each country's take-home engine, as on calcbloc.com/compare/salary.

    Needs a key

  • GET /api/v1/tax-tables/{country}/{year}

    Official tax tables for a country and tax year

    Every income tax band, threshold, employee contribution and employer rate in the dataset, with effective dates and the official source of each figure. Add region= for a US state, Canadian province or territory, or Scotland or Wales.

    Key optional

  • GET /api/health

    Service status for uptime checks.

Every parameter, its allowed values and its default for each country is listed by /api/v1/countries and in the OpenAPI file. Unknown parameters are rejected with a 400 so typos never pass silently; out-of-range numbers are clamped and reported in warnings.

Coverage

Countries and parameters

Countrycountry=Tax yearNet salary paramsEmployer cost paramsTax tables
IcelandTax tables onlyiceland2026Not available yetNot available yetNational
MaltaTax tables onlymalta2026Not available yetNot available yetNational
LithuaniaTax tables onlylithuania2026Not available yetNot available yetNational
BulgariaTax tables onlybulgaria2026Not available yetNot available yetNational
CyprusTax tables onlycyprus2026Not available yetNot available yetNational
CroatiaTax tables onlycroatia2026Not available yetNot available yetNational + 21 regions
LatviaTax tables onlylatvia2026Not available yetNot available yetNational
GreeceTax tables onlygreece2026Not available yetNot available yetNational
EstoniaTax tables onlyestonia2026Not available yetNot available yetNational
SlovakiaTax tables onlyslovakia2026Not available yetNot available yetNational
RomaniaTax tables onlyromania2026Not available yetNot available yetNational
NorwayTax tables onlynorway2026Not available yetNot available yetNational
CzechiaTax tables onlyczechia2026Not available yetNot available yetNational
LuxembourgTax tables onlyluxembourg2026Not available yetNot available yetNational
PolandTax tables onlypoland2026Not available yetNot available yetNational
HungaryTax tables onlyhungary2026Not available yetNot available yetNational
FinlandTax tables onlyfinland2026Not available yetNot available yetNational + 19 regions
SloveniaTax tables onlyslovenia2026Not available yetNot available yetNational
AustriaTax tables onlyaustria2026Not available yetNot available yetNational
SwedenTax tables onlysweden2026Not available yetNot available yetNational + 21 regions
SwitzerlandTax tables onlyswitzerland2026Not available yetNot available yetNational + 26 regions
DenmarkTax tables onlydenmark2026Not available yetNot available yetNational + 5 regions
PortugalTax tables onlyportugal2026Not available yetNot available yetNational + 2 regions
United Arab EmiratesTax tables onlyuae2026Not available yetNot available yetNational
ItalyTax tables onlyitaly2026Not available yetNot available yetNational + 21 regions
Singaporesingapore2026salary, bonus, status, agesalary, bonus, status, ageNational
Francefrance2026salary, cadre, childrenNot available yetNational
Netherlandsnetherlands2026salary, holiday_allowance, pension_pct, expat_ruling, under_30_masterssalary, holiday_allowance, contract, size, whk_pctNational
Spainspain2026salary, region, payments, contract, under_one_year, situation, children, children_under_3, agesalary, region, contract, payments, atep_pctNational + 21 regions
Germanygermany2026salary, region, tax_class, church, children, over_23, health_add_on_pctsalary, region, health_add_on_pct, small_employer, u1_pct, u2_pctNational
United Statesus2026salary, region, filing_status, frequency, multiple_jobs, children, other_dependents, retirement_pctsalary, region, health_per_month, retirement_match_pct, other_benefits, paid_days_off, overhead_pctNational + 51 regions
United Kingdomuk2026-27salary, region, frequency, pension_pct, pension_method, student_loan, postgraduate_loan, over_state_pension_agesalary, ni_category, pension_mode, pension_pct, employment_allowance, apprenticeship_levy, other_costsNational + 2 regions
Australiaaustralia2026-27salary, super_mode, frequency, residency, tax_free_threshold, help_debt, salary_sacrifice, private_hospital_coversalary, region, super_mode, total_wages, workers_comp_pct, other_costsNational
New Zealandnew-zealand2026-27salary, frequency, tax_code, student_loan, kiwisaver_ratesalary, kiwisaver_member, employer_rate, acc_work_levy_rate, other_costsNational
Canadacanada2026salary, region, frequency, rrsp, dependantssalary, region, total_payroll, wcb_rate, wcb_max, other_costsNational + 13 regions
Irelandireland2026salary, status, spouse_income, pension_pct, age_band, medical_cardsalary, employer_pension_pct, prsi_class, other_costsNational
Indiaindia2026-27salary, region, regime, age, basic_pct, pf_mode, gratuity_in_ctcsalary, region, basic_pct, pf_mode, wage_rule, gratuity, bonus_pct, other_costsNational

Money is in the country's currency, per year unless a field name says otherwise; rates are decimals (0.2 = 20%); percent inputs such as pension_pct=5 mean 5%. India's net salary takes annual CTC.

The one rule

Attribution

Free use requires a visible link to calcbloc.com wherever the figures are shown: on the page, in the app screen or next to the chart (for tax-table data, the CC BY credit below does the same job). Every response carries an attribution block with the text and the calcbloc.com page the figures belong to. Full terms of use.

Tax-table data licence

The tax-table data (/api/v1/tax-tables responses and the CSV and JSON downloads) is © 2026 itmarkerz technologies and licensed under Creative Commons Attribution 4.0 International (CC BY 4.0): reuse and adapt it, commercially too, with the credit “Data by CalcBloc (calcbloc.com/data)” and a link. The licence covers CalcBloc's compilation of official figures; the rates themselves are set by governments. Calculation results (net salary, employer cost, compare) stay under the API terms.

Fair use

Limits

AccessPer dayPer minuteEndpoints
No key (per IP address)505All
Free key5,00060All
CommercialHigher volumes or no-attribution use: contact us.

Days reset at midnight UTC. Each response says where you stand in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over a limit you get a 429 with a Retry-After header in seconds. Responses are cacheable for a day (Cache-Control: public, s-maxage=86400, max-age=3600): cache them on your side and you will rarely get near the limits.

When it fails

Errors

Errors are JSON: {"error":{"code","message","docs"}}, plus the attribution block.

  • 400unknown_parameter A query parameter the endpoint does not accept for that country.
  • 400invalid_parameter A value of the wrong type or outside the allowed options.
  • 400missing_parameter A required parameter (country, salary, or region where needed) is missing.
  • 400duplicate_parameter The same parameter appears twice.
  • 400unsupported_country The country is not covered (tax tables: 404).
  • 404unsupported_year The tax year is not kept (tax tables: 404); calculations: 400 for a year other than the current one.
  • 401api_key_required Calculation endpoints need a key.
  • 401invalid_key The key is wrong or has been revoked.
  • 429rate_limited Limit reached; wait the number of seconds in Retry-After.
  • 404not_found No such endpoint.
Details

CORS, caching and accuracy

  • GET only. Any origin may call the API from a browser (Access-Control-Allow-Origin: *); no cookies or credentials are used. Keep keys out of public front-end code: call from your server.
  • The figures come from the same calculator engines and data files as calcbloc.com, which are checked against official sources (IRS, HMRC, ATO, Inland Revenue, CRA, Revenue and others). Each tax-table figure carries its source and retrieval date.
  • Results are estimates for planning, not tax advice. When a new tax year is loaded, its year label changes and the old one stops being served.
Versions

Changelog

Tax-year data updates are listed in the data changelog.