Availability Upload
This use case allows operators and marketing agents to automatically upload aircraft availability 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 softwares used by professionals in the charter jet market has the ability to automatically send availability 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
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 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 availability for that aircraft.
Time gaps
Time gaps between the activities are OK. So the start time of one activity does not have to be right after 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.
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.
Trip ID
It is highly recommended to send the tripId (lift id) from each quote request, with the corresponding booked trip activity in the availability upload. This is done to get valuable statistics on which requests end up as a booked trip. More information about how to implement this is found on the PUT /schedules operation page.
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.
- Sent schedule data does not contain activities older than one month.
- Sent schedule data contains at least one activity that ends in the past.
- Schedules are sent on a regular interval (e.g. once every 5 minutes).
- Users cannot configure call frequency so schedules are sent more frequently than once every 5 minutes.
- In each consecutive call the same activity has the same activity id.
- All times are sent in UTC.
- Marketing information is only sent for empty leg activities.
- Verified flag in the marketing information is set only if someone has manually marked the empty leg as marketable.
- Each company using the software can specify their own API connection and this is used in API calls related to this company.
- A specific aircraft can use a different API connection than the company’s default API connection.
- There is no retry logic in place generating additional calls if the call is unsuccessful.
- 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.
- The application should have basic error handling capabilities as suggested in API Basics: Error Handling.
Updated 30 days ago