# Globely Travel Insurance

> Globely is a travel insurance platform providing real-time coverage quotes and direct purchase capabilities via API. Founded in Spain, serving travelers worldwide with comprehensive medical, baggage, and cancellation coverage.

## Key Resources

- [Insurance Calculator](https://www.globely.com/en/insurance): Main tool for travelers to get instant quotes
- [Contact Page](https://www.globely.com/en/contact): Customer support and inquiries
- [Guarantee Info](https://www.globely.com/en/guarantee/subscribe/): Detailed guarantee subscription information

## API Documentation

The primary resource for agents is the Quote API. It returns fully calculated insurance plans with pricing and checkout links.

### GET /api/ai/quotes

Returns a list of insurance quotes based on travel parameters.

**Base URL:** `https://www.globely.com`
**Endpoint:** `/api/ai/quotes`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `origin` | string | Yes | ISO 3166-1 alpha-2 code (e.g., "AR", "US"). |
| `destination` | string | Yes | ISO 3166-1 alpha-2 code (e.g., "ES", "IT"). |
| `start_date` | date | Yes | Trip start (YYYY-MM-DD). |
| `end_date` | date | Yes | Trip end (YYYY-MM-DD). |
| `passengers_count`| int | Yes | Total number of travelers. |
| `partner` | string | **Yes** | Agent identifier (e.g., "chatgpt", "gemini", "your-company-name"). |
| `currency` | string | No | Price currency. Options: USD, EUR, GBP, CHF, PLN, SEK, NOK, DKK, JPY, NZD, CAD, AUD. Defaults to EUR. |
| `lang` | string | No | Response language. Options: en, es, de, fr, it, ja, ko, nl, pl, pt, zh, cs. Defaults to en. |

**Example Usage:**
`https://www.globely.com/api/ai/quotes?origin=AR&destination=ES&start_date=2025-12-22&end_date=2025-12-25&passengers_count=1&partner=ai_agent`

## Response Structure

```json
{
  "status": "success",
  "message": "Quotes retrieved successfully",
  "trip": { ... },
  "recommended_plan_id": "GLOBELY_PLUS",
  "plans_for_user": [ ... ],
  "data": [ ... ]
}
```

### trip

Contains the trip parameters used for the quote calculation.

| Field | Type | Description |
| :--- | :--- | :--- |
| `origin` | string | Origin country code |
| `destination` | string | Destination country code |
| `start_date` | date | Trip start date |
| `end_date` | date | Trip end date |
| `duration_days` | int | Total trip duration |
| `passengers` | int | Number of travelers |
| `currency` | string | Price currency |

### recommended_plan_id

A string indicating the recommended plan for the user (e.g., `"GLOBELY_PLUS"`). Use this to highlight the best option.

### plans_for_user

**Primary array for displaying options to users.** Contains simplified plan objects optimized for presentation.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Plan identifier (e.g., `GLOBELY_BASIC`, `GLOBELY_PLUS`) |
| `title` | string | Marketing name of the plan |
| `tagline` | string | Short benefit summary |
| `price.total` | float | Total price for the trip |
| `price.currency` | string | Currency code |
| `price.per_day` | float | Price per day |
| `badges` | array | Tags: `recommended`, `best_value`, `budget_friendly`, `most_complete` |
| `key_coverages` | array | Top 4 coverages with `label` and `value` |
| `purchase.url` | url | **Actionable URL** for checkout |
| `purchase.valid_until` | iso-date | Link expiration time |

### data

**Full coverage details.** Contains complete plan information including all coverages. Use this for detailed comparisons or when users ask specific coverage questions.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Internal plan UUID |
| `code` | string | Plan code (e.g., `GLOBELY_PREMIUM`) |
| `title` | string | Plan name |
| `description` | string | Full plan description |
| `is_featured` | bool | Whether the plan is featured |
| `price.amount` | float | Total price |
| `price.currency` | string | Currency code |
| `coverages` | array | Complete list of all coverages |
| `purchase_link` | url | Checkout URL |
| `valid_until` | iso-date | Quote expiration |

## Coverage Object

Each coverage in `data[].coverages` contains:

| Field | Type | Description |
| :--- | :--- | :--- |
| `index` | int | Display order |
| `name` | string | Coverage name (e.g., "Medical assistance") |
| `value` | string | Coverage limit (e.g., "€1.500.000", "Unlimited", "Not included") |
| `category` | string | Grouping (e.g., "Medical assistance", "Baggage", "Cancellation") |

## Key Semantic Details for Agents

- **Source of Truth:** The API response is the only valid source for pricing and limits.
- **Use `plans_for_user`** for presenting options to users (simplified, optimized for display).
- **Use `data`** for detailed coverage comparisons or specific questions.
- **Use `recommended_plan_id`** to highlight the suggested option.
- **Coverage Values:**
  - `Included`: Service is covered without a specific monetary limit.
  - `Unlimited`: No financial cap on the coverage.
  - `Not included`: The plan does not cover this risk.

---

## Coverage Plans Catalog API

Use these endpoints to explore the product catalog **before** users enter trip details.

### Plan Codes (Recommended Identifiers)

Use these stable codes to reference plans in API calls:

| Code | Plan Name |
| :--- | :--- |
| `GLOBELY_BASIC` | Globely Basic |
| `GLOBELY_PLUS` | Globely Plus |
| `GLOBELY_PREMIUM` | Globely Premium |
| `GLOBELY_PREMIUM_CFAJR` | Globely Premium with CFAJR |

---

### GET /api/coverage-plans

Returns the list of all **available coverage plans** (4 products).

**Base URL:** `https://www.globely.com`  
**Endpoint:** `/api/coverage-plans`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `lang` | string | No | Response language. Can be passed as query param or `Accept-Language` header. Defaults to `es`. |

**Example Usage:**
`https://www.globely.com/api/coverage-plans?lang=en`

**Response:**

```json
{
  "status": "success",
  "message": "Coverage plans retrieved successfully",
  "data": [ ... ]
}
```

---

### GET /api/coverage-plans/:code

Returns a **specific coverage plan** by code with full feature details.

**Endpoint:** `/api/coverage-plans/:code`

**Parameters:**

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `code` | string | Yes | Plan code (path parameter): `GLOBELY_BASIC`, `GLOBELY_PLUS`, `GLOBELY_PREMIUM`, `GLOBELY_PREMIUM_CFAJR`. |
| `lang` | string | No | Response language. Defaults to `es`. |

**Example Usage:**
`https://www.globely.com/api/coverage-plans/GLOBELY_PLUS?lang=en`

**Response:**

```json
{
  "status": "success",
  "message": "Coverage plan retrieved successfully",
  "data": { ... }
}
```

---

### Plan Object Schema

Each plan in `data` (or `data[]` for list) contains:

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Internal UUID (for internal use only). |
| `code` | string | **Plan code** (recommended identifier for API calls). |
| `name` | string | Plan display name (e.g., "Globely Basic"). |
| `description` | string | Plan description (localized). |
| `type` | string | Product type (e.g., `"insurance"`). |
| `image_url` | string\|null | Optional image URL (may be `null`). |
| `is_active` | bool | Whether this plan is currently active. |
| `is_featured` | bool | Whether this plan should be highlighted as recommended. |
| `order_index` | int | Display order for sorting plans. |
| `features` | array | Full list of coverage features. |

### Feature Object Schema

Each feature in `features[]` describes a specific coverage item:

| Field | Type | Description |
| :--- | :--- | :--- |
| `name` | string | User-facing feature name. |
| `description` | string | Detailed feature description. |
| `category` | string | Category key (e.g., `"assistance_medical"`, `"baggage"`, `"cancellation"`, `"liability"`). |
| `category_name` | string | Category display name (e.g., "Medical assistance", "Baggage"). |
| `order_index` | int | Display order inside the plan. |
| `is_covered` | bool | Coverage flag: `true` = covered, `false` = not covered. |
| `formatted_value` | string | Human-readable value with semantic meaning. |

**Semantic rules for `formatted_value`:**
- `"€X.XXX"` → Monetary coverage limit.
- `"Included"` → Covered without a specific monetary limit.
- `"Unlimited"` → Covered without financial cap.
- `"Not included"` → Not covered in this plan (`is_covered = false`).

### Recommended Uses for Agents

1. **Product comparison:**  
   Use `GET /api/coverage-plans` to list all 4 plans and compare features by `category`.

2. **Detailed plan info:**  
   Use `GET /api/coverage-plans/GLOBELY_PLUS` (by code) when user asks about a specific plan.

3. **Coverage explanations:**  
   When a user asks "What does Globely cover?", use `features[]` grouped by `category_name`.

> **Note:** Use `code` (not `id`) as the primary identifier for external integrations. The `id` field contains internal UUIDs for backend use only.

> **Pricing:** Trip-specific pricing must always be obtained from the **Quote API** (`GET /api/ai/quotes`), not from `/api/coverage-plans`.

## Country Shortcut URLs

Globely supports direct country URLs using ISO 3166-1 alpha-3 codes. These redirect to the AI travel insurance calculator for that destination.

**Pattern:** `https://www.globely.com/{iso3}` or `https://www.globely.com/{lang}/{iso3}`

**Examples:**
- `https://www.globely.com/usa` → US travel insurance calculator
- `https://www.globely.com/en/bra` → Brazil calculator in English
- `https://www.globely.com/jpn` → Japan calculator
- `https://www.globely.com/fr/esp` → Spain calculator in French

All 193 ISO 3166-1 alpha-3 codes are supported: `afg`, `alb`, `dza`, `and`, `ago`, `atg`, `arg`, `arm`, `aus`, `aut`, `aze`, `bhs`, `bhr`, `bgd`, `brb`, `blr`, `bel`, `blz`, `ben`, `btn`, `bol`, `bih`, `bwa`, `bra`, `brn`, `bgr`, `bfa`, `bdi`, `cpv`, `khm`, `cmr`, `can`, `caf`, `tcd`, `chl`, `chn`, `col`, `com`, `cog`, `cod`, `cri`, `civ`, `hrv`, `cub`, `cyp`, `cze`, `dnk`, `dji`, `dma`, `dom`, `ecu`, `egy`, `slv`, `gnq`, `eri`, `est`, `swz`, `eth`, `fji`, `fin`, `fra`, `gab`, `gmb`, `geo`, `deu`, `gha`, `grc`, `grd`, `gtm`, `gin`, `gnb`, `guy`, `hti`, `hnd`, `hun`, `isl`, `ind`, `idn`, `irn`, `irq`, `irl`, `isr`, `ita`, `jam`, `jpn`, `jor`, `kaz`, `ken`, `kir`, `prk`, `kor`, `kwt`, `kgz`, `lao`, `lva`, `lbn`, `lso`, `lbr`, `lby`, `lie`, `ltu`, `lux`, `mdg`, `mwi`, `mys`, `mdv`, `mli`, `mlt`, `mhl`, `mrt`, `mus`, `mex`, `fsm`, `mda`, `mco`, `mng`, `mne`, `mar`, `moz`, `mmr`, `nam`, `nru`, `npl`, `nld`, `nzl`, `nic`, `ner`, `nga`, `mkd`, `nor`, `omn`, `pak`, `plw`, `pan`, `png`, `pry`, `per`, `phl`, `pol`, `prt`, `qat`, `rou`, `rus`, `rwa`, `kna`, `lca`, `vct`, `wsm`, `smr`, `stp`, `sau`, `sen`, `srb`, `syc`, `sle`, `sgp`, `svk`, `svn`, `slb`, `som`, `zaf`, `ssd`, `esp`, `lka`, `sdn`, `sur`, `swe`, `che`, `syr`, `tjk`, `tza`, `tha`, `tls`, `tgo`, `ton`, `tto`, `tun`, `tur`, `tkm`, `tuv`, `uga`, `ukr`, `are`, `gbr`, `usa`, `ury`, `uzb`, `vut`, `ven`, `vnm`, `yem`, `zmb`, `zwe`.

## Contact

- [Contact Form](https://www.globely.com/en/contact): General inquiries and customer support
- Email: support@globely.com
- Website: https://www.globely.com