API Documentation

The FiscalMap Tax Intelligence API provides programmatic access to comprehensive tax data for 100+ countries, including income tax rates, capital gains tax, crypto taxation, treaty networks, and economic indicators. Build tax comparison tools, investment platforms, and relocation planning services.

Base URL

https://fiscalmap.app/api/v1/

Endpoints

GET /countries GET /countries/:code GET /crypto New GET /us-states GET /dn-visas GET /rankings GET /filter New GET /compare GET /territorial GET /rates New GET /ease New GET /search POST /simulate GET /treaties GET /stats

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header or as a query parameter.

Option 1: Authorization Header (recommended)

Authorization: Bearer YOUR_API_KEY

Option 2: Query Parameter

?api_key=YOUR_API_KEY

API Tiers — Annual Billing

Free

500 requests/month

Countries list
Basic fields only
No crypto details
No treaties

Starter

$699

per year · 15,000 req/month

Full country data
Crypto endpoint
Economic data (PPP, CoL)
Digital nomad visas
US States data

Pro

$2,499

per year · 100,000 req/month

Everything in Starter
Tax simulation engine
Treaty network (5,000+ pairs)
Priority email support

Business

$7,499

per year · 500,000 req/month

Everything in Pro
Dedicated support
Higher rate limits
Invoice billing

Enterprise

Custom

Unlimited + SLA

Everything in Business
Custom integrations
SLA guarantee
Dedicated account manager

📧 Request API Key →

Countries

GET /api/v1/countries

Returns a list of all countries with their tax profiles. Supports filtering by tax system, rates, region, and crypto-friendliness.

Query Parameters

Parameter	Type	Description
type	string	Filter by tax system: `Territorial`, `Worldwide`, `None`, `Non-Dom`, `Remittance`
max_income	number	Maximum income tax rate (e.g., `15` for ≤15%)
max_cg	number	Maximum capital gains tax rate
min_score	number	Minimum overall FiscalMap score (0-100)
min_crypto_score New	number	Minimum crypto-friendliness score (1-5)
region	string	Filter by region: `EU`, `LATAM`, `GULF`, `CARIBBEAN`, `ASIA`
max_res_cost	number	Maximum residency cost in USD
sort	string	Sort by: `score`, `income`, `cg`, `crypto_score`, `safety`
order	string	`asc` or `desc` (default: desc)
page / limit	number	Pagination (default: page=1, limit=50, max: 100)

        Example Request
      
GET /api/v1/countries?type=Territorial&max_income=10&min_crypto_score=4

GET /api/v1/countries/:code

Returns full details for a specific country, including tax rates, crypto policy, economic data, residency info, and digital nomad visa details.

        Example Response
      

{
  "data": {
    "code": "UAE",
    "name": "United Arab Emirates",
    "flag": "🇦🇪",
    "income": 0,
    "cg": 0,
    "wealth": 0,
    "inheritance": 0,
    "type": "Territorial",
    "score": 98,
    "safety": 8,
    "col": 4,
    "healthcare": 7,
    "days": 90,
    "resCost": "$0–3,500",
    "ppp_index": 88,
    "monthly_budget": {
      "rent": 1800,
      "food": 500,
      "transport": 150,
      "total": 2800,
      "city": "Dubai"
    },
    "crypto": {
      "score": 5,
      "tax": "0%",
      "note": "Zero crypto tax. Dubai and Abu Dhabi are major institutional crypto hubs."
    },
    "dn_visa": { ... },
    "social_security": { ... },
    "pros": [...],
    "cons": [...]
  },
  "tier": "pro"
}
      

Response Fields

Field	Type	Description
income	number	Top marginal income tax rate (%)
cg	number	Capital gains tax rate (%)
type	string	Tax system: Territorial, Worldwide, None, Non-Dom, Remittance
ppp_index	number	Purchasing Power Parity index (100 = US baseline). Higher = cheaper.
col	number	Cost of living score (1=cheapest to 5=most expensive)
monthly_budget	object	Estimated monthly expenses (rent, food, transport) for a typical expat
crypto	object	Crypto taxation details (score, tax rate, regulatory notes)
social_security	object	Employee (ee) and employer (er) contribution rates (%)

