Questions about documentation of beta API


#1

Hi guys!
I’ve started reading your documentation of v3 API and have few initial question.

The first question one belongs to response samples in your beta API documentation

  1. How can I find payload examples of nested object like DecodedForecastStruct in WeatherForecast endpoint response? Example: http://prntscr.com/htq672
  2. How can I find full list of values for fields described as ‘conditions’ or ‘wind_friendly’ of WeatherConditions endpoint response? Example: http://prntscr.com/htq76q.
    Sure I can use google for standardized values search, but it is no guarantee that all will be presented there.

The second question about IATA codes and you already answered a lot about this on the forum, but I should ask.
As I understand IATA codes in your system considered as unreliable and you do not recommend to:

  • send it in requests to your API
  • you return only ICAO codes in all your responses
    Do I understand all correct, or there is something I miss?

#2

I have asked the team to provide some answers to these questions.


#3

For question 1: you can look at the WSDL and get the definitions for all the types: https://flightxml.flightaware.com/soap/FlightXML3/wsdl
For question 2:
cloud_friendly - Cloud_type of OVC-> Overcast Skies, BKN or SCT or FEW -> Scattered Clouds, else "Clear skies"
wind_friendly - wind_speed of >30 -> “Very windy”, >10 -> “Windy”, >3 -> “Light Winds”, else "Calm winds"
For IATA codes vs ICAO codes you are essentially correct.


#4

firstly read the API documentation (it’s pretty good) then use a http client such as PAW or Charles to test/configure your calls. then when you get a 200 OK response back you can very quickly see what data to parse etc.

There’s no substitute to reading the docs though.


#5

Thank you for the answer!
I was read a lot of articles on this forum and have mo questions about your API.

all questions asked based on alert for specific flight, not a ranges

  1. As I understand by forum SetAlert method has secret push minutes_out and if I want this event what I should add to …&channels={16 e_filed e_departure e_arrival e_diverted e_cancelled}

  2. What is the order of pushes by event code
    As I understand the order of pushes based on event code in case of pushes for specific flight is:

  • ‘filed’ - usually 1-2 hours before departure
  • ‘departure’ - after ‘filed’
  • ‘minutes out’ - before departure
  • ‘arrival’ - last event
    But I do not know when ‘cancelled’, ‘diverted’ and ‘change’ will be invoked in this flow, correct me if I wrong in next:
  • ‘cancelled’ - should be invoked prior to ‘filed’ or ‘departure’
  • ‘diverted’ - ?
  • ‘change’ - can be invoked a lot of times before, after and between any event.
  1. What is the possible maximum and minimum number of pushes I will receive if I will subscribe for all possible events for specific flights?

  2. When first push usually will be sent from your side for specific flight? Is it 1-2 hours before departure based on event e_filed or some event can be invoked early?

  3. Does faFlightId value same for specific operator flight and it’s codeshares?

  4. What is the difference between faFlightID and ident in format ICAOAIrlineCodeFlightNumber@DepartureTime? Will be departure time valid if I will get this time from AirlineFlightSchedules response?

  5. Is it possible that departure or arrival time from AirlineFlightSchedules response will be changed in some moment if request flight using same request values after some time?

  6. In case if flight requested by operator ident but operator does not sell tickets your API won’t returns flight details, is it correct?

  7. When usually faFlightID will be issued to flight? For how many hours before departure?
    As I understand answer is : The faFlightID is usually available for a flight when it is less than 48 hours from departure (sometimes only a few minutes from departure), but it will vary depending on whether it is a GA flight or a commercial flight, and whether it is in an area of primary flight coverage (US/Canada/Australia) or not.

  8. Will be faFlightID changed if flight was diverted? Will I continue to receive pushes if flight was diverted or I should set new alert using new faFlightID?

  9. Does V3 API FlightInfoStatus method and V2 API Push I receive contains same information in the same time or one of this methods contains more recent information first?

  10. What the format/standard of field “tz” (time zone) of Timestamp object? Is it ISO code of zone?

  11. What the time zone of fields “arrivaltime” and “departuretime” of AirlineFlightScheduleStruct object, local or UTC?

  12. Questions about https://flightaware.com/:
    A long period of time we were using service www.eflightlink.com for our UI web part with next parameters http://www.eflightlink.com/track/rd.asp?provider=FADIRECT&AL=AA&FN=1406&DT=20171229.
    This request made redirection to your web page https://flightaware.com/live/flight/AAL1406 that shows flight by given ident on current day.
    Now I found path that can shows me flight for the given date not current day, it looks like https://flightaware.com/live/flight/AAL1406/history/20180111/0250Z/KMIA/KJFK
    Can I use this URL for my needs and redirect my users to this page for free or I will violate agreements with you doing this?
    In case I can use it for free I need to know what date and time from your API payload I should use to create this URL for specific flight?
    As I understand pattern of URL is https://flightaware.com/live/flight/{ICAOAirlineCodeFlightNumber}/history/{UTCFlightDate}/{UTCFlightTime}Z/{ICAOSourceAirportCode}/{ICAODestinationAirportCode}
    What datetime fields from V3 API AirlineFlightSchedules or FlightInfoStatus for {UTCFlightDate} and {UTCFlightTime} parameters? AS I understand this is flight departure time.


