Laminar Data API Model

Laminar Data aims to provide a unified, connected model of aviation data. To this end, the UML below model has been developed to let you visualise how data entities are represented and grouped in the system. This model maps to how the API calls are constructed. Hover over a node in the diagram to view additional information about what it represents, and click a node to jump straight to the relevant documentation.

Hello

Relation between the API and UML

Classes are resources in the API. Instances of a class can therefore be returned as responses to API calls. Fields within a class are the identifiers of an instance used in a URL path. Aggregations and compositions show steps between identifiers in a path. For example /v1/icao-prefix/{icao.prefix.letter}/firs/{icao.designator} navigates from the root of the API to an FIR via two associations.

Composition

Composition shows that the identity of the member of the composition is defined by its membership of the associated class. This means that tracing from the API root to the class then adding the identifier of the instance will return the instance of that object. For example, /v1/icao-prefix/{icao.prefix.letter}/firs/{icao.designator} will return the FIR with the given name within the given ICAO prefix.

You may notice that for any given class there is only one path from the API root to that class via composition relationships. This means that the URL to each resource is a single unique identifier. This guarantees that if two paths are different then they always refer to different resource. You can therefore use these paths to make identity comparisons.

Where the composition association is single cardinality no identifier is needed to retrieve the resource and no summary list is implied. For example /v1/aerodromes/{aerodrome.icao}/metar will return the METAR for the aerodrome in full.

Aggregation

Aggregation associations show that you can retrieve resources based on that association. These relations always return a collection of summaries of resources. Each summary will contain the identifier of the resource allowing you to navigate to the full representation of that resource via the identity URLs defined by the composition associations.

For example, /v1/icao-prefix/{icao.prefix.letter}/aerodromes will return a list of aerodrome summaries of all aerodromes in the ICAO prefix area.

The composition relations also imply that a summary list would be available but this will only be the case where practical. For example, /v1/airlines will return a list of all airlines but /v1/flights would return too large a response to be practical so will not be implemented. When a summary is implemented, a label is placed over the aggregation arrow.

Laminar Data API

This object represents the root of the Laminar API; that is, the endpoint accessible at https://api.laminardata.aero/v1/.

It follows that all objects will be descendants of this object, either directly or through intermediate containing objects.

ICAO Prefix

The International Civil Aviation Organisation issue four-letter designators for aerodromes and FIRs. The first letter of these designators refers to a particular region of the world, for example E is Europe and K is the USA. In the Laminar Data API, this grouping has been used in order to divide up the world into geographic areas of interest.

An ICAO prefix contains all the FIRs and aerodromes within it.

Relationships

  • Contains FIRs.
  • Associated with aerodromes, SIGMETs and regulations.

FIR

A Flight Information Region is a designated region of airspace. Each FIR is administered by a particular authority, who provides a flight information service within the FIR. Every portion of the globe is covered by a single FIR.

FIRs are identified by their ICAO-assigned four-letter designator, which is globally unique.

Relationships

  • Contained by an ICAO prefix.
  • Contains designated points and navaids.
  • Associated with NOTAMs, route segments, and airspaces.

Aerodrome

An aerodrome is a defined area on land or water intended to be used either wholly or in part for the arrival, departure, and surface movement of aircraft or helicopters.

Aerodromes in the Laminar API are identified by their ICAO-assigned four-letter designator, which is globally unique.

Relationships

  • Associated with an ICAO prefix.
  • Contains a METAR and TAF.

Airline

An airline in the Laminar API is defined as a commercial carrier which operates a number of flights.

Airlines in the Laminar API are identified by their ICAO-assigned three-letter designator, which is globally unique.

Relationships

  • Associated with flights.

Flight

A flight is defined as a journey of an aircraft from one origin aerodrome to one destination aerodrome at a particular point in time. For example, if a flight ran between Glasgow and Heathrow once per day for a year, then this would result in 365 unique flights in the Laminar API.

Flights in the Laminar API are identified by a Globally Unique Flight Identifier, which is a UUID that is unique for an individual flight instance. This identifier does not have any meaning outside of the Laminar API.

Relationships

  • Associated with a tile.
  • Associated with an airline.

METAR

A Meteorological Aerodrome Record is a weather report of current meteorological conditions issued by an aerodrome at a defined interval (usually every 30 minutes).

This API also captures SPECIs under the same URL, which is a similar report containing the same content as a METAR but was issued outside of the usual METAR interval.

Only the latest METAR is provided for a particular aerodrome in Laminar; there is no concept of historical METARs.

Relationships

  • Contained by an aerodrome.

TAF

A Terminal Aerodrome Forecast is a report of expected meteorological conditions over a given period of time (usually 24 hours).

Only the latest TAF is provided for a particular aerodrome in Laminar; there is no concept of historical TAFs.

Relationships

  • Contained by an aerodrome.

SIGMET

A Significant meteorological Event is an advisory of significantly hazardous weather affecting a particular area of the world. SIGMETs are issued on an ad-hoc basis as conditions warrant.

SIGMETs are identified in Laminar by a UUID, generated when the SIGMET is first received and maintained for any updates that are made. SIGMETs are grouped by the ICAO prefix they affect.

Relationships

  • Associated with an FIR.

Airspace

A defined three dimensional region of space relevant to air traffic.

Airspaces are identified by a globally unique designator. Each airspace is geometrically contained within an FIR, however as the designator is globally unique the composition relationship has been set as the API root to allow an airspace to be accessed without the need to know the FIR it is contained within.

Relationships

  • Associated with an FIR.

Designated Point

A specific geographical point on the globe that has been assigned a designator (typically a 5 letter code), for use in flight planning, routes, and navigation.

The designator is only unique within the FIR that contains it. Therefore, the identity of a designated point is determined by the combination of its designator and the containing FIR.

Relationships

  • Contained by an FIR.

Navaid

A Navigation Aid is one or more physical pieces of ground equipment at a particular location which provide guidance information to an aircraft.

Navaids are assigned typically a three-letter designator, however this is only unique within the FIR that contains it. Therefore the identity of a navaid is determined by the combination of this designator and the containing FIR.

Relationships

  • Contained by an FIR.

Route Segment

A single segment of a route describing the path between two waypoints. For example, the route CORAL, APPLE, VEGAT would have two route segments: CORAL to APPLE, and APPLE to VEGAT.

Route segments have no natural designator and are therefore accessible by a UUID at the root level.

Relationships

  • Contained by an FIR.

Tile

The Laminar API divides the world into a grid in order to allow entities to be selected easily by a rectangular geographic region.

Tiles are identified by their zoom level, their x-coordinate, and their y-coordinate (in that order). Currently only zoom level 3 is supported in the Laminar API.

Relationships

  • Associated with flights.

NOTAM

A Notice to Airmen is a notice to advise pilots of circumstances at a particular location or area that could affect the state or safety of a flight.

NOTAMs are identified by a universally unique identifier, generated when it is received. A NOTAM which replaces another is assigned a different UUID, however a link is maintained between the two.

Relationships

  • Associated with an FIR.

Regulation

Regulations provide information on the available capacity of the European air traffic management network.

Regulations are identified by a universally unique identifier, generated when it is received. The regulations are split into two main categories, airspace and aerodrome regulations, depending on which air traffic volume is affected.

Relationships

  • Associated with an ICAO prefix.