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

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

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)

{
  "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

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

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)

{
  "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

GET /traveldemand/routes/subscription

Parameters

This endpoint requires no parameters.

Example Request

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)

{
  "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

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

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)

{
  "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:

{
  "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:

{
  "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.