OpenAPI specification
Full machine-readable contract for the public REST endpoints. Drop into Postman, Insomnia, or your generator of choice.
Loading...
Loading...
Early access · data partnership inquiry
Quick answer
Programmatic access to WhereNext's structured relocation intelligence — 95-country, 380-city, 4,149-school, and 30-golden-visa-programme data, all CC BY 4.0 underlying. The public REST and JSON endpoints below are free forever; this page is the inquiry surface for higher rate limits, embeddable widgets, MCP transport access, and partner agreements. No SLAs / SOC 2 / custom dashboards promised yet — we onboard 1-3 pilots per quarter.
Key facts
Tell us about your use case. We reply from a real address — no automated funnel, no newsletter. If we’re not the right fit, we’ll point you to a public endpoint or another data publisher rather than waste your time.
Limited beta · 1–3 pilots this quarter
We pair inquiries with our highest-fit endpoints. Higher rate limits and white-label widgets are available case-by-case during the customer-discovery period — we are deliberately not productising billing or quotas yet.
You don’t need a key or an inquiry to use any of these endpoints. They’re published under Creative Commons Attribution 4.0 — attribute to WhereNext with a link back, and any use (including commercial) is allowed.
Full machine-readable contract for the public REST endpoints. Drop into Postman, Insomnia, or your generator of choice.
Live registry of every public endpoint and dataset in the platform, returned as JSON.
DCAT-AP-style JSON-LD catalog of every dataset, suitable for grounding AI assistants and discovery tools.
Frictionless Data spec datapackage describing schemas, licences, and CSV/JSON resources.
AI-readable platform index. /llms-full.txt expands every section. Both are versioned with the site.
Single-document catalogue of every endpoint, supported entity, rate-limit profile, and ranking-independence assertion. Read by MCP clients (transport at /api/mcp, requires bearer) and AI agents.
Every endpoint below is live in production. No auth, no key — copy the URL, paste it into a browser or curl, inspect the JSON. The shapes below are abbreviated for readability.
GET · country comparison
/api/data/ai-comparison?a=PT&b=ES
Side-by-side scoring of Portugal vs Spain across 7 dimensions with a natural-language summary.
{
"@context": "https://schema.org",
"@type": "Dataset",
"name": "Portugal vs Spain — WhereNext comparison",
"description": "Side-by-side scoring of Portugal vs Spain across seven WhereNext dimensions (cost, safety, healthcare, career, infrastructure, lifestyle, education) with a natural-language summary.",
"winner": "PT",
"dimensions": {
"cost": { "PT": 6.8, "ES": 6.2, "winner": "PT" },
"safety": { "PT": 8.4, "ES": 7.6, "winner": "PT" },
"healthcare": { "PT": 7.9, "ES": 8.1, "winner": "ES" },
"career": { "PT": 5.2, "ES": 6.4, "winner": "ES" },
"infrastructure":{ "PT": 7.1, "ES": 7.4, "winner": "ES" }
},
"summary": "Portugal edges Spain on cost and safety; Spain wins healthcare and career."
}GET · tax intelligence
/api/data/ai-tax/pt?income=100000
Effective rate for $100k income in Portugal, plus brackets, social contributions, and special expat regimes.
{
"country": "Portugal",
"effective_rate_pct": 32.4,
"brackets": [/* progressive IRS brackets */],
"social_contributions_pct": 11.0,
"special_regimes": ["NHR (closed to new entrants 2024)", "IFICI"],
"notes": "USD→EUR FX at issue date; consult a Portuguese tax adviser."
}GET · school intelligence
/api/data/school-intelligence/dubai
Per-city school market: median tuition, hidden-fee analysis, budget tiers, and best-value picks.
{
"city": "Dubai", "country": "United Arab Emirates",
"schools_count": 203,
"median_tuition_usd": 13500,
"tuition_range_usd": [5950, 86486],
"hidden_fees_pct_median": 18.4,
"curricula": ["British", "American", "IB", "Indian", "French", "German"],
"best_value_top3": [/* 3 schools with fit + true_cost + accreditation */]
}POST · agent workflow · plan a relocation
/api/intelligence/plan-relocation
One call for the full intake-to-next-step journey: nl-query → shortlist → readiness + first-year cost per destination → recommended advisor category.
POST /api/intelligence/plan-relocation
Content-Type: application/json
{
"query": "US family with two kids, $5k/mo, warm climate, schools matter"
}
→ 200 OK · application/ld+json
{
"shortlist": ["PT", "ES", "MX", "CR"],
"readiness": [/* per-destination score + blockers */],
"first_year_cost": [/* per-destination move-in + recurring */],
"recommended_advisor": "immigration_lawyer",
"assumptions": ["heuristic: persona=families", "budget tier: 5000"]
}Full catalog: 43 endpoints across /api/data/index. Canonical schema: openapi.yaml. MCP transport for agents: capabilities manifest.
Pre-fill destination cost, tax, and visa context inside an HR or relocation-management tool. Reduce the back-and-forth with employees evaluating an offer abroad.
Likely fit: Higher request volume, embeddable destination cards, tax/visa pre-checks.
Bulk pull country / city / school / property aggregates into a client-facing dashboard with consistent data lineage.
Likely fit: Per-route packages (e.g. US to PT, UK to ES), white-label charts, periodic refresh.
Ground relocation answers in WhereNext's freshness-tagged, CC BY 4.0 structured intelligence rather than crowdsourced anecdotes.
Likely fit: Higher rate limits for retrieval, citation-friendly response envelope, dataset DOIs.
There is no paid API tier today. Pricing, SLAs, and metering are deliberately deferred until we’ve done customer discovery with enough partners to pick the shape that actually solves a problem — this avoids the trap of building a marketplace with the wrong plumbing.
If you need a contract, an SLA, or commercial-grade rate limits today, theNumbeo API and the public OECD / World Bank / Eurostat APIs may already cover you. WhereNext’s differentiator is structured cross-domain relocation intelligence (cost + tax + visa + schools + property in one envelope) — let us know if that matters to you.