Crypto Tax Data New

🪙 Comprehensive Crypto Taxation Intelligence

Access crypto-specific tax rates, regulatory environments, and friendliness scores for every country. Perfect for building crypto tax planning tools, exchange compliance features, or investor relocation guides.

GET /api/v1/crypto

Returns countries ranked by crypto-friendliness with detailed crypto tax information. Score scale: 1 (hostile) → 5 (top global hub).

Query Parameters

Parameter	Type	Description
min_score	number	Minimum crypto score (1-5). Example: `4` for friendly+ only
max_tax	string	Exact crypto tax rate filter. Example: `0%` for zero-tax jurisdictions
region	string	Region filter: `GULF`, `CARIBBEAN`, `EU`, `LATAM`, `ASIA`
page / limit	number	Pagination (default: limit=50)

        Example: Zero-Tax Crypto Havens
      
GET /api/v1/crypto?max_tax=0%&min_score=4

        Example Response
      

{
  "data": [
    {
      "code": "UAE",
      "name": "United Arab Emirates",
      "flag": "🇦🇪",
      "income_tax": 0,
      "cg_tax": 0,
      "tax_system": "Territorial",
      "overall_score": 98,
      "crypto": {
        "score": 5,
        "tax": "0%",
        "note": "Zero crypto tax — no CGT, no tax on gains. Dubai and Abu Dhabi are major institutional crypto hubs (VARA, ADGM). One of the most advanced regulatory frameworks globally."
      }
    },
    {
      "code": "CYM",
      "name": "Cayman Islands",
      "crypto": {
        "score": 5,
        "tax": "0%",
        "note": "Zero tax of any kind, crypto included. The world's leading crypto fund center — Cayman is the reference domicile for DAOs, hedge funds and major DeFi protocols."
      }
    }
    // ... more countries
  ],
  "pagination": { "page": 1, "limit": 50, "total": 24 },
  "score_distribution": { "5": 8, "4": 16, "3": 35, "2": 28, "1": 12 },
  "_note": "crypto.score: 1=unfriendly, 2=hostile/unclear, 3=neutral, 4=friendly, 5=top hub"
}
      

Crypto Score Definitions

Score	Label	Description
5	Top Hub	Global crypto center with clear regulation, 0% CGT, institutional presence (UAE, Cayman, Switzerland, Singapore, Gibraltar)
4	Friendly	0% CGT or favorable holding rules, progressive regulation (Germany 1yr rule, Portugal, Malta, Cyprus Non-Dom)
3	Neutral	Standard CGT applies, no special hostility, developing framework (most EU countries under MiCA)
2	Unclear	High taxes (25%+) or ambiguous legal status, limited regulatory clarity
1	Hostile	Crypto banned, severely restricted, or punitive taxation

US States

GET /api/v1/us-states

Returns tax data for all 50 US states + DC, including state income tax, capital gains treatment, property taxes, and cost of living.

GET /api/v1/us-states/:code

Returns detailed tax profile for a specific US state. Use 2-letter state codes (TX, FL, CA, etc.).

Digital Nomad Visas

GET /api/v1/dn-visas

Returns all countries offering digital nomad visa programs with requirements, costs, duration, and income thresholds.

        Response Fields
      

{
  "visa": "Remote Work Visa",
  "duration": "1yr renewable",
  "income_req": "$5,000/mo",
  "cost": "$611",
  "tax": "0% income tax",
  "stay": "No minimum",
  "remote_friendly": 9,
  "process": "Apply through Dubai Tourism..."
}
      

Rankings

GET /api/v1/rankings

Returns countries ranked by a specific metric.

Query Parameters

