# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zytlyn.com/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.