Schedule Upload

This use case allows operators and marketing agents to automatically upload aircraft schedule information to the Avinode Marketplace.

Overview

Each aircraft marketed in the Avinode Marketplace has a schedule and this schedule contains information about the aircraft’s activities like passenger flights, ferry flights, maintenance etc. Each activity holds information about the start time and position of the aircraft and also the end time and position. This information is then used by various functions in the Avinode Marketplace.

Other software, such as fleet management systems, are often integrated to keep track of aircraft movements and activities. The majority of the fleet management software used by professionals in the charter jet market has the ability to automatically send schedule data to the Avinode Marketplace through an application like this.

Pre-requisites

Gaining an understanding of our APIs and fundamentals is essential to the success of your project. To do so, start by reading our introductions page, including the pages linked in the "Before you start" section.

Implementation

The application uploads schedule information by periodically calling the PUT /schedules operation for each of the aircraft in the operator’s fleet. More information about how to implement this operation is found on the PUT /schedules operation page.

Call frequency

The service should be called on a regular interval. The recommended frequency is to send data for each aircraft once every 5 minutes. If the call frequency is configurable in the calling software it should not be possible to configure this to send more frequently than once every 5 minutes. The Avinode Marketplace informs brokers how fresh the schedule data is so the service should be called regularly without long periods of not sending data.

Schedule specifics

Complete schedule

A complete schedule must be sent in each call. Any schedule data that exist in the Avinode Marketplace before the call, and that is not included in the call, will be removed.

Continuous schedule

A schedule is ideally continuous. That means that the start airport of one activity is the same airport as the end airport of the previous activity. It is possible to upload a schedule that isn’t continuous, but this might affect the Marketplace’s ability to show and use the correct availability for that aircraft.

Overlapping activities

Activities that overlap in time should be avoided. However sending an activity that starts the exact same time as the previous ends is OK. It is possible to upload overlapping activities, but this might affect the Marketplace’s ability to show and use the correct schedule for that aircraft.

Time gaps

Time gaps between the activities are OK. The start time of one activity does not have to be right after the end time of the previous activity. If there is a time gap between two activities, the Marketplace will consider the aircraft to be on-ground available at the end airport of the first activity during this gap.

Schedule time span

In addition to sending all future activities, the uploaded data should also at least contain the most recent activity that has an end time in the past. This to ensure that the current position of the aircraft is always known. An easier approach might be to always send, for example, one month of the most recent historical data in each call and hopefully this data will contain at least one activity that ends in the past.

Activity types

Each schedule activity must have an activity type that specifies what kind of activity it is. This will be used to determine how this activity should affect the aircraft’s availability. What values to send is up to the application calling this operation. The value cannot be longer than 20 characters. The sent value will also be shown when the Avinode Member views the schedule data in the Marketplace’s online web interface. Each Avinode member company maintains a mapping table for their activity types where each activity type is mapped to one of the items in the list below. New non-mapped activity types will be automatically created in the mapping table when sent for the first time. They will be mapped as Occupied by default.

The member can at any time log in to the Avinode Marketplace and change their mappings. Here is a list of the available interpretations an activity type can be mapped to.

• Empty Leg Availability – During an activity of this type the aircraft will be considered available. The activity will also be marketed as an empty leg in the Avinode Marketplace.
• Ferry Availability – During an activity of this type the aircraft will be considered available. The activity will not be marketed as an empty leg. The search algorithm will look at any following passenger leg to ensure that the aircraft has enough time to position for that.
• Flight Occupied – During an activity of this type the aircraft will be considered occupied. This option should be used for all flight related occupancy (e.g. 135 trips, 91 trips etc.).
• Occupied – During an activity of this type the aircraft will be considered occupied. This option should be used for all non-flight occupancy (e.g maintenance).
• Onground Availability – During an activity of this type the aircraft will be considered available. This option can be used to indicate transient (away from home base) availability. The search algorithm will price the aircraft from the indicated airport, rather than home base. Note that sending activities of this type is not required (see “Time gaps”).
• Option Availability– This is an “information only” type. Activities mapped to this type will be shown in the Schedule for the aircraft, but does in no way effect the position of the aircraft, nor does it affect the availability of the aircraft. This can be used for non-confirmed trips etc.

🚧

Invalid airport codes handling

Avinode checks airport codes against current industry official records, but sometimes airport codes change or an invalid value is sent. In this case the schedule will still be updated, i.e. Avinode will not terminate the operation, but the invalid airport code for either startAirport or endAirportwill be replaced by the aircraft homebase.

The HTTP status code HTTP 200 + Errors will be returned with an error message including information on which schedule activity and airport code caused the error.

The error should be flagged to the user and handled accordingly to avoid any schedule discrepancies.

For more information see: Error handling guide: HTTP 200 + Errors

Block Time

When providing startDateTime and endDateTime for each activity, it is crucial that these times refer to the block time. The block time represents the total duration of a flight, from pushing back from the departure gate ("off-blocks") to arriving at the destination gate ("on-blocks").

