Service Description

 

 

asrv.aero

Flight Data Request Service

 

 

Until this note is removed the documentation is a work in progress, and revisions to the documentation will not be tracked.

 

Namespace: http://www.asrv.aero/webservices/1.0/flightdatarequestservice

 

Document revisions

Date
Description
Author
yyyy-mm-dd First complete version of the documentation
Ole Nymoen

 

 

 

1. Introduction

1.1. Overview

This service description defines one service with a set of operations to request flight oriented data. All flight related data elements are defined by the Airport Data Dictionary.

The service is primarily designed to meet the need of airport partners, but availability is the decision of the service provider.

There are a set of use cases that can be realized using the operations and data available, for example:

While the entity definitions stay the same, the data they contain related to one flight will change as time goes by. Initially only schedule data will be available. The data content should then steadily increase as the flight progresses, until it is as complete as the service provider can make it.

1.2. Implementation considerations

Any implementation of this service MUST use the WSDL and XSD files provided here: WSDL and XSDs

It is however up to the service provider which data elements to support, and how much data to return for requests spanning a long time period. To enable this most elements are optional. The reason for a service provider to not support all elements might be business rules related to data distribution, that it doesn't have the information, or that it wants to provide information in other (more restricted) ways.

Any service provider should make available documentation about the actual implementation, including:

    • the address of the service.
    • any limitations in the implementation.
    • recommended and allowed polling intervals.

 

1.3. Purpose of this service description

This service description has the following purpose:

      • Describe of service in enough detail for a service provider to implement it.
      • Describe the service so that a client (of this service) developer can use it.
      • Make available the WSDL and XSD files necessary to implement and use the service.
      • Make it possible for relevant people at airports, airlines, handlers and other aviation partners to understand the available functionality and then to decide if to implement/use it or not.

1.4. Intended readership

    • IT architects
    • Developers
    • Business architects
    • Interested parties in the aviation community

2. Service overview

The figure below shows the available operations on the FlightDataRequestService. The operations are described in detail in Service operations. All operations, apart from GetAlerts, have a basic and a full version. The "basic" version return a simplified data set and should be used where suitable to save processing power and bandwidth.

The operations can retrieve the following types of data:

  • Arriving flights
  • Departing flights
  • Turnarounds (arriving and departing flights connected)
  • Flight leg (departure and arrival)
  • Alerts

3. Service operations

3.1. GetBasicFlightDataInbound ( flightFilter: FlightFilter ) : GetBasicFlightDataInboundResponse

Returns basic data (a simplified data set) about the set of inbound flights that fit the FlightFilter.

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.2. GetFlightDataInbound( flightFilter: FlightFilter ) : GetFlightDataInboundResponse

Returns data about the set of inbound flights that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.3. GetBasicFlightDataOutbound( flightFilter: FlightFilter ) : GetBasicFlightDataOutboundResponse

Returns basic data (a simplified data set) about the set of outbound flights that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

 

3.4. GetFlightDataOutbound( flightFilter: FlightFilter ) : GetFlightDataOutboundResponse

Returns data about the set of outbound flights that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.5. GetBasicFlightLegData ( flightFilter: FlightFilter ) : GetBasicFlightLegDataResponse

Returns basic data (a simplified data set) about the set of flights legs that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.6. GetFlightLegData ( flightFilter: FlightFilter ) : GetFlightLegDataResponse

Returns data about the set of flights legs that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.7. GetBasicTurnaroundData ( flightFilter: FlightFilter ) : GetBasicTurnaroundDataResponse

Returns basic data (a simplified data set) about the set of turnarounds that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.8. GetTurnaroundData( flightFilter: FlightFilter ) : GetTurnaroundDataResponse

Returns data about the set of turnarounds that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

 

3.9. GetAlerts ( flightFilter: FlightFilter ) : GetAlertsResponse

Returns data about the set of alerts that fit the FlightFilter. 

Parameters:

filghtFilter: See definition of FlightFilter under Data entities.

Returns:

4. Data entities

4.1. Alert

flightLegIdentifier : FlightLegIdentifier

See definition of FlightLegIdentifier under Data entities.
alertStatusCode : AlertStatusCode

 
alertStatusText : AlertStatusText [0..1]  
active : boolean [0..1]  
alertLevel : AlertLevel [0..1]  

 

