# Introduction

## API Endpoints Reference

This section provides comprehensive documentation for all Travel Demand API endpoints. All endpoints require authentication via the `x-api-key` header.

### Base URL

```
https://api.zytlyn.com
```

### Endpoint Categories

The API is organized into four main categories:

1. **Route Prediction** - Get demand predictions for specific routes
2. **Route Historical Data** - Access historical demand data
3. **Route Subscription** - Manage and view your subscriptions
4. **Route Lead Time Prediction** - Analyze lead time patterns

***

### Route Prediction

> Endpoints for demand predictions between specific origin-destination pairs.

#### Get Route Demand Prediction

Retrieves travel demand predictions for a specified route, product dimension, and time resolution.

**Endpoint**

```http
GET /traveldemand/{product_dimension}/routes/prediction/{time_resolution}/{origin}/{destination}
```

**Parameters**

| Parameter           | Type   | Required | Description                             |
| ------------------- | ------ | -------- | --------------------------------------- |
| `product_dimension` | string | ✅        | The product dimension for predictions   |
| `time_resolution`   | string | ✅        | Temporal granularity of prediction data |
| `origin`            | string | ✅        | 3-letter IATA code for origin city      |
| `destination`       | string | ✅        | 3-letter IATA code for destination city |

**Parameter Values**

* **product\_dimension**: `search_date`, `travel_date`, `lead_time`
* **time\_resolution**: `monthly`, `weekly`, `daily`
* **origin/destination**: 3-letter IATA codes (e.g., `LON`, `BCN`, `NYC`)

**Example Request**

```bash
curl -X GET \
  'https://api.zytlyn.com/traveldemand/search_date/routes/prediction/monthly/LON/BCN' \
  -H 'accept: application/json' \
  -H 'x-api-key: your-api-key-here'
```

**Success Response (200)**

```json
{
  "query": {
    "product_dimension": "search_date",
    "time_resolution": "monthly"
  },
  "predictions": [
    {
      "target": {
        "origin": "LON",
        "destination": "BCN"
      },
      "period": {
        "start": "2025-01-01",
        "end": "2025-01-31"
      },
      "strategic_insights": {
        "zytlyn_demand": 15420,
        "zytlyn_realised_demand_passengers": 12840,
        "year_over_2019_growth": 15,
        "year_over_year_growth": 8
      },
      "forecast_uncertainties": {
        "zytlyn_demand": 1200,
        "zytlyn_realised_demand_passengers": 980
      },
      "created_on": "2025-07-24T10:08:08.751Z"
    }
  ]
}
```

**Error Responses**

* **401 Unauthorized**: Invalid or missing API key
* **422 Validation Error**: Invalid parameters

***

### Route Historical Data

> Endpoints for accessing historical demand data between specific origin-destination pairs.

#### Get Route Demand History

Retrieves historical data for a specific flight route based on product dimension and time resolution.

**Endpoint**

```http
GET /traveldemand/{product_dimension}/routes/history/{time_resolution}/{origin}/{destination}
```

**Parameters**

| Parameter           | Type   | Required | Description                             |
| ------------------- | ------ | -------- | --------------------------------------- |
| `product_dimension` | string | ✅        | The type of date for historical data    |
| `time_resolution`   | string | ✅        | Granularity of historical data          |
| `origin`            | string | ✅        | 3-letter IATA code for origin city      |
| `destination`       | string | ✅        | 3-letter IATA code for destination city |

**Parameter Values**

* **product\_dimension**: `search_date`, `travel_date`, `lead_time`
* **time\_resolution**: `monthly`, `weekly`, `daily`
* **origin/destination**: 3-letter IATA codes

**Example Request**

```bash
curl -X GET \
  'https://api.zytlyn.com/traveldemand/travel_date/routes/history/weekly/LON/BCN' \
  -H 'accept: application/json' \
  -H 'x-api-key: your-api-key-here'
```

**Success Response (200)**

```json
{
  "query": {
    "product_dimension": "travel_date",
    "time_resolution": "weekly"
  },
  "history": [
    {
      "target": {
        "origin": "LON",
        "destination": "BCN"
      },
      "period": {
        "start": "2024-07-15",
        "end": "2024-07-21"
      },
      "strategic_insights": {
        "zytlyn_demand": 3250,
        "year_over_2019_growth": 12,
        "year_over_year_growth": 5,
        "demand_to_realisation_ratio": 1.34,
        "realised_demand_length_of_stay": {
          "0-1": 0.13,
          "1-2": 3.16,
          "2-3": 8.13,
          "3-4": 15.45,
          "4-6": 32.72,
          "6-10": 20.42,
          "10-20": 9.42,
          "20-30": 2.68,
          "30+": 7.9
        },
        "realised_demand_percentage_one_way": 45,
        "realised_demand_percentage_round_trip": 55,
        "demand_percentage_one_way": 48,
        "demand_percentage_round_trip": 52,
        "zytlyn_realised_demand": 2420,
        "zytlyn_realised_demand_passengers": 2680,
        "passenger_per_booking_ratio": 1.11,
        "cabin_class_distribution": {
          "economy": 87.5,
          "premium_economy": 8.2,
          "business": 3.8,
          "first": 0.5
        },
        "realised_demand_multi_city": 125,
        "passenger_per_booking_ratio_multi_city": 1.25
      },
      "created_on": "2024-07-28T10:08:08.753Z"
    }
  ]
}
```

***

### Route Subscription

> Endpoints to access the list of routes to which you are subscribed.

#### Get Route Subscriptions

Retrieves all subscription configurations related to route-based predictions.

