# Geo-Parity

> Geographic parity tools for remote work, global pay, and travel: purchasing power parity, fair salaries, Schengen compliance, cross-timezone meetings, contractor economics, freelance rates, tax residency, country comparison, cloud region latency, and digital-nomad visas. Every tool is a fast static page AND a structured, agent-callable JSON endpoint. Built for Answer Engine Optimization (AEO): every capability is reachable by LLMs, headless browsers, and autonomous agents without parsing CSS or guessing form state.

This site treats AI agents as first-class users. Numerical logic is deterministic and stateless, the DOM carries explicit `data-agent-*` semantic hints, and computation is available as a JSON API and a Model Context Protocol (MCP) tool.

**Worldwide, not US-only.** The UI has a persistent "Home base" (country + currency) auto-detected from the visitor's locale and overridable via a header switcher; every tool defaults its "from" country to the home base and displays figures in the home currency (Intl-formatted). Internally, PPP is expressed on a neutral US = 1.0 reference, but all comparisons are bilateral (`home → target`), and the programmatic pages already cover *every* country pair (e.g. `/salary/germany-to-japan`). For agents, money-carrying JSON stays USD-denominated unless a `currency=` param is given, and the API routes read the Cloudflare `cf-ipcountry` header for a sensible default.

Several tools are consolidated to keep the surface small: the homepage is one **Cost & Salary Comparison** hub with tabs `?tab=ppp|compare|prices|salary` (folding the old `/compare`, `/cost-of-living`, `/fair-pay`); `/contractor-calculator` holds Contractor-vs-Employee + `?mode=rate` (old `/hourly-rate`); `/fire` holds FIRE + `?mode=runway` (old `/runway`); `/nomad-visas` holds the visa matcher + `?tab=passports` (old `/passport-power`). All original API endpoints and MCP tool names are retained.

## Core Concepts

- **PPP Index**: A country's price level relative to a US baseline of `1.0`. A value of `0.4` means goods cost ~40% of the US price.
- **Effective Local Purchasing Power**: How far a given US-denominated income stretches in the target country (`income / pppIndex`).
- **Lifestyle Equilibrium Cost**: The local income required to sustain an equivalent US lifestyle (`cost * pppIndex`).

## Capabilities

