DEV Community: Mathis Higuinen

Building a multilingual API serving 39,585 visa pairs in 15 languages

Mathis Higuinen — Tue, 26 May 2026 23:34:53 +0000

How we structured a visa requirements database across 15 languages with ISO standardization, caching layers, and translation pipelines.

Most travel APIs return data in English. That's fine if your users are American or British. It's useless if they're Japanese, Thai, Arabic-speaking, or any of the 5.5 billion people whose first language isn't English.

When a Vietnamese traveler looks up visa requirements for France, they need the answer in Vietnamese — not just the visa type, but the required documents list, the application process, the embassy information, the travel tips. Translating "Valid passport with 6 months minimum validity" into 15 languages isn't a string replacement. It's a content localization problem at scale.

The Orizn Visa API serves 39,585 passport-destination pairs in 15 languages: English, French, Spanish, Portuguese, German, Japanese, Korean, Chinese, Russian, Italian, Arabic, Hindi, Thai, Vietnamese, and Filipino. Here's how the system is structured.

Why these 15 languages

Not random. These 15 cover approximately 75% of the world's internet users by primary language:

English — lingua franca, baseline
Chinese — 1.1B speakers, China's visa-free program expanding rapidly
Spanish — 550M speakers, Latin America is a growing travel market
Hindi — 600M speakers, Indian passport holders are one of the most visa-restricted populations
Arabic — 370M speakers, Gulf states have some of the fastest-growing passports
Portuguese — 260M speakers, Brazil alone has 210M people
French — 280M speakers, major passport in Africa and Europe
Japanese, Korean — high-value travel markets, strong outbound tourism
Russian — 250M speakers, complex visa landscape post-2022
German, Italian — core EU passports
Thai, Vietnamese, Filipino — Southeast Asia, where digital nomads concentrate

Each language isn't just a translation — it's a market. A Thai translation means Thai travel bloggers can embed our widgets and Thai developers can build apps with localized visa data.

Data architecture

The core data model is simple:

visa_pair {
  passport:     ISO 3166-1 alpha-3  (e.g. "FRA")
  destination:  ISO 3166-1 alpha-3  (e.g. "JPN")
  requirement:  enum                (visa_free | visa_required | e_visa |
                                     visa_on_arrival | eta | no_admission)
  visa_free_days: integer | null
  verified:     boolean
  source_url:   string
  last_updated: timestamp
}

