OpenAPI specification
Full machine-readable contract for the public REST endpoints. Drop into Postman, Insomnia, or your generator of choice.
Early access · data partnership inquiry
API and data access
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
- Free + open OpenAPI · DCAT catalog · Frictionless datapackage · llms.txt · MCP capability manifest.
- Beta partner programme 1-3 pilots this quarter. Indicative pricing below; metering + billing are by inquiry, not self-serve yet.
- Honest fallback If the public endpoints already fit, we'll tell you — and point at Numbeo / OECD / Eurostat as alternatives.
Inquire about beta access
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
Request beta API access
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.
Already free · CC BY 4.0
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.
API discovery index
Live registry of every public endpoint and dataset in the platform, returned as JSON.
DCAT data catalog
DCAT-AP-style JSON-LD catalog of every dataset, suitable for grounding AI assistants and discovery tools.
Frictionless Data Package
Frictionless Data spec datapackage describing schemas, licences, and CSV/JSON resources.
llms.txt + llms-full.txt
AI-readable platform index. /llms-full.txt expands every section. Both are versioned with the site.
Capability manifest (MCP-discoverable)
Single-document catalogue of every endpoint, supported entity, rate-limit profile, and ranking-independence assertion. Read by MCP clients (public transport at /api/mcp, rate-limited; optional partner bearer) and AI agents.
Plans & indicative pricing
The public layer is free forever. Commercial tiers below are indicative planning anchors for the beta — onboarding is by inquiry while we do customer discovery; there is no self-serve checkout, key issuance, or metering yet. For context, the Numbeo API licenses unsourced, undated cost data from roughly $260–$560/mo — every WhereNext record is dated, named-source-attributed, and confidence-labelled.
Open data
Freeforever · CC BY 4.0
Evaluation, research, light & non-commercial use.
- Every public REST + JSON endpoint (43, listed above)
- OpenAPI spec, DCAT catalog, datapackage, llms.txt
- Attribute to WhereNext with a link back
Developer
from ~$99–$299/mo (indicative)
Apps & AI agents needing headroom and a commercial-use license.
- Higher rate limits for production retrieval
- Commercial-use license beyond CC BY attribution
- Change-feed access (/api/data/rule-changes) for freshness
- CSV + JSON bulk pulls
Enterprise
from ~$10k–$30k/yr (indicative)
Mobility platforms, relocation firms, fintech embedding the feed.
- Full cross-domain feed + rule-change webhook/RSS (by agreement)
- Commercial license + priority support
- Per-corridor packages & periodic refresh
- White-label charts / embeddable cards (case-by-case)
Indicative ranges for planning only — not a live SKU. Final pricing, rate limits, and terms are set per pilot agreement. Data is licensed as-is: decision-support intelligence compiled from named sources, not legal, tax, or immigration advice.
Try a sample query
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.
/api/data/ai-comparison?a=PT&b=ES— open the live endpoint, or explore it below
Side-by-side country comparison across 7 dimensions with natural-language summary.
curl -s 'https://getwherenext.com/api/data/ai-comparison?a=PT&b=ES' \
-H 'Accept: application/json'Sample response200 OKapplication/ld+jsonreal response captured 2026-07-07
{
"@context": "https://schema.org",
"@type": "Dataset",
"name": "Portugal vs Spain: Relocation Comparison Data (2026)",
"license": "https://creativecommons.org/licenses/by/4.0/",
"dateModified": "2026-04-27",
"isAccessibleForFree": true,
"entity": { "type": "comparison", "code": "PT-vs-ES", "name": "Portugal vs Spain" },
"data": {
"countryA": {
"name": "Portugal", "code": "PT",
"monthlyEstimateUsd": 2000, "overallScore": 65,
"globalRank": 19, "globalRankOutOf": 95,
"scores": { "cost": 56, "safety": 95, "healthcare": 83, "education": 84,
"career": 70, "lifestyle": 82, "infrastructure": 74 },
"confidenceScore": 0.88
},
"countryB": {
"name": "Spain", "code": "ES",
"monthlyEstimateUsd": 2200, "overallScore": 64,
"globalRank": 22, "globalRankOutOf": 95,
"scores": { "cost": 48, "safety": 80, "healthcare": 89, "education": 86,
"career": 74, "lifestyle": 73, "infrastructure": 81 },
"confidenceScore": 0.88
},
"dimensionWins": { "PT": 3, "ES": 3, "tied": 1 },
"dimensions": [
{ "name": "Cost of Living", "dimension": "cost", "winner": "PT",
"scoreA": 56, "scoreB": 48,
"insight": "Portugal is approximately 14% more affordable for expats." },
{ "name": "Safety & Security", "dimension": "safety", "winner": "PT",
"scoreA": 95, "scoreB": 80,
"insight": "Portugal outperforms Spain on safety & security by 15 points." }
]
},
"summary": "Portugal scores higher overall (65 vs 64). Portugal has advantages in cost of living, safety & security, and lifestyle & culture. Spain has advantages in healthcare quality, career opportunity, and infrastructure. …",
"sources": ["World Bank", "OECD", "World Health Organization",
"UNDP Human Development Index", "Global Peace Index", "…"],
"confidence": { "level": "high" }
}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.
Rate limits & attribution
The real, enforced values on the public layer today — no aspirational infrastructure claims.
| Rate limit | 30 requests / min per IP (shared across guarded endpoints) |
|---|---|
| License | CC BY 4.0 — attribution required, any use permitted incl. commercial |
| Attribution format | “WhereNext <dataset name> (2026)” linking to the dataset page |
| Scope | City/country-level aggregates only — never per-school or per-person records |
| Higher limits | By inquiry (beta pilots) — no self-serve keys or metering yet |
Who the beta is for
Global mobility platforms
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.
Relocation consultants & immigration firms
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.
AI assistants & answer engines
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.
Honest disclosure
The pricing above is indicative — there is no self-serve checkout, key issuance, or metering today. We publish ranges to be honest about commercial intent and to learn willingness to pay; the actual plumbing (billing, quotas, contracts) is built per pilot, only once recurring demand is real. 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.