- **Interactive Calculator** (`/`): Enter an income, choose a data source, and pick a target country to see effective purchasing power and equilibrium cost. Form controls are annotated with `data-agent-purpose` attributes for reliable agent manipulation.
- **Fair Pay Salary Localizer** (`/?tab=salary`, part of the comparison hub): Convert a base salary from a home country into a cost-of-living-fair local equivalent (`S_local = S_base × (I_target / I_home)`). Built for remote-work salary negotiation and global hiring.
- **Calculation API** (`/api/calculate.json?income=100000&target=TH&source=worldbank`): Returns a structured JSON payload with the inputs, the active data source, the resolved PPP index, and derived metrics. The `source` param is optional and defaults to `worldbank`. Suitable for direct agent invocation.
- **Salary API** (`/api/salary.json?base=150000&home=US&target=ES&source=consensus`): Returns the fair local-equivalent salary (USD purchasing-power equivalent), the cost-of-living ratio, the resolved home/target, and a `local` object expressing the figure in the target's local currency at market FX (from World Bank exchange rates). Omit `target` to receive a full localized matrix across every country in the source — ideal for HR/recruiting agents pricing one offer across many markets. `source` defaults to `consensus`.
- **Local Salary Benchmarker** (`/wage-bands`): The real local wage ladder per country — survival floor (essentials), statutory minimum, median (p50), comfortable (p75), top 10% (p90), top 1% (p99) — from a log-normal model calibrated on World Bank GNI per capita (mean, adjusted by each country's actual employment-to-population ratio) and the Gini index (spread). Consumption-based Gini figures (per the WB Poverty & Inequality Platform welfare basis) are widened ~7 points to an income-equivalent so top-decile pay isn't understated. For setting fair local salary bands or seeing where a salary stands ("what is a top 10% salary in Poland?"). Includes a "where do I stand?" reverse lookup, HR band builder, and Fair Pay cross-check.
- **Wage Bands API** (`GET /api/wage-bands.json?country=PL`): Optional `salary` (locate your pay → percentile + out-earns %) and `percentile` (0–100 → exact threshold wage, e.g. 90 for the top-10% floor). Returns all bands (monthly + annual, USD + local currency), the model params, and source years. MCP tool: `calculate_wage_bands`. Estimates, not payroll data.
- **Schengen 90/180** — now part of the **Tax Residency & Schengen Tracker** (`/tax-residency`, see below). Non-EU visitors may be present at most 90 days in any rolling 180-day window; the tracker shows days used/remaining and the exact first overstay date from your itinerary.
- **Visa Check API** (`POST /api/visa-check`): JSON body `{ "trips": [{ "entry": "YYYY-MM-DD", "exit": "YYYY-MM-DD" }], "referenceDate"?: "YYYY-MM-DD", "plannedEntry"?: "YYYY-MM-DD" }`. Returns `{ compliant, daysUsed, daysRemaining, firstOverstayDate, maxDaysInWindow, ... }`. With `plannedEntry`, also returns `plan: { maxStay, latestExit, fullResetDate }` — the longest compliant stay starting on that date. Entry and exit days both count; overlapping trips are de-duplicated. Ideal for AI travel planners validating proposed flights before booking.
- **Team Timezone Friction Scorer** (`/meeting-planner`): Rate how hard a distributed team's timezone spread is to work across. Enter 2+ members' cities and working hours → a 0–100 Friction Score + grade (Effortless/Manageable/Strained/Broken) driven by daily full-team overlap hours, the exact golden-hour meeting window (DST-accurate, per-person hours), and the "lone wolf" — the member whose removal frees the most shared overlap (a hiring / async-workflow signal). Answers "how bad is my team's timezone spread and who's the outlier?".
- **Meeting/Friction API** (`GET /api/meeting.json?zones=Europe/London,America/New_York,Australia/Sydney&start=540&end=1080`): Returns the golden-hour overlap in UTC and each participant's local time (or `overlap: null` + best partial) PLUS a `friction` block `{ score, grade, dailyOverlapHours, overlapMinutes, coverage, loneWolf }`. `zones` comma-separated IANA timezones; `start`/`end` minutes from midnight (default 540/1080); optional per-zone `hours=540-1080;420-720`. MCP tool: `find_meeting_slot`. For scheduler agents and hiring/team-design agents.
- **Contractor Calculator** (`/contractor-calculator`): Compare freelance contractor take-home vs an employee (W2/EOR) salary after taxes and self-paid health insurance; find the break-even hourly rate.
- **Contract API** (`GET /api/contract.json?contractorRate=100&employeeRate=70&country=US`): Returns contractor net, employee net, the break-even contractor rate, and a verdict. Uses transparent effective-rate tax presets per country (all overridable via `ctRate`, `empRate`, `health`, `hours`, `contractorWeeks`, `employeeWeeks`, `expenses`). Pass `taxMode=brackets` for progressive 2025 brackets (US and GB only; response echoes the mode used). Estimates only — not tax advice. Ideal for AI financial advisors evaluating a contract.
- **Cloud Region Selector** (`/cloud-region-selector`): Find the cloud host region minimizing population-weighted latency for a user base, and whether a multi-region split helps.
- **Region API** (`GET /api/region.json?users=US-East:40,UK:30,Germany:30`): `users` is a comma-separated list of `region:percent` pairs (percentages auto-normalize); optional `hosts` restricts candidate host regions and `provider` filters by cloud (AWS | GCP | Azure — 37 curated regions). Returns all host regions ranked by weighted RTT, the best single region, the optimal split (each user routed to nearest host), and the exhaustive best two-region pair. Latency is estimated from geography, not measured. Ideal for deployment agents choosing a default region.
- **Geo-Arbitrage FIRE Engine** (`/fire`): "Where can I retire right now on $400k?" — portfolio × safe withdrawal rate mapped against every country's purchasing-power price level. World heat map + tier table (lean $32k / comfortable $55k / upper $90k / luxury $150k US-equivalent budgets), years-to-FIRE planner, Coast-FIRE mode, SWR sensitivity band, and nomad-visa income-floor eligibility per country.
- **FIRE API** (`GET /api/fire.json?portfolio=400000&swr=0.04`): Optional `source`, `savings` (monthly USD — adds `yearsToTier`), `return` (real annual, fraction or percent), `coast=1`. Returns per-country tier costs, FIRE numbers, achieved tier, coverage, local-currency monthly income, visa eligibility, tier counts at 3/3.5/4/4.5% SWR, and a `statePension` overlay (OECD net pension replacement rate, where covered — a safety net from pension age, not subtracted from the FIRE numbers). MCP tool: `find_fire_locations`. Not financial advice.
- **Pint & Property Index** (`/?tab=prices`, part of the comparison hub): Everyday prices in any two countries — rent, a pint, groceries, transport, gym — from a 32-item curated US baseline scaled by `pppIndex^elasticity` (housing 1.4, services 1.1, utilities 1.0, groceries 0.8, world-priced tradables 0.4). Includes a single-person monthly budget rollup. Model estimates, not quotes.
- **Micro-Costs API** (`GET /api/micro-costs.json?base=GB&target=TH`): Optional `source` (defaults to the consumption basket when it covers both countries, else consensus; echoed in the response). Returns per-item USD + local-currency prices, `pctDiff` per item, category subtotals, and `monthlyBudget`. MCP tool: `estimate_micro_costs`.
- **Country Compare** (`/?tab=compare`, part of the comparison hub): Two countries side by side — price levels across every dataset, percent difference, and $100k salary equivalence both directions.
- **Compare API** (`GET /api/compare.json?a=DE&b=TH`): Returns both countries' full source spreads, the consensus ratio, `pctDifference`, and `salary100k` both directions.
- **Hourly Rate Calculator** (`/contractor-calculator?mode=rate`, merged into the Freelance tool): Work backwards from a desired net income to the freelance hourly/day rate, accounting for tax, health insurance, weeks off, and billable utilization.
- **Rate API** (`GET /api/rate.json?desiredNet=100000&country=US`): Optional `hours`, `weeksOff`, `utilization` (0–1), `expenses`, `health`, `taxRate` (percent). Returns `hourlyRate`, `dayRate`, `requiredGross`, `billableHours`.
- **Tax Residency & Schengen Tracker** (`/tax-residency`): The unified border/tax tool — one travel itinerary in, three answers out. (1) Schengen 90/180 tourist compliance (days used/remaining, first overstay, longest compliant stay). (2) Per-country tax-residency risk on each country's OWN threshold and counting basis: the 183-day rule (calendar-year / rolling-12m / UK Apr-6 / any-365), Cyprus's conditional 60-day rule (flagged only when you're not 183+ resident elsewhere — evaluated from the itinerary), the US Substantial Presence Test (weighted 3-year), and the UK tax-year test — each with safe days left, a leave-by date, and a safe/warning/triggered rating. (3) With an income, the tax cost of triggering residency: standard resident rate (effective-rate checkpoints at $50k/$100k/$200k) vs special expat regimes (Beckham, IFICI, impatriati, Cyprus/Malta non-dom, territorial/remittance), cheaper route flagged. Privacy-first: runs in the browser; dates aren't stored server-side. Answers "will I owe tax if I work from Spain 4 months, and am I still Schengen-legal?".
- **Unified API** (`POST /api/residency-tracker`): JSON body `{ "stays": [{ "country": "ES", "entry": "YYYY-MM-DD", "exit": "YYYY-MM-DD" }], "income"?: 120000, "referenceDate"?: "YYYY-MM-DD" }`. Returns `schengen` (or null), per-country `countries[]` (thresholdDays, daysUsed, safeDaysLeft, risk, secondary Cyprus-60, usSubstantialPresence, ukTaxYear, taxProjection) and a `summary`. MCP tool: `check_travel_residency`. Not tax advice.
- **Legacy single-purpose APIs (still supported)**: `POST /api/visa-check` (Schengen only), `POST /api/residency-check` (day counts, generic 183 + US SPT + UK), `GET /api/tax-trap.json?country=ES&days=120&income=80000` (single-country risk + tax cost). MCP tools `check_schengen`, `check_residency`, `check_tax_residency_risk`.
- **Quality of Life vs Cost Matrix** (`/livability`): Ranks 41 countries by a user-weighted composite of livability metrics — median broadband Mbps, safety, healthcare, air quality, English (curated country-level dataset, the site's replacement for the discontinued Teleport public API) — against monthly essentials cost from the Pint & Property basket. Scatter (cost × quality with quadrants) + ranked list, lifestyle labels per budget, nomad-visa and tax-threshold badges.
- **Livability API** (`GET /api/livability.json?minInternet=80&maxBudget=3000`): All params optional — `budget` (default 3000), `minSafety`, `weights=internet,safety,healthcare,air,english` (0–10 each). Returns ranked rows with composite/value scores, essentials cost, lifestyle label, visa eligibility, and days-to-tax-residency. MCP tool: `rank_livability`.
- **Digital Nomad Visa Income Matcher** (`/nomad-visas`): Enter a monthly remote income (any of ~100 currencies, converted via the site FX table) and household size; the tool computes each of 33 programs' real income threshold — base plus its published per-dependent uplift (e.g. Spain +38% partner/+13% child, Portugal +50%/+25%) — and returns the countries you qualify for plus the near misses just out of reach, with durations, tax notes and official sources. Answers "what nomad visa do I qualify for on $X with a partner and 2 kids?".
- **Nomad Visa API** (`GET /api/nomad-visas.json?income=4000&currency=EUR&partners=1&children=1`): All params optional (`income` in `currency` (default USD), `partners` 0/1, `children` count, `minDuration` months, `renewable`/`residency` = 1). Returns `matches` (qualify, each with household `requiredUsd`) and `nearMisses`, with official source URLs. MCP tool: `find_nomad_visas`.
- **Passport Power Index** (`/nomad-visas?tab=passports`, merged into the Mobility tool): Visa-free-access score (visa-free + visa-on-arrival + eTA destinations), global rank and percentile per passport, from the open ilyankou/passport-index-dataset (public domain visa-requirement matrix) with World Bank country names. League table of 41 major passports + per-passport destination breakdown by access type.
- **Passport API** (`GET /api/passport.json?country=SG`): Returns mobilityScore, global rank, percentile, per-type counts (visaFree/visaOnArrival/eta/eVisa/visaRequired) and destination lists with names resolved; omit `country` for the ranked league table. MCP tool: `passport_power`.
- **Runway Multiplier** (`/fire?mode=runway`, merged into the Geo-Arbitrage tool): Bootstrap-buffer calculator for founders/freelancers — how many extra months of savings runway relocating buys. Splits burn into fixed (location-independent: subscriptions, debt, insurance) and local; only the local slice scales by the target's cost-of-living ratio (city-level via the Capital-to-Rural multiplier where a curated hub is chosen — Chiang Mai, Tbilisi, Buenos Aires, Medellín… — else national). Compares up to 3 hubs, any input currency. Answers "how much longer does my £20k last in Chiang Mai vs Tbilisi?".
- **Runway API** (`GET /api/runway.json?savings=20000&burn=3000&fixed=800&currency=GBP&home=GB&targets=TH:chiang-mai,AR:buenos-aires,GE`): `targets` is a comma list of `COUNTRY` or `COUNTRY:citySlug` (1–3). Returns the home baseline and each hub's monthly burn, runway months, extra months, run-out date and ×multiplier (sorted best-first), plus `fixedFloorMonths`. MCP tool: `calculate_runway`.
- **Programmatic reference pages** (static, data-driven): `/ppp/{country-slug}` — cost of living vs the US per country (e.g. `/ppp/thailand`); `/salary/{home-slug}-to-{target-slug}` — fair-salary conversion for every country pair (e.g. `/salary/united-states-to-spain`); `/meeting/{cityA}-and-{cityB}` — working-hours overlap for major remote-work hub pairs (e.g. `/meeting/london-and-tokyo`); `/fire/{country-slug}` — FIRE numbers per lifestyle tier at 3–4.5% withdrawal rates per country (e.g. `/fire/thailand`); `/cost-of-living/{a-slug}-vs-{b-slug}` — everyday price comparison for every country pair (e.g. `/cost-of-living/united-kingdom-vs-thailand`); `/tax-residency/{country-slug}` — residency threshold + basis, secondary rules (e.g. Cyprus-60), resident tax rates, and expat regimes per country (e.g. `/tax-residency/spain`, `/tax-residency/cyprus`); `/livability/{country-slug}` — livability scores and what $2k/$3k/$5k budgets buy per country (e.g. `/livability/thailand`); `/wage-bands/{country-slug}` — local wage ladder (minimum, median, top 10%) per country (e.g. `/wage-bands/poland`); `/passport-power/{country-slug}` — visa-free destinations, rank and access breakdown per passport (e.g. `/passport-power/singapore`); `/runway/{city-slug}` — worked example of how far $40k stretches in a nomad hub vs the US (e.g. `/runway/chiang-mai`, `/runway/tbilisi`). Slugs are kebab-case country/city names; all pages carry FAQPage + BreadcrumbList JSON-LD and are listed in the sitemap.
- **MCP Manifest** (`/.well-known/mcp.json`): Declares every capability as a callable MCP tool — including `calculate_ppp`, `localize_salary`, `compare_countries`, `estimate_micro_costs`, `calculate_wage_bands`, `compare_contract`, `required_rate`, `find_fire_locations`, `calculate_runway`, `find_meeting_slot`, `check_travel_residency` (plus the legacy `check_schengen` / `check_residency` / `check_tax_residency_risk`), `find_nomad_visas`, `passport_power`, `rank_livability` and `select_region`. Tools whose UI pages were merged keep their original names and endpoints.
- **OpenAPI 3.1 spec** (`/openapi.json`): Machine-readable description of every endpoint, parameter, and error convention — import it into any HTTP tool-calling framework.

## Data

Figures are real, drawn from multiple providers and stored in a swappable registry (`/src/data/datasets`). Each dataset shares the same shape and a US baseline of `1.0`. `pppIndex` is a US-relative price level derived as `PPP conversion factor ÷ market exchange rate` (or rebased to US = 1.0 for Penn World Table), using the latest year available per country (each country carries its reference `year`).

- **`consensus`** — Per-country **median** across the GDP-based providers below. Default source; the most robust single figure.
- **`worldbank`** — World Bank GDP-based price level (`PA.NUS.PPP ÷ PA.NUS.FCRF`). ~41 countries.
- **`imf`** — IMF World Economic Outlook implied PPP (`PPPEX ÷ market exchange rate`). Broadest coverage, recent estimates.
- **`oecd`** — OECD PPP-for-GDP price level (`DSD_NAMAIN10@DF_TABLE4: PPP_B1GQ ÷ EXC_A`). OECD members + key partners only (~34 countries).
- **`pwt`** — Penn World Table price level of GDP (`pl_gdpo`, rebased to USA = 1.0). Academic benchmark.
- **`worldbank-cons`** — World Bank household-consumption price level (`PA.NUS.PRVT.PP ÷ PA.NUS.FCRF`). Reflects a consumption basket.
- **`bigmac`** — The Economist Big Mac index: a US-relative consumer price level from the price of a single standardized good (`local Big Mac price in USD ÷ US price`). Relatable but narrow — ~40 countries, one product; euro-area members share the Euro-area price.
- **`eurostat`** — Eurostat surveyed Price Level Indices for Actual Individual Consumption (`prc_ppp_ind`, EU27=100), rebased to US=1.0. A direct observed basket comparison (not GDP-derived), covering European countries plus the US anchor and Japan — the strongest independent cross-check for the ~19 countries it covers.
- **`factbook`** — CIA World Factbook coverage filler: a US-relative price level for ~100 micro-states and territories the macro sources ignore (Monaco, Bermuda, Cayman, Tuvalu, Malta, Georgia, Qatar…), derived as `GDP(official exchange rate) ÷ Real GDP(PPP)` normalized to US=1.0. Coarse whole-economy estimate, not a consumer basket — for reaching obscure locations only.

Coverage and reference years differ by source, so the set of valid `target` codes depends on the selected `source` (e.g. Thailand and Nigeria appear in most sources but not OECD or Eurostat). Data is refreshed at build time via `npm run data:fetch` (World Bank + IMF + OECD + Penn World Table), `npm run data:bigmac` (The Economist Big Mac index), `npm run data:eurostat` (Eurostat observed price levels), `npm run data:factbook` (CIA World Factbook micro-states), and `npm run data:fx` (World Bank market exchange rates for every entity — ~140 currencies, with territories filled by currency inheritance).

Reference data (not PPP): **Airport lookup** (`GET /api/airports.json?country=TH` | `?iata=BKK` | `?near=13.7,100.5&limit=5`): the scheduled-service large/medium airports from the open OurAirports dataset — by IATA code, by country, or nearest to a coordinate with great-circle distance. A static travel backbone for distance/nearest-airport queries.

**Coverage fallback.** When a `target`/country isn't in the chosen (or default) source and no `source` was pinned, the PPP calculator (`/api/calculate.json`) and cost comparison (`/api/micro-costs.json`) fall back across sources — reaching the ~100 Factbook micro-states/territories rather than erroring. Such responses carry `coverage: { approximate: true, note }` because the Factbook figure is a coarse whole-economy estimate. Pinning an explicit `source` disables the fallback (it will error if the code isn't in that source).

**Sub-national (city) costs.** The `calculate.json` and `micro-costs.json` APIs accept optional city slugs (`city` / `baseCity`+`targetCity`, e.g. `london`, `san-francisco`, `hull`). The engine applies a Capital-to-Rural multiplier on top of the national price level: curated per-city overrides where known, US-metro BEA Regional Price Parities for US cities, else a population-tier heuristic (tier-1 city >1M ×1.15, tier-2 ×1.0, rural ×0.85). Unknown city → national figure. Estimates for orientation, not measured local prices. US metro data refreshes via `npm run data:bea` (requires a free BEA_API_KEY).

## Access & rate limits

Every endpoint above stays **free, open and key-free**, CORS-enabled, with no sign-up. Requests are metered per IP on a fixed hourly window:

- **Anonymous (no key): 300 requests/hour per IP.** Enough for interactive agent use; no registration.
- **With an API key:** 1,000/hour on a free account, 20,000/hour on API Starter, 200,000/hour on API Scale. See `/pricing`.

Send a key as `Authorization: Bearer gp_live_…` (or `?key=…` where headers can't be set). Keys are created at `/account` and only raise the ceiling — they never change the response. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (epoch seconds). Over the limit returns HTTP **429** with `{ "ok": false, "code": "RATE_LIMITED", "retryAfterSeconds": n }` and a `Retry-After` header — back off and retry after the reset.

Paid plans are billed through Stripe; payment never affects the numbers a tool or endpoint returns.

## Notes

- Figures are real, drawn from the providers above (World Bank, IMF, OECD, Penn World Table), and are illustrative — informational only, not investment, relocation, tax, or legal advice.
- The math engine is pure and stateless: identical inputs always yield identical outputs across the UI and the API.