#6

Answering what I can…

  1. ‘filed’ - usually 1-2 hours before departure
    ‘departure’ - after ‘filed’
    ‘minutes out’ - before arrival
    ‘arrival’ - last event
    ‘cancelled’ - should be invoked prior to ‘filed’ or ‘departure’
    ‘diverted’ - at any time after departure but before arrival
    ‘change’ - can be invoked a lot of times before, after and between any event.

  2. I imagine there will be a minimum of 1 (filed - unless a scheduled airline flight that is cancelled before flight plan filing) and no maximum since there can be many updates.

  3. First will be when the flight plan is filed. Usually up to 24-36 hours before departure.

  4. Yes, there will be one faflightid for each flight that is operated and can have numerous codeshares associated.

(7). This is possible, but unlikely within a week of the flight.

(10). Diverted flights will have the same faFlightID.


#7

Thank you for answers!
Can you verify order number of answers, because it looks like desynchronized in order to my questions, mostly answers #6 and #7


#8

(6). You shouldn’t try and construct the faflightid. there are instances where it won’t conform to what you are expecting.

(11). The push notification will be delayed by less than a minute or so because of the extra processing/queueing/sending that goes along with it.


#9

I won’t try to construct faFlightId by myself anyway.
I just see by documentation that query parameter “ident” accept few different values, for example:

  • faFlightID
  • ident in format AAL1406
  • ident in format AAL1406@1231454856
    Are examples correct?

As I understand if I will use faFlightID as value of “ident” it guarantees that response will contain result
and if I will try to construct identifier as AAL1406@1231454856 result will depend on hit by airline, flight number, and departure datetime.
Based on this I want to understand which type of value for ‘ident’ more reliable for example to set alert for specific flight.


#10

faFlightID is the unique identifier for a flight, so it will always give you the one you want, if you already know it.


#11
  1. you can specify minutes_out xxx in the channels parameter where xxx is the number of minutes out you want the alert.

#12

(8). For calls like FlightInfoEx, you can request either operator or marketing airline and it will just figure it out. For other calls, like BirdseyeInFlight, you have to be more specific. The documentation on the calls tells you what you can/can’t search.

(9). An faFlightId will be created, typically, 1-2 hours before, but, for some larger airlines with schedules that are typically good and accurate, you may see a flight 72 hours out. You can guarantee you will have an faFlightId by the time you get a departure message.


#13

1- As I understand by forum SetAlert method has secret push minutes_out and if I want this event what I should add to …&channels={16 e_filed e_departure e_arrival e_diverted e_cancelled}
If you want to receive minutes_out alerts, please add e_eta to you list of eventcodes. Example: …&channels={16 e_filed e_departure e_arrival e_diverted e_cancelled e_eta}
The default minutes_out time is 45 minutes, but if you want to customize this time to something different (15 minutes in the example), you will need to add something like this: …&channels={minutes_out 15} {16 e_filed e_departure e_arrival e_diverted e_cancelled e_eta}

