Developer Documentation

LobbyFlight API

Integrate real-time flight data into your applications. Our API supports multi-display architecture - manage multiple displays with individual configurations.

RESTful API

Real-time Data

Secure & Reliable

Quick Start

Get API Key

API access is available on the Premium plan. Generate your API key in the portal.

Make Request

Include your API key in the Authorization header and make requests to our endpoints.

Get Data

Receive JSON responses with flight data, configurations, and weather information.

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header:

X-API-Key: lf_live_xxxxxxxxxxxx

API keys are available exclusively for Premium plan subscribers.Upgrade to Premium

Code Examples

# List all displays
curl -X GET "https://lobbyflight.com/api/v1/displays" \
  -H "X-API-Key: lf_live_your_api_key_here"

# Get flights for a specific display
curl -X GET "https://lobbyflight.com/api/v1/displays/{displayId}/flights" \
  -H "X-API-Key: lf_live_your_api_key_here"

# Get flights by airport code
curl -X GET "https://lobbyflight.com/api/v1/flights/VIE?type=departures" \
  -H "X-API-Key: lf_live_your_api_key_here"

API Endpoints

All endpoints use the base URL https://lobbyflight.com/api/v1

Displays

GET/api/v1/displays

List all displays for your hotel

Response

{
  "success": true,
  "displays": [
    {
      "id": "d1a2b3c4-5678-90ab-cdef-1234567890ab",
      "name": "Lobby Main Display",
      "hotelName": "Grand Hotel Vienna",
      "displayMode": "tv",
      "airportCode": "VIE",
      "resolvedAirportCode": "VIE",
      "airportCodes": ["VIE"],
      "effectiveTimezone": "Europe/Vienna",
      "flightType": "departures",
      "isActive": true,
      "lastSeenAt": "2024-01-15T09:55:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "boardPrefs": {
        "styleId": "klassisch",
        "type.density": "normal",
        "list.columns.gate": "on",
        "screen.pixelShift": true
      }
    }
  ]
}

Field notes

airportCodesNew	Airports the display effectively shows: the display's own list, otherwise the hotel's.
effectiveTimezoneNew	IANA time zone of the board's clock and flight times. Honours the display's "use airport time zone" and "local time" settings; null means the screen uses its device's local time.
boardPrefsNew	Read-only. The board design settings exactly as the screen uses them, resolved and limited to your plan; same object as on the detail endpoint (see "Board design settings" below). Example abridged.
resolvedAirportCodeNew	The display's primary airport, resolved as airportCode → airportCodes[0] → hotel airport (the airport the board shows). null when none is configured.
airportCodeDeprecated	The per-display airport column as stored, unchanged; it is often null (the portal stores airports in airportCodes). Use resolvedAirportCode or airportCodes instead. Still returned for existing integrations.

GET/api/v1/displays/{displayId}

Get detailed configuration for a specific display

Parameters

Name	Type	Required	Description
displayId	string	Yes	Unique display identifier (UUID)

Response

{
  "success": true,
  "display": {
    "id": "d1a2b3c4-5678-90ab-cdef-1234567890ab",
    "name": "Lobby Main Display",
    "hotelName": "Grand Hotel Vienna",
    "displayMode": "tv",
    "airportCode": "VIE",
    "resolvedAirportCode": "VIE",
    "airportCodes": ["VIE"],
    "flightType": "departures",
    "logoUrl": "https://...",
    "theme": {
      "primary": "#1E40AF",
      "secondary": "#3B82F6"
    },
    "refreshInterval": 300,
    "timeFormat": "24h",
    "timezone": null,
    "effectiveTimezone": "Europe/Vienna",
    "useAirportTimezone": true,
    "showWeather": true,
    "languages": ["de", "en"],
    "rotationEnabled": true,
    "rotationInterval": 30,
    "flightDisplayDuration": 60,
    "isActive": true,
    "boardPrefs": {
      "styleId": "klassisch",
      "header.clockSeconds": true,
      "list.columns.terminal": true,
      "list.columns.gate": "on",
      "list.destination": "airport",
      "status.style": "pill",
      "time.countdownMaxMinutes": null,
      "type.density": "normal",
      "type.numerals": "mono",
      "motion.listMode": "page",
      "lang.mode": "rotate",
      "screen.pixelShift": true,
      "screen.night.enabled": false,
      "extras.leaveBy": false
    }
  }
}