4.2. BasicFlightDataInbound
Term / Type Description
flightLegIdentifier : FlightLegIdentifier

See definition under Data entities
flightIsMultiLeg : boolean [0..1]

Flight leg is part of multileg Flight.

If this flight leg is part of a multi-leg flight then the list of airports that is the whole flight is listet in FlightRouteIATA.
flightRouteIATA : AirportIATA [0..*] List of airports a multi leg flight will land on before arriving at the destination. The list consists of AirportIATA codes. The list should contain all airports including first departure airport and last destination airport. The list should be ordered by the actual sequence the aircraft uses the airports.

codeshareData : CodeshareData

 See definition under Data entities.
flightServiceTypeIATA : FlightServiceTypeIATA [0..1] IATA SSIM Appendix C Service Types.
aircraftIATAType : AircraftIATAType [0..1] 3 character code as designated by International Air Transport Association (IATA) to uniquely designate Aircraft Type. Local (non-IATA) codes can be added as required as long as they are unique for aircraft types within the defined context.
Reference Document: IATA codeset 7800.
flightIsCancelled : boolean [0..1] Set to true if the flight operation is cancelled. For flight as with code share it's possible to only cancel the code shared flight.
flightDIIndicator: DIIndicator [0..1] Indicator showing what kind of flight (domestic, international, Schengen) this is. See also: AirportDIIndicator.
aircraftParkingPosition : AircraftParkingPosition [0..1] Where the aircraft is located. Code for a parking position, typically a stand, but can also be a hangar. Each airport has a set of AircraftParkingPositions. Each "AircraftParkingPosition" has one given type, defined by "AircraftParkingPositionType". Each position can have one or more usages, defined by (one or more) "AircraftParkingPositionUsage".
baggageClaimUnit : BaggageClaimUnit [0..1] Baggage belt (carousel) onto which passenger bags are loaded for collection by passengers on arrival flights.
There are a set of BaggageClaimUnits for each airport.
beltFirstBag : DateTimeUTC [0..1] UTC time the first passenger bag was loaded onto a baggage belt (carousel).
beltLastBag DateTimeUTC [0..1] UTC time the last passenger bag was loaded onto baggage a belt (carousel)
sibt : DateTimeUTC [0..1] Scheduled In-Block Time. The time that an aircraft is scheduled to arrive at its first parking position. Always UTC time.

eldt : DateTimeUTC [0..1]

 Estimated Landing Time. The estimated time that an aircraft will touchdown on the runway. (Equivalent to ATC ETA–Estimated Time of Arrival = landing). Always UTC time.
aldt : DateTimeUTC [0..1] Actual Landing Time. The time that an aircraft lands on a runway. (Equivalent to ATC ATA –Actual Time of Arrival = landing, ACARS=ON). Always UTC time.
eibt : DateTimeUTC [0..1] Estimated In-Block Time. The estimated time that an aircraft will arrive in-blocks. (Equivalent to Airline/Handler ETA –Estimated Time of Arrival). Always UTC time.

aibt : DateTimeUTC [0..1]

 Actual In-Block Time. The time that an aircraft arrives in-blocks. (Equivalent to Airline/Handler ATA –Actual Time of Arrival, ACARS = IN). Always UTC time.
linkedDeparture : FlightLegIdentifier [0..1] Something that links an departing flight (leg) to an arriving flight leg. Will typically contain some key information.

4.2.1. Elements that might be added

remark_1 (optional) Description: This field holds public remark for arrival/departure.

remark­_2 (optional)  Description: This field holds staff remark for arrival/departure.

next_info (optional)  Description: 
This field holds time of new info. Time is reported by MVT NI. UTC time value follows ISO 8601 format used in XML ’dateTime’ type.

last_delay_code (optional)  Description: This field holds code for delay                       

last_delay_code2 (optional)  Description: This field holds code2 for delay          

 

4.3. BasicFlightDataOutbound
flightLegIdentifier : FlightLegIdentifier

See definition under Data entities
flightIsMultiLeg : boolean [0..1]

Flight leg is part of multileg Flight.