12- What the format/standard of field “tz” (time zone) of Timestamp object? Is it ISO code of zone?
The tz field will look like these examples: PST, CST, EST. They are just the standard abbreviations.

13- What the time zone of fields “arrivaltime” and “departuretime” of AirlineFlightScheduleStruct object, local or UTC?
arrivaltime and departuretime do not have timezone fields. The reason is that these times will be given in epoch times (an epoch time is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT))

14- Questions about https://flightaware.com/:
A long period of time we were using service www.eflightlink.com1 for our UI web part with next parameters http://www.eflightlink.com/track/rd.asp?provider=FADIRECT&AL=AA&FN=1406&DT=20171229.
This request made redirection to your web page https://flightaware.com/live/flight/AAL1406 that shows flight by given ident on current day.
Now I found path that can shows me flight for the given date not current day, it looks like https://flightaware.com/live/flight/AAL1406/history/20180111/0250Z/KMIA/KJFK1
Can I use this URL for my needs and redirect my users to this page for free or I will violate agreements with you doing this?
No

In case I can use it for free I need to know what date and time from your API payload I should use to create this URL for specific flight?
As I understand pattern of URL is https://flightaware.com/live/flight/ {ICAOAirlineCodeFlightNumber}/history/{UTCFlightDate}/{UTCFlightTime}Z/{ICAOSourceAirportCode}/{ICAODestinationAirportCode}
What datetime fields from V3 API AirlineFlightSchedules or FlightInfoStatus for {UTCFlightDate} and {UTCFlightTime}
parameters? AS I understand this is flight departure time.
UTCFlightDate and UTCFlightTime can both be derived from the departuretime epoch given in AirlineFlightSchedules.


#14

Thank you for answers!
I want to clarify answer on question #14
I can not redirect my users to page https://flightaware.com/live/flight/AAL1406/history/20180111/0250Z/KMIA/KJFK1, because will violate some agreements.

What if I will ask about page with route https://flightaware.com/live/flight/AAL1406, will I have answer same as for the previous page?


#15

Sorry I meant to say “no” to the second part of your question.

ie. you won’t violate any agreements and you can redirect to any links on our site.


#16

ohhh, exelent, thank you!!!

I am forming last question, that most important to start developing, will post it soon


#17

Last question.

In our flow, our customer verifying existence flight of flight and after this subscribes on it’s updates, for example flow is next:

End-user give to us information like: date time of flight, airport (departure of arrival), airline, flight number;

Let’s say that departure of this flight will be 7 months in future from moment of verifying;

So we verifying this flight via your V3 API endpoint AirlineFlightSchedules and response give us the exact flight.
In given flight scheduled departure time is present, but faFlightID - blank.

Now I need to setup alert for this flight, there is the place where question start:
On current moment faFlightID is not issued to the flight.

  1. I have to wait almost 7 months to get this faFlightID and than send request to V2 API SetAlert endpoint with parameter ident=<“issued faFlightID”>
  2. I can try to send request to V2 API SetAlert endpoint at current moment with parameter ident= <“actual_ident” value from AirlineFlightSchedules response> + @ + <“departuretime” value from AirlineFlightSchedules response>

Questions:

  1. What option above is more reliable;
  2. If I will use option #2 will I miss Alert because departure time will be changed in for example month before flight departure and “ident” value of option #2 will be not valid after this.
    (I know that scheduled departure time can be changed based on answer #7)

#18

The best way to set the alert will be to use the ident and have the start and end date be the date 7 months in the future. You don’t have to specify a departure time, the date is sufficient.


#19

But one flight can fly few times in a day with the same ident, departure and arrival airports.


#20

Then you can append the origin or destination to be more specific. They are both optional parameters.

You can see that in the documentation here: https://flightaware.com/commercial/flightxml/explorer/#op_SetAlert