Parameter	Type	Description
metric	string	Ranking metric: `score`, `income`, `cg`, `wealth`, `safety`, `healthcare`, `col`, `ppp`, `crypto_score`
limit	number	Number of results (default: 20)

        Example: Top Countries by Crypto Score
      
GET /api/v1/rankings?metric=crypto_score&limit=10

Compare Countries

GET /api/v1/compare

Side-by-side comparison of 2-4 countries with all tax metrics, economic data, and crypto policies.

Query Parameters

Parameter	Type	Description
codesrequired	string	Comma-separated country codes (2-4). Example: `UAE,PY,GEO,POR`

        Example
      
GET /api/v1/compare?codes=UAE,PY,GEO

Territorial Tax Countries

GET /api/v1/territorial

Returns all countries with territorial taxation (0% tax on foreign income) or no income tax. Ideal for digital nomads and location-independent entrepreneurs.

Advanced Filter New

GET /api/v1/filter

Advanced multi-criteria filtering across all metrics. Combine any number of min/max thresholds to find countries matching precise requirements. Results sorted by overall score.

Query Parameters

Parameter	Type	Description
`min_score` / `max_score`	number	Overall FiscalMap score (0-100)
`min_income` / `max_income`	number	Income tax rate (%)
`min_corp` / `max_corp`	number	Corporate tax rate (%)
`min_cg` / `max_cg`	number	Capital gains tax rate (%)
`min_wealth` / `max_wealth`	number	Wealth tax rate (%)
`min_crypto_score` / `max_crypto_score`	number	Crypto friendliness score (1-5)
`min_safety` / `max_safety`	number	Safety score (1-10)
`min_ppp` / `max_ppp`	number	Purchasing Power Parity index
`tax_type`	string	Tax system: `Territorial`, `Worldwide`, `None`, `Non-Dom`, `Remittance`
`dn_visa`	boolean	Set to `1` for countries with digital nomad visa only

Example: Low-tax, crypto-friendly, safe countries

GET /api/v1/filter?max_income=15&min_crypto_score=4&min_safety=7

Tax Rate Tables New

GET /api/v1/rates

Extended tax rate tables covering 150-200+ jurisdictions — significantly broader than the core country profiles. Returns available rate types when called without a sub-path.

GET /api/v1/rates/:type

Returns the full rate table for a specific tax type. Supports filtering by rate range and sorting.

Query Parameters

Parameter	Type	Description
`min_rate`	number	Minimum tax rate (%)
`max_rate`	number	Maximum tax rate (%)
`order`	string	`asc` (default) or `desc`

Example: Countries with corporate tax under 15%

GET /api/v1/rates/corp?max_rate=15

Ease of Business New

GET /api/v1/ease

Ease of business and residency setup scores for all countries. Scale: 1 (easiest) to 10 (hardest). Useful for ranking countries by bureaucratic complexity.

Query Parameters

Parameter	Type	Description
`order`	string	`asc` (easiest first) or `desc` (default, hardest first)

Example

GET /api/v1/ease?order=asc

Example Response

{
  "endpoint": "/api/v1/ease",
  "description": "Ease of business/residency setup scores (1-10, higher = harder)",
  "count": 99,
  "data": [
    { "code": "UAE", "score": 3 },
    { "code": "GEO", "score": 2 },
    { "code": "PRY", "score": 4 }
  ]
}

Search

GET /api/v1/search

Full-text search across country names, notes, and tax details.

Query Parameters

Parameter	Type	Description
qrequired	string	Search query. Example: `crypto friendly`, `golden visa`, `no inheritance`

Tax Simulation Pro

POST /api/v1/simulate

Simulates personal tax liability in a specific country based on income, capital gains, dividends, and crypto gains. Returns detailed breakdown with effective rates.

Request Body (JSON)

Field	Type	Description
countryrequired	string	Country code (e.g., `UAE`, `PY`)
income	number	Annual employment/business income (USD)
capital_gains	number	Capital gains from stocks, real estate (USD)
crypto_gains	number	Cryptocurrency gains (USD)
dividends	number	Dividend income (USD)
source	string	`local` or `foreign` (affects territorial systems)

        Example Request
      