If this flight leg is part of a multi-leg flight then the list of airports that is the whole flight is listet in FlightRouteIATA.
flightRouteIATA : AirportIATA [0..*] List of airports a multi leg flight will land on before arriving at the destination. The list consists of AirportIATA codes. The list should contain all airports including first departure airport and last destination airport. The list should be ordered by the actual sequence the aircraft uses the airports.
codeshareData : CodeshareData See definition under Data entities.
flightServiceTypeIATA : FlightServiceTypeIATA [0..1] IATA SSIM Appendix C Service Types.
aircraftIATAType : AircraftIATAType [0..1] 3 character code as designated by International Air Transport Association (IATA) to uniquely designate Aircraft Type. Local (non-IATA) codes can be added as required as long as they are unique for aircraft types within the defined context.
Reference Document: IATA codeset 7800.

flightIsCancelled : boolean [0..1]

 Set to true if the flight operation is cancelled. For flight as with code share it's possible to only cancel the code shared flight.
flightDIIndicator :  DIIndicator [0..1] Indicator showing what kind of flight (domestic, international, Schengen) this is. See also: AirportDIIndicator.
checkInZone : CheckInZone [0..1] Where within the passenger terminal the CheckInDesk is located. Descriptive text string.
aircraftParkingPosition : AircraftParkingPosition [0..1] Where the aircraft is located. Code for a parking position, typically a stand, but can also be a hangar. Each airport has a set of AircraftParkingPositions. Each "AircraftParkingPosition" has one given type, defined by "AircraftParkingPositionType". Each position can have one or more usages, defined by (one or more) "AircraftParkingPositionUsage".
gate : Gate [0..1] Uniquely defines one gate at the airport.
gateAction : GateAction [0..1] The stage in the boarding process for the gate. These can be set manually or by business rules (e.g. auto gating)
sobt : DateTimeUTC [0..1] Scheduled Off-Block Time. The time that an aircraft is scheduled to depart from its parking position. Always UTC time.
tobt : DateTimeUTC [0..1] Target Off-Block Time. The time that an Aircraft Operator or Ground Handler estimates that an aircraft will be ready, all doors closed, boarding bridge removed, push back vehicle available and ready to start up / push back immediately upon reception of clearance from the TWR. Always UTC time.
eobt : DateTimeUTC [0..1] Estimated Off-Block Time. The estimated time at which the aircraft will start movement associated with departure. Always UTC time.
aobt : DateTimeUTC [0..1] Actual Off-Block Time. Time the aircraft pushes back / vacates the parking position. (Equivalent to Airline / Handlers ATD – Actual Time of Departure & ACARS=OUT). Always UTC time.
tsat : DateTimeUTC [0..1] Target Start Up Approval Time. The time provided by ATC taking into account TOBT, CTOT and/or the traffic situation that an aircraft can expect start up / push back approval Note: The actual start up approval (ASAT) can be given in advance of TSAT. Always UTC time.
ttot : DateTimeUTC [0..1] The Target Take Off Time taking into account the TOBT/TSAT plus the EXOT. Each TTOT on one runway is separated from other  TTOT or TLDT to represent vortex and/or SID (Standard Instrument Departure (ref. SIDRoute)) separation between aircraft. Always UTC time.
etot : DateTimeUTC [0..1] Estimated Take Off Time. The estimated take off time taking into account the EOBT plus EXOT. Always UTC time.
atot : DateTimeUTC [0..1] Actual Take Off Time. The time that an aircraft takes off from the runway. (Equivalent to ATC ATD–Actual Time of Departure, ACARS = OFF). Always UTC time.
fuelRampRequested : Kilo [0..1] FuelRamp indicates the kilogram of fuel that is requested. Can be negative, for instance if aircraft has to unload fuel before going to a hangar.
aircraftMTOW : Kilo [0..1] Maximum take off weight. The maximum weight (in kgs) at which the pilot of this aircraft is allowed to attempt to take off, due to structural or other limits.
linkedArrival : FlightLegIdentifier [0..1] Something that links an arriving flight (leg) to a departing flight leg. Will typically contain some key information.

4.3.1. Elements that might be added

checkindesk-data

remark_1 (optional) Description: This field holds public remark for arrival/departure.

remark­_2 (optional)  Description: This field holds staff remark for arrival/departure.