**Endpoint**

```http
GET /traveldemand/routes/subscription
```

**Parameters**

This endpoint requires no parameters.

**Example Request**

```bash
curl -X GET \
  'https://api.zytlyn.com/traveldemand/routes/subscription' \
  -H 'accept: application/json' \
  -H 'x-api-key: your-api-key-here'
```

**Success Response (200)**

```json
{
  "subscription": [
    {
      "product_dimension": "search_date",
      "time_resolution": "monthly",
      "georesolution": "route", 
      "historical_data_range": 24,
      "prediction_horizon": 12,
      "targets": [
        {
          "origin": "LON",
          "destination": "BCN"
        },
        {
          "origin": "LON", 
          "destination": "MAD"
        },
        {
          "origin": "PAR",
          "destination": "ROM"
        }
      ]
    },
    {
      "product_dimension": "travel_date",
      "time_resolution": "weekly",
      "georesolution": "route",
      "historical_data_range": 12,
      "prediction_horizon": 12,
      "targets": [
        {
          "origin": "NYC",
          "destination": "LAX"
        }
      ]
    }
  ]
}
```

**Subscription Fields**

| Field                   | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `product_dimension`     | The product dimension for this subscription      |
| `time_resolution`       | Time granularity available                       |
| `georesolution`         | Geographic resolution (always "route")           |
| `historical_data_range` | Months of historical data available              |
| `prediction_horizon`    | Months of predictions available                  |
| `targets`               | Array of origin-destination pairs you can access |

***

### Route Lead Time Prediction

> Endpoints for lead time demand predictions between specific origin-destination pairs.

#### Get Route Lead Time Demand Prediction

Retrieves travel demand lead time predictions for a specified route and time resolution.

**Endpoint**

```http
GET /traveldemand/lead_time/routes/prediction/{time_resolution}/{origin}/{destination}
```

**Parameters**

| Parameter         | Type   | Required | Description                             |
| ----------------- | ------ | -------- | --------------------------------------- |
| `time_resolution` | string | ✅        | Temporal granularity of prediction data |
| `origin`          | string | ✅        | 3-letter IATA code for origin city      |
| `destination`     | string | ✅        | 3-letter IATA code for destination city |

**Parameter Values**

* **time\_resolution**: `monthly`, `weekly`, `daily`
* **origin/destination**: 3-letter IATA codes

**Example Request**

```bash
curl -X GET \
  'https://api.zytlyn.com/traveldemand/lead_time/routes/prediction/weekly/LON/BCN' \
  -H 'accept: application/json' \
  -H 'x-api-key: your-api-key-here'
```

**Success Response (200)**

```json
{
  "query": {
    "product_dimension": "lead_time",
    "time_resolution": "weekly"
  },
  "predictions": [
    {
      "target": {
        "origin": "LON",
        "destination": "BCN"
      },
      "period": {
        "start": "2025-08-01",
        "end": "2025-08-07"
      },
      "zytlyn_demand": {
        "lead_time": {
          "0_1": 0.0445,
          "1_2": 0.0897,
          "2_3": 0.0803,
          "3_4": 0.0679,
          "4_5": 0.0651,
          "5_6": 0.0637,
          "6_7": 0.0557,
          "7_14": 0.1823,
          "14_21": 0.1456,
          "21_30": 0.1187,
          "30_60": 0.1523,
          "60_90": 0.0892,
          "90+": 0.0449
        }
      },
      "created_on": "2025-07-24T10:08:08.764Z"
    }
  ]
}
```

**Lead Time Buckets**

Lead time data is provided in specific buckets representing days before travel:

| Bucket  | Description                       |
| ------- | --------------------------------- |
| `0_1`   | Searches 0-1 days before travel   |
| `1_2`   | Searches 1-2 days before travel   |
| `2_3`   | Searches 2-3 days before travel   |
| `3_4`   | Searches 3-4 days before travel   |
| `4_5`   | Searches 4-5 days before travel   |
| `5_6`   | Searches 5-6 days before travel   |
| `6_7`   | Searches 6-7 days before travel   |
| `7_14`  | Searches 7-14 days before travel  |
| `14_21` | Searches 14-21 days before travel |
| `21_30` | Searches 21-30 days before travel |
| `30_60` | Searches 30-60 days before travel |
| `60_90` | Searches 60-90 days before travel |
| `90+`   | Searches 90+ days before travel   |

***

### Common Error Responses

#### 400 Bad Request

When trying to get data with a subscription that doesn't allow it, you'll receive a `400 Bad Request` response with a detailed message:

```json
{
  "detail":"We are not able to provide data for AMM to BCN with search_date and weekly, please check your subscription"
  }
```

**Common causes:**

* Trying to get data with a subscription that doesn't allow it

#### 422 Unprocessable Entity

When the request is malformed, you'll receive a `422 Unprocessable Entity` response with a detailed message:

```json
{
  "detail":
  [{
      "type":"string_pattern_mismatch",
      "loc":["path","destination"],
      "msg":"String should match pattern '[A-Z]{3}'",
      "input":"bcn",
      "ctx":{"pattern":"[A-Z]{3}"},
      "url":"https://errors.pydantic.dev/2.11/v/string_pattern_mismatch"
    }]
  }
```

**Common causes:**

* Invalid or malformed request
* Missing required parameters
* Invalid parameter values (e.g. invalid IATA code)

### SDKs and Tools

#### cURL Examples

All examples in this documentation use cURL for simplicity. Replace `your-api-key-here` with your actual API key.

#### Testing

Use the subscription endpoint to test your API access and view available routes before making prediction or historical data requests.