Tax API for Relocation Tools — After-Tax Income Comparison

What relocation and expat tools need from a tax API

Relocation tools have specific requirements that differ from simple tax calculators:

• Common currency baseline — the user has one salary, expressed in one currency. The tool needs to evaluate what that income means in 10–20 different countries with different currencies and tax systems.
• Zero-tax jurisdiction support — for expat and digital nomad tools, the UAE, Qatar, Bahrain, and Cayman Islands are among the most searched destinations. The API must return valid zero-tax results (not errors).
• Current country comparison — the user's starting point. The value isn't just "what's my net in Singapore" — it's "how much more (or less) would I keep compared to what I keep now."
• Honest confidence labelling — some countries have complex tax systems (Germany's non-linear formula, US state-by-state variation) where simplified estimates are the best available model. Users should know when a result is approximate.
• Appropriate disclaimers — relocation decisions involve visa eligibility, residency rules, social security agreements, and personal circumstances. Tax is one factor. The tool must not overstate the precision of its output.

Currency conversion for meaningful comparisons

When a user enters their salary in one currency (say, £80,000 GBP) and wants to compare destinations in EUR, SGD, AED, and CHF — all calculations need to use the same real income value. The currency field handles this automatically.

// User earns £80,000. Compare UK vs Germany vs Singapore vs UAE.
// Use "GBP" as the baseline currency — all countries receive GBP 80,000 equivalent.

const countries = ["GB", "DE", "SG", "AE"];

const results = await Promise.all(
  countries.map(country =>
    fetch("https://api.countrytaxcalc.com/api/v1/calculate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.COUNTRYTAXCALC_API_KEY
      },
      body: JSON.stringify({
        income: 80000,
        currency: "GBP",  // same baseline for all
        country
      })
    }).then(r => r.json())
  )
);

// Each result now has:
// - net_income in local currency (GBP, EUR, SGD, AED)
// - currency_conversion.exchange_rate used
// - currency_conversion.rate_date and source
// - effective_tax_rate: directly comparable across all four (same real income)

The currency_conversion object in each response gives you full provenance:

// Example: currency_conversion for UK when passing GBP (no conversion needed)
// For Germany when passing GBP:
"currency_conversion": {
  "input_income": 80000,
  "input_currency": "GBP",
  "local_currency": "EUR",
  "exchange_rate": 1.1742,
  "converted_income": 93936,
  "rate_date": "2026-07-07",
  "rate_source": "api.frankfurter.dev (European Central Bank)",
  "fx_source": "frankfurter",
  "fx_rate_age_hours": 18
}

Surface fx_rate_age_hours to users if it's over 48 hours — you can show "exchange rates may be slightly outdated" for transparency. In practice ECB rates update every business day, so fx_rate_age_hours is almost always under 24.

Zero-tax jurisdictions

Zero-tax jurisdictions are among the most popular destination queries in relocation tools. The API handles them correctly — no special case required:

// UAE has zero income tax
// Response:
{
  "country": "United Arab Emirates",
  "country_code": "AE",
  "gross_income": 93933,  // £80,000 converted to AED equivalent
  "breakdown": {
    "deductions": [],
    "taxable_income": 93933,
    "national_income_tax": {
      "amount": 0,
      "effective_rate": 0,
      "marginal_rate": 0,
      "brackets_applied": []
    },
    "social_contributions": []
  },
  "totals": {
    "total_tax": 0,
    "net_income": 93933,
    "effective_tax_rate": 0,
    "take_home_percentage": 100,
    "monthly_net_income": 7827.75
  },
  "metadata": {
    "accuracy_confidence": 0.95,
    "data_source": "UAE Ministry of Finance"
  }
}

Zero-tax countries supported: UAE, Saudi Arabia, Bahrain, Qatar, Cayman Islands, and others. The full list is in GET /api/v1/countries. In your UI, these will always rank first in a net income sort — which is the correct result.

Current vs. destination comparison

The most useful output for a relocation tool is the delta — how much more or less the user would take home in the destination versus their current situation. Here's the complete pattern:

async function relocationComparison(currentCountry, destinationCountries, grossIncome, currency) {
  // Fetch all at once: current country + all destinations
  const allCountries = [currentCountry, ...destinationCountries];

  const results = await Promise.all(
    allCountries.map(country =>
      fetch("https://api.countrytaxcalc.com/api/v1/calculate", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-Key": process.env.COUNTRYTAXCALC_API_KEY
        },
        body: JSON.stringify({ income: grossIncome, currency, country })
      }).then(r => r.json())
    )
  );

  const current = results[0];
  const destinations = results.slice(1);

  // For each destination, calculate the delta vs. current
  const comparison = destinations.map(dest => {
    // Note: delta is in respective local currencies — for cross-currency delta,
    // you'd need to convert both to a common currency using the FX data
    const netDelta = dest.totals.net_income - current.totals.net_income;
    const rateDelta = dest.totals.effective_tax_rate - current.totals.effective_tax_rate;

    return {
      country: dest.country,
      country_code: dest.country_code,
      currency: dest.currency,
      currency_symbol: dest.currency_symbol,
      net_income: dest.totals.net_income,
      monthly_net: dest.totals.monthly_net_income,
      effective_rate: dest.totals.effective_tax_rate,
      rate_delta: rateDelta.toFixed(2),       // e.g. -8.5 means 8.5pp lower tax
      confidence: dest.metadata.accuracy_confidence,
      data_source: dest.metadata.data_source,
      currency_conversion: dest.currency_conversion || null
    };
  });

  // Sort: lowest effective tax rate first
  comparison.sort((a, b) => a.effective_rate - b.effective_rate);

  return {
    current: {
      country: current.country,
      net_income: current.totals.net_income,
      monthly_net: current.totals.monthly_net_income,
      effective_rate: current.totals.effective_tax_rate,
      currency: current.currency,
      currency_symbol: current.currency_symbol
    },
    destinations: comparison
  };
}

// Usage
const result = await relocationComparison(
  "GB",
  ["DE", "NL", "IE", "SG", "AE", "CH", "PT"],
  80000,
  "GBP"
);

Worked example: UK to Singapore comparison

A user earning £80,000 in the UK wants to understand their take-home in Singapore. Using GBP as the baseline currency:

The net income figures are in each country's local currency. To display the delta meaningfully, either use the exchange rate from currency_conversion to convert destination net to GBP, or compare effective rates directly — rates are always expressed as a percentage and are directly comparable regardless of currency.

Display guidance for relocation tools

Recommendations for how to present tax comparison data in a relocation context:

• Lead with effective rate — it's currency-agnostic and immediately comparable. "Singapore taxes 14.1% of this income" is clear.
• Show local net income with currency symbol — SGD 123,420 feels real; a USD conversion adds context but isn't the primary fact.
• Include monthly equivalent — monthly figures are more relatable for day-to-day planning than annual.
• Confidence indicator — for results with accuracy_confidence < 0.9, prefix with "~" or add "(estimated)" — never present a 0.7-confidence result as a precise figure.
• Data source attribution — show the metadata.data_source for each country ("Tax rates sourced from HMRC / IRAS / Bundeszentralamt für Steuern"). This builds trust with users who want to verify the numbers.
• Exchange rate note — if displaying currency-converted figures, show the exchange rate date and source ("Exchange rates: ECB, [date]").

Honest limitations for relocation tools

The API is highly accurate for what it models — national income tax and standard employee social contributions for a resident taxpayer. There are several things it does not model that are directly relevant to relocation decisions:

• Residency qualification — many zero-tax or low-tax jurisdictions require minimum residency periods or specific visa types. The API tells you the tax rate if you were resident, not whether you qualify to be resident.
• Split-year treatment — the year of arriving in or departing a country often involves pro-rated tax treatment or dual residency periods. The API models a full year of standard residency.
• Social security implications — many countries have bilateral social security agreements that affect which country's contributions apply. National Insurance, pension contributions, and healthcare coverage are material relocation considerations beyond income tax.
• Municipal and local taxes — some countries have significant local-level taxes (e.g. Swiss cantonal taxes, US local income taxes) that may not be fully captured in the standard model.
• Cost of living — tax is one component of financial outcome. Housing, healthcare, childcare, and general costs of living are not reflected in the API data.