next_info (optional)  Description: 
This field holds time of new info. Time is reported by MVT NI. UTC time value follows ISO 8601 format used in XML ’dateTime’ type.

last_delay_code (optional)  Description: This field holds code for delay                       

last_delay_code2 (optional)  Description: This field holds code2 for delay          

 

 

4.4. BasicFlightLegData

 
FlightLegIdentifier

See definition under Data entities
 

 
   

 

4.5. BasicTurnaroundData

 
FlightLegIdentifier

See definition under Data entities
 

 
   

 

4.6. FlightDataInbound

FlightLegIdentifier

See definition under Data entities
   
   

Expanded version of FlightDataInbound

 

4.7. FlightDataOutbound

FlightLegIdentifier

See definition under Data entities
   
   

Expanded version of FlightDataOutbound

 

4.8. FlightFilter

 

 Describe usage here, definitions below.

flightId : FlightId

Invalidates airline and service type, the rest apply
airport : AirportIATA [0..n]

 Either end of a flight leg

Table with AirportIATA codes. '*' as the first airport indicates all supported by the provider.
Default: '*'

airline : AirlineIATA [0..n]

Table with AirlineIATA codes. '*' as the first airline indicates all supported by the provider.

Default: '*'
flightServiceTypeIATA : FlightServiceTypeIATA  
hoursBefore : Count [0..1]

The number of hours before the current time for which data is wanted. What is compared to the current time can vary with implementations. It will typically be:

  • SIBT / SOBT when that is the only available information
  • EIBT / EOBT when they exist
  • AIBT / AOBT when they exist
  • Implementations can also use landing/take off times.

Default: 1 
hoursAfter : Count[0..1]

The number of hours after the current time for which data is wanted.
See also description above. 

Default: 7
startTime : DateTimeUTC  
endTime : DateTimeUTC   

onlyUpdatedAfter : DateTimeUTC [0..1]

 Only data that has been updated after "onlyUpdatedAfter" is returned.

 Include definitions of terms and types here

FlightId

IATA based identifier for this flight, usually issued long before the flight actually takes place.

FlightId is normally the concatenation of OperatingAirlineIATA, FlightNumber and OperationalSuffix.

FlightId typically identifies a flight to the majority of systems, but it is not unique across time. It's unique only in conjunction with FlightDepartureDate.

Exception: Some airlines use their ICAO code (OperatingAirlineICAO) instead of OperatingAirlineIATA. This might be because they aren't an IATA member or because they just prefer the ICAO code. Regardless, this means that it is allowed to use OperatingAirlineICAO as part of FlightId.

FlightId is then defined as the concatenation of AirlineIATAorICAO, FlightNumber and OperationalSuffix.

 

4.9. FlightLegData

NB! FlightLegData has information about the departure and the arrival of one flight leg.

FlightLegIdentifier

See definition under Data entities
   
   

Expanded version of FlightLegData

 

4.10. FlightLegIdentifier

This is the standard Airport Data Dictionary FlightLegIdentifier. None of the elements are required, but enough have to be present to actually uniquely identify a flight.

 


IFPLID
Defined by Eurocontrol as "A unique flight plan identifier, assigned by the IFPS". Two letters followed by eight digits.
callsign
A call sign is used to uniquely identify an aircraft using the airspace around a particular airport.  Call signs in aviation are derived from several different policies, depending upon the type of flight operation. In most countries, unscheduled general aviation flights identify themselves using the call sign corresponding to the aircraft's registration number.  Commercial operators, including scheduled airline, air cargo and air taxi operators, will usually use an ICAO or FAA-registered call sign for their company. These will typically consist of the ICAO code of the operating airline followed by a flight identification.  The flight identification is very often the same as the flight number, but could be different due to call sign confusion, if two or more flights close to each other have similar flight numbers (i.e. KLM649 and KLM645 or BAW466 and BAW646).
aircraftRegistration
An aircraft registration is a unique alphanumeric string that identifies an aircraft. In accordance with the Convention on International Civil Aviation all aircraft must be registered with a national aviation authority and they must carry proof of this registration in the form of a legal document called a Certificate of Registration at all times when in operation.

An aircraft can be re-registered in special cases, for instance if it's sold to an operator in another country.
ssrCode
Secondary Surveilence Radar Code