Field notes

airportCodesNew	Airports the display effectively shows: the display's own list, otherwise the hotel's.
effectiveTimezoneNew	IANA time zone of the board's clock and flight times. With useAirportTimezone the primary airport's zone; otherwise null (the screen's device clock, the default) or, when the display's time.localZone setting is "hotel", the hotel's own zone.
useAirportTimezoneNew	Whether the board shows airport time (true) or local time (false: the device clock, or the hotel's zone with boardPrefs time.localZone = "hotel").
resolvedAirportCodeNew	The display's primary airport, resolved as airportCode → airportCodes[0] → hotel airport (the airport the board shows). null when none is configured.
airportCodeDeprecated	The per-display airport column as stored, unchanged; it is often null (the portal stores airports in airportCodes). Use resolvedAirportCode or airportCodes instead. Still returned for existing integrations.
timezoneDeprecated	Legacy per-display time zone column, usually null. Use effectiveTimezone instead. Still returned for existing integrations.
rotationIntervalDeprecated	No longer used by the board. The time per departures/arrivals phase is flightDisplayDuration (seconds). Still returned for existing integrations.
boardPrefsNew	Read-only. Every board design setting as the screen uses it: defaults, then group defaults, property and display settings (a group lock wins), limited to your plan. Always contains every key; the example is abridged. See "Board design settings" below.

GET/api/v1/displays/{displayId}/flights

Get flights for a specific display based on its configured airport (the display's primary airport, falling back to your hotel's primary airport). Returns 400 NO_AIRPORT only if neither is set.

Parameters

Name	Type	Required	Description
displayId	string	Yes	Unique display identifier (UUID)
type	string	No	Override flight type: "departures" or "arrivals"

Response

{
  "success": true,
  "data": [
    {
      "flight": { "iata": "OS501", "number": "501" },
      "airline": { "name": "Austrian Airlines", "iata": "OS" },
      "departure": {
        "scheduled": "2024-01-15T10:00:00Z",
        "terminal": "3",
        "gate": "F10"
      },
      "arrival": {
        "airport": "Frankfurt",
        "iata": "FRA"
      },
      "flightStatus": "scheduled"
    }
  ],
  "airport": "VIE",
  "flightType": "departures",
  "displayId": "d1a2b3c4-...",
  "displayName": "Lobby Main Display",
  "cachedAt": "2024-01-15T09:55:00Z"
}

GET/api/v1/displays/{displayId}/analytics

Get analytics data for a specific display

Parameters

Name	Type	Required	Description
displayId	string	Yes	Unique display identifier (UUID)
startDate	string	No	Start date (ISO format, default: 7 days ago)
endDate	string	No	End date (ISO format, default: today)

Response

{
  "success": true,
  "analytics": {
    "displayId": "d1a2b3c4-...",
    "displayName": "Lobby Main Display",
    "displayMode": "tv",
    "period": {
      "startDate": "2024-01-08",
      "endDate": "2024-01-15"
    },
    "metrics": {
      "totalViews": 1234,
      "totalSearches": 89,
      "totalInteractions": 256,
      "uptimePercentage": 99.2,
      "errorCount": 3
    },
    "dailyStats": [...]
  }
}

Flights

GET/api/v1/flights/{airportCode}

Get flights by airport code (must be in your authorized airport list)

Parameters

Name	Type	Required	Description
airportCode	string	Yes	IATA airport code (e.g., VIE, MUC)
type	string	No	Filter by "departures" (default) or "arrivals"

Response

{
  "success": true,
  "data": [
    {
      "flight": { "iata": "OS501", "number": "501" },
      "airline": { "name": "Austrian Airlines", "iata": "OS" },
      "departure": {
        "scheduled": "2024-01-15T10:00:00Z",
        "terminal": "3",
        "gate": "F10"
      },
      "arrival": {
        "airport": "Frankfurt",
        "iata": "FRA"
      },
      "flightStatus": "scheduled"
    }
  ],
  "airport": "VIE",
  "type": "departures",
  "cachedAt": "2024-01-15T09:55:00Z"
}

Weather

GET/api/v1/weather/{airportCode}

Get current weather for an airport location

Parameters

Name	Type	Required	Description
airportCode	string	Yes	IATA airport code (e.g., VIE, MUC)
units	string	No	"metric" (default) or "imperial"

Response

{
  "success": true,
  "data": {
    "temp": 12,
    "feelsLike": 10,
    "description": "partly cloudy",
    "icon": "02d",
    "humidity": 65,
    "windSpeed": 15,
    "forecast": [
      {
        "date": "2024-01-16",
        "tempMax": 14,
        "tempMin": 8,
        "description": "sunny",
        "icon": "01d"
      }
    ]
  },
  "airport": "VIE",
  "units": "metric",
  "cachedAt": "2024-01-15T09:55:00Z"
}

Analytics

GET/api/v1/analytics

Get analytics overview for all displays of your hotel

Parameters

Name	Type	Required	Description
startDate	string	No	Start date (ISO format, default: 7 days ago)
endDate	string	No	End date (ISO format, default: today)

Response

{
  "success": true,
  "analytics": {
    "hotelId": "h1a2b3c4-...",
    "period": {
      "startDate": "2024-01-08",
      "endDate": "2024-01-15"
    },
    "summary": {
      "totalDisplays": 3,
      "activeDisplays": 3,
      "totalViews": 4521,
      "totalSearches": 312,
      "totalInteractions": 876,
      "averageUptime": 98.7
    },
    "displays": [
      {
        "displayId": "d1a2b3c4-...",
        "displayName": "Lobby Main Display",
        "displayMode": "tv",
        "metrics": {...}
      }
    ]
  }
}

Board design settings (boardPrefs)

Both display endpoints return boardPrefs: a flat object of dot-separated keys such as "header.clockSeconds". It is read-only and already resolved: defaults, then your group's defaults, the property and the display (a locked group default wins), limited to what your plan includes. It is the same object the screen receives, so a setting your plan does not cover shows its default value.

Every key is always present. Settings are changed in the portal (Displays → a display → Design), not through the API. New keys may be added over time; treat unknown keys as informational and do not rely on a fixed key list.

Key prefix	What it covers
styleId	The board style the settings started from (e.g. "klassisch", "look-ocean-blue"), or null.
header.*	Title, subtitle, clock (seconds, analog, world clocks), date format, logo size, accent line, header variant.
weather.*	Weather details, forecast and style (panel, inline, icon, 3-day strip).
list.*	Columns on/off (terminal, gate, airline line, baggage belt), destination format, custom column labels, "next 3 flights" hero.
status.*	Status style, on-time wording, delay display, status icons and colour scheme.
time.*	Countdown and its limit, past flights (dim or hide), time window, hiding cancelled flights.
type.*	Density, font, numerals, uppercase headings, row style, airline logo style.
background.* / theme.*	Background (theme, gradient, pattern, image, dimming) and seasonal themes with end date.
motion.*	Scrolling or paging, seconds and rows per page, transitions, row fade-in.
lang.*	Rotating or bilingual labels, second language, stable layout for right-to-left languages.
footer.*	Flight count, "last updated" line, custom footer text, footer visibility.
filter.*	Airline include/exclude list, highlighted airlines, terminal filter.
screen.*	Screen care: pixel shift, safe area, rotation, night mode (from, to, mode).
extras.*	Leave-hotel-by column, QR code (target, URL, label), announcement ticker (text, severity, end time).

Rate Limits

Request Limits

100 requests per minute
10,000 requests per day
Burst limit: 20 requests per second

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 95

X-RateLimit-Reset: 1705312800

Error Codes

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
403	Forbidden	API access not included in your plan
404	Not Found	Hotel or resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Ready to Start Building?

Get your API key today and start integrating LobbyFlight data into your applications.

View Pricing Contact Sales