199 passports × 199 destinations = 39,601 theoretical pairs. Some pairs are self-referential (you don't need a visa to visit your own country), bringing the actual count to 39,585.

Each pair has a base record in English. Translations are stored separately:

visa_translation {
  passport:     ISO3
  destination:  ISO3
  lang:         enum (15 values)
  description:  text
  documents:    text[]
  process:      text[]
  tips:         text[]
}

39,585 pairs × 15 languages = 593,775 translation records. That's the real scale of the system.

The translation pipeline

Raw visa data comes from 136 government portals. Most publish in their national language plus English. Some only publish in their national language.

The pipeline has 5 stages:

1. Extraction — Pull structured visa rules from government sources. This is the hardest part. Every government formats their visa information differently. Some have clean REST APIs. Most have PDF documents or HTML pages with inconsistent formatting.

2. Normalization — Map to the 6 standardized requirement types. A government might say "no visa needed for stays under 90 days" — that maps to visa_free with visa_free_days: 90. Another might say "electronic authorization required prior to travel" — that's eta. The mapping isn't always obvious and edge cases are everywhere.

3. English baseline — Generate the English version with all fields: description, documents_required, process, tips, country_info. This is the canonical record that everything else derives from.

4. Translation — Generate the 14 other language versions. This isn't word-for-word translation. Document names, process steps, and tips need to be culturally adapted. "Apply at the embassy" in Japanese includes the Japanese name of the embassy and Japanese-language application forms. "Proof of sufficient funds" in Arabic needs to reflect local banking norms.

5. Verification — Cross-check against at least 2 independent sources per pair. The verified flag indicates whether the data has been confirmed. Unverified pairs are still returned but flagged — better to have data with a caveat than no data at all.

Caching strategy

With 593K+ records and 15 language variants, caching is critical:

Request flow:
Client → API Gateway → Cache (Redis) → Database

Cache key pattern: visa:{passport}:{destination}:{lang}

The TTL strategy is split by volatility:

24 hours for stable pairs — visa types don't change hourly. A visa_free pair that's been stable for 3 years doesn't need real-time freshness.
1 hour for recently changed pairs — if Thailand just modified its policy, the cache needs to reflect that quickly.
No cache for the /changes endpoint — it queries the diff table directly. When someone asks "what changed this week?", they need the latest data, not a cached snapshot.

The /check endpoint (quick check, no documents) is cached aggressively — it returns 5 fields. The /visa endpoint (full details with documents, process, tips) has shorter TTLs because embassies can update document requirements at any time.

ISO standardization decisions

We use ISO 3166-1 alpha-3 exclusively. Not alpha-2 (FR, JP), not country names (France, Japan), not IATA codes (CDG, NRT). Three reasons:

Unambiguous — alpha-3 has no collisions across all 199 countries
Universal — same codes work regardless of language (a Japanese developer sends FRA, not フランス)
Machine-readable — 3 uppercase ASCII characters, trivially validatable with a regex

The API auto-uppercases inputs (fra → FRA) and returns clear error messages for invalid codes:

{
  "error": "\"passport\" value \"JP\" is not a valid ISO 3166-1 alpha-3 code. Did you mean \"JPN\"?"
}

This matters especially for MCP and agent usage where the LLM might send lowercase or alpha-2 codes. A clear error message lets the agent self-correct and retry.

What I'd do differently

Start with fewer languages. Launching with 15 simultaneously was ambitious. Starting with 5 (English, Spanish, French, Chinese, Arabic) and adding based on demand would have been faster and let us focus quality on the highest-impact languages first.

Invest in government source monitoring earlier. The hardest operational challenge isn't translation — it's knowing when a government changes its visa policy. Thailand's 60→30 day rollback happened via a cabinet resolution. That's not an RSS feed. Building automated monitoring for 136 government portals is an ongoing project.

Build the diff system from day one. We added the /changes endpoint later. If we'd built temporal versioning into the data model from the start (valid_from, valid_to on every record), the change detection and audit trail features would have been trivial instead of retrofitted.

Try the API

The multilingual response in action:

# English (free, no API key)
curl "https://visa.orizn.app/api/v1/visa/check?passport=JPN&destination=FRA"

# Japanese (needs free API key)
curl -H "x-api-key: YOUR_KEY" \
  "https://visa.orizn.app/api/v1/visa?passport=JPN&destination=FRA&lang=ja"

# Arabic
curl -H "x-api-key: YOUR_KEY" \
  "https://visa.orizn.app/api/v1/visa?passport=JPN&destination=FRA&lang=ar"

Quick checks are free, no API key needed. Full details in 15 languages with a free key (3,000 req/month) from visa.orizn.app.

SDKs: npm install orizn · pip install orizn · cargo add orizn

Source: github.com/MattJeff/orizn-visa-api

Building an MCP Server for Visa Requirements in TypeScript

Mathis Higuinen — Tue, 26 May 2026 15:15:10 +0000

What is MCP, and why should you care?

The Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI agents connect to external tools and data sources through a unified interface. Think of it as USB-C for AI: one protocol, any agent. Instead of building custom integrations for Claude, GPT, Gemini, and every other model, you build one MCP server and every compatible agent can use it.

MCP defines a simple contract. Your server exposes tools (functions the AI can call) and resources (data the AI can read). The agent discovers what's available, reads the descriptions, and decides when to use them. The transport layer is pluggable -- stdio for local tools, SSE or HTTP for remote ones.

The protocol is gaining traction fast. Claude Desktop, Cursor, Windsurf, and dozens of other clients already support it. If you have an API that AI agents should be able to use, wrapping it in MCP is one of the highest-leverage things you can do right now.

Why visa requirements are perfect for MCP

Here's a problem every travel-focused AI agent has: visa requirements. Ask an LLM whether a Brazilian passport holder needs a visa for Japan, and you'll get an answer -- but it might be wrong. Models rely on training data that's months or years old, and visa policies change constantly. Thailand just launched a new 60-day visa exemption. Turkey updated its e-visa rules. The model doesn't know.

Visa data is structured, query-driven, and time-sensitive. It's exactly the kind of information that should come from a live API, not from parametric memory. An MCP server bridges that gap: the agent recognizes a visa question, calls the tool, and gets current data from a real database.

That's what we built with the Orizn Visa MCP Server -- a TypeScript MCP server backed by an API covering 39,585 passport-destination pairs in 15 languages.

Architecture overview

The stack is deliberately minimal:

Runtime: Node.js 18+
Language: TypeScript
MCP SDK: @modelcontextprotocol/sdk (v1.12+)
Transport: stdio (runs locally alongside the AI client)
Backend: Orizn Visa API at https://visa.orizn.app/api/v1/visa

The server exposes 5 tools and 2 resources:

Tools	Description
`check_visa_requirement`	Full visa details for a passport-destination pair
`quick_visa_check`	Fast yes/no check (free, no API key)
`get_all_destinations`	All destinations for one passport at once
`get_visa_changes`	Recent visa policy updates
`get_coverage_stats`	Database coverage statistics

Resources	Description
`visa://supported-languages`	The 15 supported language codes
`visa://country-codes`	All 199 ISO3 country codes the API accepts

Code walkthrough

Server initialization

MCP servers start with a Server instance and a transport. We use StdioServerTransport, which communicates over stdin/stdout -- the standard for local MCP servers:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "orizn-visa", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

const transport = new StdioServerTransport();
await server.connect(transport);

You register capabilities upfront -- tools and resources -- so the client knows what to expect.

Defining tools

Tools are defined with a name, description, and JSON Schema for inputs. Here's the core visa check tool:

{
  name: "check_visa_requirement",
  description:
    "Check visa requirements between any two countries. Returns visa type " +
    "(visa-free, e-visa, visa required, etc.), allowed stay duration, " +
    "required documents, step-by-step application process, and travel tips. " +
    "Covers 39,585 passport-destination pairs in 15 languages. " +
    "Use this tool when the user asks about visa rules, entry requirements, " +
    "or whether they need a visa to visit a country.",
  inputSchema: {
    type: "object",
    properties: {
      passport: {
        type: "string",
        description: "ISO 3166-1 alpha-3 code of the passport (e.g. 'FRA').",
      },
      destination: {
        type: "string",
        description: "ISO 3166-1 alpha-3 code of the destination (e.g. 'JPN').",
      },
      lang: {
        type: "string",
        description: "Language code for the response. Defaults to 'en'.",
      },
    },
    required: ["passport", "destination"],
  },
}

The tool handler validates inputs and calls the API:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args = {} } = request.params;

  switch (name) {
    case "check_visa_requirement": {
      const passport = validateISO3(args.passport, "passport");
      const destination = validateISO3(args.destination, "destination");
      const lang = validateLang(args.lang);
      const result = await apiFetch("", { passport, destination, lang }, apiKey, true);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
    // ... other tools
  }
});

