SearchBirdseyeInFlight Questions


I’m trying to get aircraft data within geographic and time boundaries using “SearchBirdseyeInFlight” and I could use some extra information/explanation of some of the returned data and query functions. I expect some of my problems are just a misunderstanding on my part. I know I asked a lot of questions so partial responses are welcome!

  • What’s the difference between “clock” and “lastPositionTime” keys?

  • How do either of these relate to “timestamp” in the result? For example, when I query clock >= 2017-04-28 15:30:44
    , I get timestamps ranging from 15:31:07 to 15:15:23.

  • I expected the Unix timestamps to be UTC+0, but queries against “clock” don’t return results until I set to times to local. I double checked this against a tracklog from the website.

  • When I match timestamps from my results to track log data on the website, ground speed never matches up. All other geo parameters seem to be OK

  • I can run incremental queries and get results that are identical or sometimes identical with the exception of latitude, longitude, and waypoints. E.g. below.

At 15:51:00: Query clock >= 15:50:30 (409 results)
At 15:51:30: Query clock >= 15:51:00 (437 results, 4 completely identical results, 3 w/ identical timestamps but modified lat/lon/waypoints)

  • Lastly, if I change my query spacing, it effects the returned data. In the above I query every 30 seconds. If I query every 15 seconds, I get about 1/3 of the results. I suspect this has something to do with “the time the data was captured” vs “the time the data was put in the database” but that isn’t clear from the API docs

Thanks in advance!


Anyone have any experience using this function? I’m out of ideas trying to test out and understand the timing involved.


The difference between the “clock” and “lastPositionTime” keys is that clock is updated on any event (so anything that updates the flight such as a departure notice, etc) whereas the lastPositionTime is only updated when a new position is received.

The timestamp is the time the last position was received. So if you pass in {>= clock 1493831890} you may see timestamps that were earlier than the time passed in since a non-position update could have happened in the time interval specified.

I’m not sure what you mean by you didn’t receive results until you set times to local. clock and lastPositionTime are expecting an epoch value (ie 1493829925 for 5/3/2017 16:45:25 UTC. Can you give some additional explanation on this?

The timestamps are for when flightaware received the position update, not necessarily the exact timestamp for when that position was generated. As such you really can’t use the timestamps and positions to compute a reliable groundspeed. However the result returned form a query will include the groundspeed at the time of that position.

The identical results again goes back to a non-position update causing the clock to increment. If you instead use the lastPositionTime then you should not see those duplicates.


The time keys make sense based on what I’ve seen so far. The timestamp/timezone issue was my fault. The function I used to convert epoch time to something readable had an implicit timezone instead of returning as Zulu (lesson learned).

I’m not sure what you mean about groundspeed. I’m not deriving it, I’m using the value in the result. Are the speeds listed in a flight’s track log (like this an airspeed?

I’m not sure I understand the duplicates/partial duplicates though. I don’t get a lot of them, but they seem to be there. I made 3 identical queries in 15 second intervals. I queried over range and lastPositionTime (NOT clock) and received the following (truncated to the important parts):

{'ident': UAL2005,
  'latitude': 39.00037,
  'longitude': -120.97374,
  'timestamp': 1493674407}

{'ident': UAL2005,
  'latitude': 38.98333,
  'longitude': -121.05,
  'timestamp': 1493674407}

{'ident': UAL2005,
  'latitude': 38.98333,
  'longitude': -121.05,
  'timestamp': 1493674407}

Why did the position change without the timestamp also changing?

Thanks again!


Sorry I misunderstood on the groundspeed question. Turns out the groundspeed field in SearchBirdseyeInFlight is actually the filed airspeed in knots. As a workaround for that you can query SearchBirdseyePositions which does return the correct groundspeed.