Uploading Trips

When uploading a schedule, the FMS must include an externalTripId for every activity included in a trip, which refers to the trip identifier within the FMS.

More information can be found on the PUT /schedules operation page.

Scheduled Services Capability

The FMS must support the option to include services when uploading schedule. However, the operators can have the flexibility to configure whether to share this information or not. The scheduled services capability must support the inclusion of various services like FBO, Fuel, Catering, Limo, Hotel, Handling, etc. In addition, the scheduled services must contain details about the service, covering:

• serviceProviderId
• serviceProviderName
• airport
• serviceType
• serviceFor
• dataSource

More details can be found on the PUT /schedules operation page or in Swagger.

Flight Regulations

When the flight regulation is specified for an activity, ensure it is included in the schedule upload. The recommended values to send for different flight regulations are:

• PART_135
• PART_125
• PART_121
• PART_91
• PART_91K
• PART_CAT
• PART_NCO
• PART_NCC
• SUBPART_604
• SUBPART_704

For detailed information refer to the PUT /schedules operation page.

Connecting Trips to Avinode Requests

If the activity is based on a request from the Avinode marketplace it is required to send the tripId (sellerlift ID or RFQ ID) from each quote request, with the corresponding booked trip activity when uploading schedules. This is done to get valuable statistics on which requests end up as booked trips.

More information about implementing this is found on the PUT /schedules operation page.

Empty leg marketing

It is possible to upload activities that will be automatically published as empty legs in the Avinode Marketplace. Providing additional marketing information for these empty legs makes them more attractive to potential brokers.

Marketing start and end times

It's possible to add a marketing start and end time with an empty leg activity. These define when the aircraft is available to fly this empty leg. The maximum allowed time span is five days.

🚧

Empty leg marketing times

• A longer time span than 5 days will result in the empty leg not being available to the market.
• Uploading consecutive empty legs from and to the same airports to circumvent the five day span limit is not allowed.
• If two empty legs with overlapping marketing time spans are uploaded for the same aircraft, only one of the empty legs will be available to the market.
• The times should be sent as UTC times.

Marketing verified

All empty leg activities that the Avinode member company has actively verified as marketable should be marked verified when uploading the schedule. Actively verified means that someone has manually marked this activity as a sell-able empty leg. Verified empty legs will be treated with a higher priority in the Avinode Marketplace and are more likely to attract business than non-verified empty legs.

Operators that markets empty legs where it turns out the empty leg is not really available to the market will get a bad reputation and brokers will eventually be less likely to show interest in that operator’s real empty legs. Automatically marking all empty legs as verified is not allowed.

Handling multiple API connections

🚧

Important!

Most applications of this type must be able to handle multiple API connections. Here are the recommended best practices.

Each company using the integration should be able to specify their own default API connection by entering its authorization token. The application will use this API connection when uploading availability data for this company’s aircraft.

For each aircraft, a separate API connection can be specified. If this is set, it will override the company’s default API connection and be used when uploading availability data for this specific aircraft. The reason for this is, that it is not uncommon that one company can have aircraft that are marketed in different company accounts in the Avinode Marketplace.

Go Live!

👍

Implementation checklist

All items on this check list must be true in order for an application of this type to be allowed to call the live Avinode Marketplace environment.

1. The application must comply with the Basic Go Live requirements.
2. Sent schedule data does not contain activities older than one month.
3. Sent schedule data contains at least one activity that ends in the past.
4. Schedules are sent on a regular interval (e.g. once every 15 minutes).
5. Users cannot configure call frequency so schedules are sent more frequently than once every 5 minutes.
6. In each consecutive call the same activity has the same activity id.
7. All times are sent in UTC.
8. startDateTime and endDateTime for each activity refer to the block time.
9. Sent schedule data must include an externalTripId for every activity included in a trip, which refers to the trip identifier within the FMS.
10. Sent schedule data must include the the tripId (sellerlift ID or RFQ ID) from each quote request, with the corresponding booked trip activity when uploading schedules.
11. Support the option to include services when uploading schedule, such as FBO, Fuel, Catering, Limo, Hotel, Handling, etc., and include detailed information about the service.
12. When an activity has flight regulation specified it is included in the schedule upload.
13. Marketing information is only sent for empty leg activities.
14. Verified flag in the marketing information is set only if someone has manually marked the empty leg as marketable.
15. Each company using the software can specify their own API connection and this is used in API calls related to this company.
16. A specific aircraft can use a different API connection than the company’s default API connection.
17. There is no retry logic in place generating additional calls if the call is unsuccessful.
18. The users of the application can see the status of the latest call for each aircraft and see any messages returned by the service in that call.
19. The application should have basic error handling capabilities as suggested in API Basics: Error Handling.
20. The application must include the integration software name in the headers of each API call in the X-Avinode-Product parameter.