Resources

Resources let the agent look up reference data without burning an API call. We expose two static resources -- supported languages and valid country codes:

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  switch (request.params.uri) {
    case "visa://supported-languages":
      return {
        contents: [{
          uri: request.params.uri,
          mimeType: "application/json",
          text: JSON.stringify(SUPPORTED_LANGUAGES_RESOURCE, null, 2),
        }],
      };
    case "visa://country-codes":
      return {
        contents: [{
          uri: request.params.uri,
          mimeType: "application/json",
          text: JSON.stringify(COUNTRY_CODES_RESOURCE, null, 2),
        }],
      };
  }
});

This way, when the agent isn't sure of a country code, it can check the resource first instead of guessing.

API client with retry logic

The API client handles timeouts, retries on 5xx errors, and fails fast on 4xx:

async function apiFetch(path: string, params: Record<string, string>,
                        apiKey: string | undefined, requiresKey: boolean): Promise<unknown> {
  let lastError: Error | undefined;

  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);

    try {
      const response = await fetch(url.toString(), {
        method: "GET", headers, signal: controller.signal,
      });
      clearTimeout(timeout);

      if (response.ok) return await response.json();

      // Don't retry client errors -- the request itself is wrong
      if (response.status >= 400 && response.status < 500) {
        throw new McpError(ErrorCode.InvalidRequest,
          `API returned ${response.status}: ${await response.text()}`);
      }

      // 5xx: retry
      lastError = new Error(`API returned ${response.status}`);
    } catch (err) {
      clearTimeout(timeout);
      if (err instanceof McpError) throw err;
      lastError = err instanceof Error ? err : new Error(String(err));
    }
  }

  throw new McpError(ErrorCode.InternalError,
    `API request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message}`);
}