POST /api/v1/simulate
Content-Type: application/json

{
  "country": "PY",
  "income": 100000,
  "crypto_gains": 50000,
  "source": "foreign"
}
      

        Example Response
      

{
  "country": "PY",
  "country_name": "Paraguay",
  "total_income": 150000,
  "total_tax": 0,
  "effective_rate": "0.00%",
  "breakdown": {
    "income_tax": 0,
    "crypto_tax": 0,
    "social_security": 0
  },
  "note": "Paraguay's territorial system exempts all foreign-sourced income. Crypto from foreign sources: 0%."
}
      

Tax Treaties Pro

🌐 5,000+ Bilateral Tax Treaty Pairs

Access withholding tax rates from the OECD treaty network (2025 data): dividends, interest, royalties, and technical fees between country pairs. Essential for international investment structuring and corporate planning.

GET /api/v1/treaties/:country_a/:country_b

Returns treaty withholding rates between two countries.

        Example
      

GET /api/v1/treaties/FRA/DEU

{
  "from": "FRA",
  "to": "DEU",
  "dividends": 5,
  "interest": 0,
  "royalties": 0,
  "tech_fees": 0
}
      

GET /api/v1/treaties/:country_code

Returns all treaty partners for a given country with their respective rates.

GET /api/v1/treaties/search

Search treaties by rate thresholds (e.g., find all pairs with 0% dividend withholding).

Query Parameters

Parameter	Type	Description
from	string	Source country code
to	string	Destination country code
max_div	number	Maximum dividend withholding rate (%)
max_int	number	Maximum interest withholding rate (%)
zero_div	boolean	Set to `1` for 0% dividend treaties only

GET /api/v1/treaties/stats

Returns aggregate treaty network statistics: total pairs, average rates, countries with most treaties.

API Statistics

GET /api/v1/stats

Returns API metadata: data coverage, update dates, and aggregate statistics.

        Example Response
      

{
  "data": {
    "countries_count": 99,
    "us_states_count": 51,
    "dn_visas_count": 26,
    "last_updated": "2026-03-10"
  },
  "breakdown": {
    "zero_tax": 12,
    "territorial": 28,
    "worldwide": 54,
    "with_dn_visa": 26,
    "avg_income_tax": 24,
    "avg_cg_tax": 15
  }
}
      

Error Handling

All errors return a JSON object with the following structure:

    Error Response Format
  

{
  "error": "Country code 'XYZ' not found",
  "code": "COUNTRY_NOT_FOUND",
  "status": 404
}
  

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Invalid parameters or malformed request
401	UNAUTHORIZED	Missing or invalid API key
403	TIER_RESTRICTED	Endpoint requires higher tier (e.g., Pro for treaties)
404	NOT_FOUND	Country code or resource not found
429	RATE_LIMITED	Too many requests — rate limit exceeded

Rate Limits

Tier	Price	Requests/Month	Requests/Minute
Free	$0	500	10
Starter	$699/year	15,000	30
Pro	$2,499/year	100,000	120
Business	$7,499/year	500,000	300
Enterprise	Custom	Unlimited	Custom

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

API Documentation

Authentication

API Tiers — Annual Billing

Countries

Crypto Tax Data New

🪙 Comprehensive Crypto Taxation Intelligence

US States

Digital Nomad Visas

Rankings

Compare Countries

Territorial Tax Countries

Advanced Filter New

Query Parameters

Example: Low-tax, crypto-friendly, safe countries

Tax Rate Tables New

Query Parameters

Example: Countries with corporate tax under 15%

Ease of Business New

Query Parameters

Example

Example Response

Search

Tax Simulation Pro

Tax Treaties Pro

🌐 5,000+ Bilateral Tax Treaty Pairs

API Statistics

Error Handling

Rate Limits

Let's talk.