V
Visa Requirements
# 🌍 Travel Buddy AI – Visa Requirements API
Most up-to-date visa requirements with structured rule breakdowns, color-coded map visualization, and customizable passport ranking.
Supports **200 passports** and **211 destinations**, updated daily.
Ideal for **travel apps, booking engines, and immigration platforms**.
Flexible plans available, including a **free tier**.
---
## 🔑 Authentication
All requests require the following headers:
```bash
"X-Api-Key: YOUR_API_KEY"
````
---
## 🚀 API Overview
### Version 2 (Recommended)
* **POST `/v2/visa/check`** – Structured visa policy payload with full rule breakdown (primary, secondary, registration, exception).
* **POST `/v2/visa/map`** – Returns grouped country codes by visa color category (e.g., `{"green":"CA,US"}`).
* **POST `/v2/passport/rank/custom`** – Generates custom passport rankings using user-defined category weights.
* **GET `/v2/health`** – Versioned health probe.
### Version 1 (Legacy)
* **POST `/v1/visa/check`** – Backward-compatible version for older clients.
* **POST `/v1/visa/map`** – Returns color-coded map data for a passport.
* **GET `/v1/health`** – Basic health check.
* **POST `/` (legacy root)** – Auto-routes based on the `request` body parameter for backward compatibility.
---
## 📌 Example: Visa Check (v2)
### Endpoint
**POST** `/v2/visa/check`
The endpoint provides a detailed breakdown of **visa and entry requirements** for one passport–destination pair.
It returns structured data for:
* **Passport & destination metadata** – names, continent, capital, currency, population, area, exchange info, etc.
* **Mandatory registration** – pre-arrival or online forms (e.g., “e-Arrival”).
* **Visa rules** – includes both primary and secondary policies (e.g., visa-free, visa on arrival, eVisa, eTA).
* **Exception rules** – overrides that apply under specific conditions (e.g., travelers holding a U.S. visa).
### Request
```bash
curl -X POST https://iisbh.jojapi.net/v2/visa/check \
-H "Content-Type: application/json" \
-H "X-JoJAPI-Key: ${JoJ-API-Key}" \
-d '{"passport":"CN","destination":"ID"}'
```
### Example Response
```json
{
"data": {
"passport": { "code": "CN", "name": "China","currency_code": "CNY" },
"destination": {
"code": "ID", "name": "Indonesia", "continent": "Asia", "capital": "Jakarta",
"currency_code": "IDR", "currency": "Indonesian Rupiah", "exchange": "0.000425",
"passport_validity": "3 months beyond the period of stay",
"phone_code": "+62", "timezone": "+08:00", "population": 277329163,
"area_km2": 1916907, "embassy_url": "https://www.embassypages.com/china#titlePlaceholder2"
},
"mandatory_registration": {
"name": "e-Arrival", "color": "yellow",
"link": "https://link.travel-buddy.ai/?link=76E321T3"
},
"visa_rules": {
"primary_rule": { "name": "Visa on arrival", "duration": "30 days", "color": "blue" },
"secondary_rule": {
"name": "eVisa", "duration": "30 days", "color": "blue",
"link": "https://link.travel-buddy.ai/?link=76E323T2"
}
}
},
"meta": { "version": "2.0", "language": "en", "generated_at": "2025-09-28T11:47:00+00:00" }
}
```
---
### How to Display Visa Rules
| # | Situation | Condition | Display | Duration Used | Color Used |
| --- | ------------------------- | --------------------------- | ---------------------------------- | ----------------------- | ------------------ |
| 1.1 | Only primary exists | No `secondary_rule` | **primary_rule – XXX days** | primary_rule.duration | primary_rule.color |
| 1.2 | Both exist with durations | Both durations present | **primary / secondary – XXX days** | primary_rule.duration | primary_rule.color |
| 1.3 | Primary has no duration | Only secondary has duration | **primary / secondary – XXX days** | secondary_rule.duration | primary_rule.color |
#### 🟨 `exception_rule`
Exceptions override the main visa rule when specific traveler criteria apply (e.g., U.S. visa holders, group tours, or transit waivers).
Always show these as separate notes — do **not** alter the primary rule color.
#### 🟦 `mandatory_registration`
These are **free but mandatory** pre-arrival forms such as “e-Arrival” or “ED card.”
They are **not visas** and do not affect visa-free eligibility.
---
## 🗺️ Visa Color Map (v2)
### Endpoint
**POST** `/v2/visa/map`
Returns a color-coded overview of visa requirements for **all destinations** from the perspective of one passport.
Useful for creating visual maps or grouped country lists.
### Request
```bash
curl -X POST https://iisbh.jojapi.net/v2/visa/map \
-H "Content-Type: application/json" \
-H "X-JoJAPI-Key: ${JoJ-API-Key}" \
-d '{"passport":"CN"}'
```
### Example Response
```json
{
"data": {
"passport": "CN",
"colors": {
"red": "AD,AF,AR,AT,...,YE",
"green": "AE,AG,AL,AM,...,ZM",
"blue": "AI,BD,BF,BH,...,ZW",
"yellow": "CI,KE,KN,LK,SC"
}
},
"meta": { "version": "2.0", "language": "en", "generated_at": "2025-09-28T11:56:37+00:00" }
}
```
### Color Legend
| Color | Meaning |
| ------------- | ----------------------- |
| 🟩 **green** | Visa-free |
| 🟦 **blue** | Visa on arrival / eVisa |
| 🟨 **yellow** | eTA |
| 🟥 **red** | Visa required / Online Visa required |
---
## 🏅 Custom Passport Ranking (v2)
### Endpoint
**POST** `/v2/passport/rank/custom`
Calculates global passport rankings using **custom weights** that you define per visa category.
### Request
```bash
curl -X POST https://iisbh.jojapi.net/v2/passport/rank/custom \
-H "Content-Type: application/json" \
-H "X-JoJAPI-Key: ${JoJ-API-Key}" \
-d '{"weights":{"Visa-free":2,"Visa on arrival":1,"Visa required":0,"eVisa":1,"eTA":1,"Freedom of movement":3,"Not admitted":-1}}'
```
### Example Response
```json
{
"data": [
{
"rank": 1, "score": 218.0,
"passport": { "code": "SE", "name": "Sweden" },
"categories": { "Visa-free": 120, "Visa on arrival": 30, "Visa required": 10, "eVisa": 5, "eTA": 2, "Freedom of movement": 12, "Not admitted": 1 }
},
{
"rank": 2, "score": 205.0,
"passport": { "code": "BG", "name": "Bulgaria" },
"categories": { "Visa-free": 95, "Visa on arrival": 25, "Visa required": 15, "eVisa": 8, "eTA": 1, "Freedom of movement": 5, "Not admitted": 2 }
}
],
"meta": { "version": "2.0", "language": "en", "generated_at": "2024-09-25T22:47:00Z" }
}
```
### Parameters
| Field | Type | Description |
| --------------------- | ------ | ------------------------------------------------ |
| `weights` | object | Weight configuration for each visa rule category |
| `Visa-free` | number | Weight for visa-free destinations |
| `Visa on arrival` | number | Weight for visa on arrival destinations |
| `Visa required` | number | Weight for visa-required destinations |
| `eVisa` | number | Weight for eVisa destinations |
| `eTA` | number | Weight for eTA destinations |
| `Freedom of movement` | number | Weight for unrestricted movement |
| `Not admitted` | number | Negative or zero weight for denied destinations |
---
## ⚠️ Error Codes
| Code | Meaning |
|------|---------|
| 400 | Other domain errors (rare) |
| 401 | Authentication or quota issues |
| 404 | Resource not found (no visa/map data) |
| 405 | Wrong HTTP method (root helper route) |
| 422 | Validation problems – missing/invalid parameters, same passport/destination, bad JSON |
| 500 | Unhandled server error (logged internally) |
---
## 🆘 Support
📧 **Contact:** [info@travel-buddy.ai](mailto:info@travel-buddy.ai)
For technical questions, API key help, or data coverage inquiries.