The distinction between 4xx and 5xx is important. A 400 means the agent sent bad parameters -- retrying won't help. A 503 means the server hiccupped -- retrying might.

ISO3 validation

Country codes are validated against a hardcoded set of 199 codes before hitting the API. This catches the most common error pattern (the LLM sends "JP" instead of "JPN") at the MCP layer with a clear error message, rather than letting it propagate as a cryptic API error:

function validateISO3(code: unknown, paramName: string): string {
  const upper = (code as string).toUpperCase();
  if (!ISO3_COUNTRY_CODES.has(upper)) {
    throw new McpError(ErrorCode.InvalidParams,
      `"${paramName}" value "${code}" is not a valid ISO 3166-1 alpha-3 country code.`);
  }
  return upper;
}

Key decisions and lessons learned

Tool descriptions are your most important code. The LLM reads them to decide when to invoke your tool. Vague descriptions mean the agent won't call your tool when it should. We explicitly state what each tool returns, what it covers (39,585 pairs, 15 languages), and when to use it versus alternatives. This isn't documentation -- it's prompt engineering.

stdout is sacred. In stdio transport, stdout carries MCP protocol messages. If you console.log() anything, you'll corrupt the protocol stream and crash the connection. All our logging goes to stderr via process.stderr.write(). This is the #1 mistake people make when building their first MCP server.

Free tier drives adoption. The quick_visa_check and get_coverage_stats tools work without an API key. This means anyone can npx orizn-visa-mcp and immediately test it. Zero friction. If they need full details, they add a key. But the first experience is instant.

Validate before you fetch. Catching "FR" vs "FRA" at the validation layer gives the agent a clear, actionable error ("not a valid ISO 3166-1 alpha-3 code") instead of a generic API 400. The agent can self-correct and retry with the right format.

Publishing and distribution

Building the server is half the work. Getting it in front of developers is the other half.

npm publish -- This enables npx orizn-visa-mcp, the fastest path from discovery to running server. Set the bin field in package.json and add the shebang (#!/usr/bin/env node) to your entry point.
MCP registries -- Submit to Smithery, mcp.so, and Glama. These are where developers browse for MCP servers. A smithery.yaml config file handles Smithery's hosted deployment.
README as marketing -- Your README is your landing page. Include a clear one-liner, a feature table, installation instructions for every major client (Claude Desktop, Cursor, VS Code), and example outputs. Most developers decide whether to try your server in 30 seconds of scanning the README.

Try it

The server is open source and ready to use:

GitHub: github.com/MattJeff/orizn-mcp-server
npm: npmjs.com/package/orizn-visa-mcp
Run it: npx orizn-visa-mcp
API docs: visa.orizn.app

If you're building an AI agent that touches travel, immigration, or international logistics, plug this in and your agent gets reliable visa data instead of hallucinated guesses. And if you're building your own MCP server -- steal the patterns. The protocol is simple, the SDK is solid, and the ecosystem is growing fast.