# ZippyTravel API Documentation (FINAL LOCKED PLAN)

**Base Endpoint**: `/api/explore`  
**Detail Endpoint**: `/api/package-detail`  
**Method**: `GET`  
**Format**: `JSON`

---

## 1. Package Types & Definitions

### 📦 Single Package
- **Definition**: A package assigned to exactly **one** region.
- **Data Structure**: `region_ids` contains only one ID.
- **Matching**: Matches if `country_id` matches AND (if provided) `region_id` matches.
- **Filters**: **STRICTLY ENFORCED**. All filters (price, nights, rating) apply.
- **Placement**: Returned in the `packages` key.
- **Pagination**: Paginated (15 per page).

### 🔥 Combo Package
- **Definition**: A package assigned to **multiple** regions.
- **Data Structure**: `region_ids` contains more than one ID.
- **Matching**: Matches if `country_id` matches AND **ANY ONE** of its `region_ids` matches the request region(s).
- **Filters**: **IGNORED**. Combo packages are returned as-is based on location match only.
- **Placement**: Returned in the `combo_packages` key.
- **Pagination**: Not paginated (all matches returned).

---

## 2. Request Parameters (/api/explore)

| Key | Type | Applies To | Description |
| :--- | :--- | :--- | :--- |
| `country_id` / `country_slug` | string | Both | Logic: Packages must belong to this country. |
| `city_id` / `city_slug` | string | Both | Logic: Match region(s). |
| `price_tag` / `min_price` / `max_price` | number | Single Only | Price filtering. |
| `nights` | int | Single Only | Filter by duration. |
| `star_rating` | int | Single Only | Filter by rating. |
| `include_packages` | bool | - | Force package retrieval on generic pages. |

---

## 3. Response Structure

```json
{
    "status": 1,
    "message": "Data fetched successfully",
    "page_variant": "...",
    "data": {
        "continents": [...],
        "countries": [...],
        "cities": [...],
        "packages": { 
            "current_page": 1,
            "data": [ 
                // ONLY Single Region Packages
                // Filtered by price, nights, stars, etc.
            ],
            "total": ...
        },
        "combo_packages": [
            // ONLY Multi-Region Packages
            // Filters IGNORED (matches on location only)
        ]
    }
}
```

---

## 4. Visibility Rules (Locked)
- **Wait Guarantee**: Combo packages will **NEVER** appear in the `packages` list.
- **Single Only**: The `packages` key is reserved exclusively for single-region listings.
- **Location Truth**: 
    - On a **Country Page**: Shows all single packages (filtered) and all combo packages for that country.
    - On a **Region Page**: Shows single packages for that region (filtered) and combo packages that include that region.

---

## 5. Sorting
- All listings (Single and Combo) are sorted by **Price (Low to High)**.
- For Single Packages, pagination is applied after filtering and sorting.