A four-digit octal number received from the aircraft transponder when it is interrogated by a secondary surveillance radar (SSR).
flightId
IATA based identifier for this flight, usually issued long before the flight actually takes place.

FlightId is normally the concatenation of OperatingAirlineIATA, FlightNumber and OperationalSuffix.

FlightId typically identifies a flight to the majority of systems, but it is not unique across time. It's unique only in conjunction with FlightDepartureDate.

Exception: Some airlines use their ICAO code (OperatingAirlineICAO) instead of OperatingAirlineIATA. This might be because they aren't an IATA member or because they just prefer the ICAO code. Regardless, this means that it is allowed to use OperatingAirlineICAO as part of FlightId.

FlightId is then defined as the concatenation of AirlineIATAorICAO, FlightNumber and OperationalSuffix.

flightDepartureDate
The scheduled date (based on UTC) of departure of flight. For flights with multiple legs this is the departure of the first leg. This date must not change once set as it is used to make the FlightIds unique.
departureAirportIATA
Departure airport IATA code (see AirportIATA for description of term).
arrivalAirportIATA
Arrival airport IATA code (see AirportIATA for description of term).
departureAirportICAO
Departure airport ICAO code (see AirportICAO for description of term).
arrivalAirportICAO
Arrival airport ICAO code (see AirportICAO for description of term).

 

4.11. ResponseStatus
statusCode : ResponseStatusCode

ResponseStatusCode indicates if the operation succeeded or failed, and if it failed - why. ResponseStatusText is a textual description of ResponseStatusCode. For all operations the set of response codes must be defined. The actual set is dependent upon the context.

 

  • "OK": Operation succeded.
  • "ERR01":
  • "ERR02":
  • "":
  • "":
  • "ERR99": Other error. "statusText" should describe the error.

 

Must be defined!
statusText : ResponseStatusText
A textual description of ResponseStatusCode.

 

 

4.12. TurnaroundData

NB! TurnaroundData has information about the arrival and departure of one aircraft.

Flight leg relevant data must be moved to the arrival/departure part. The arrival/departure parts represent the respective flight legs.

FlightLegIdentifier

See definition under Data entities
   
   

Expanded version of TurnaroundData

 


5. XML Usage

5.1. Nil Values in Schema

For any particular data element, there is an important distinction between the following cases:

(a) the element is missing
(b) the element is present but has a 'nil' attribute assigned to it

In the first case, this means that the sender is supplying no information about the element. This would typically be because no information is available, or because there has been no change in the value of the element. A recipient would not be expected to take any action as a result of this. In particular, it would not be expected to clear any existing value.

In the second case, this means that the sender has explicitly cleared the element. As a result of this, a recipient would typically clear any value that it had previously stored for this element.

The following table shows an example sequence of messages, and the expected actions taken by the data recipient. It should be noted, however, that the action is up to the recipient. The message from the sender is a notification, and not a command for the recipient to take action.

Message contents

Expected action by recipient

aircraftRegistration element missing

Does not set or change aircraft registration value

<aircraftRegistration>ABC123</aircraftRegistration>

Sets the value to ABC123

aircraftRegistration element missing

Does not change the value

<aircraftRegistration xs:nil=’true’>

Clears the aircraftRegistration value

Note that the sender should not use blank data elements such as <aircraftRegistration/> or <aircraftRegistration></aircraftRegistration> as these may cause validation errors. For example, if the schema specifies a format or a minimum length for an element, then a zero-length element will be invalid. This problem does not occur if using the nil attribute.

Note - Where a field is defined as mandatory in the schema, it must not contain a nil value.

6. WSDL and XSDs

File Created Comment

flight-data-service-definitions-2019-08-09.zip

 2020-03-29 10:43  


7. Examples




 

 

 

 

  • No labels

5 Comments

  1. Ade Edwards (Leidos)

    same,

  2. Ade Edwards (Leidos)

    maybe explain why - i.e. XSDs have been intentionally designed with non-mandatory data elements for flexibility

  3. Ade Edwards (Leidos)

    above title is in blue, not black

  4. Ade Edwards (Leidos)

    IT

  5. Ade Edwards (Leidos)

    delay
    Add lookup to data dictionary?