Two things decide what you receive for a pilot: what the pilot allows (permissions) and their Gaggle plan (detail). Both are checked on every request, so a change applies on the very next call.
For each connected app the pilot sees your name and logo, and chooses:
profile, and turn it back on later, without reconnecting.everyone, groups, friends or private. The pilot chooses which levels each app sees, by default everyone, groups and friends (the list can be narrower, or empty). Imported flights are private by default in Gaggle, so they are shared only when private is included. Manual log entries have no sharing level and are always visible.Some things are never shared with anyone: flights recorded under an event organiser’s control, and these parts of the log on any plan: tasks, notes, maximum altitude, take-off height, scores, achievements and images. Manual log entries have no sharing setting and are always included.
A missing scope answers 403 with the scope that is not enabled:
{ "error": "insufficient_scope", "scope": "tracks" }You can also only ask for the scopes your registration allows. Asking for another one is refused with invalid_scope.
The scope on your access token is the upper bound of what you asked for, and it never changes. The pilot’s switches and plan do change. To know what you can use:
GET /v1/me after connecting. Use scopes, plan, historyFrom and flightSharing.connection.updated webhook (the pilot changed a switch, or the plan changed), and re-sync the pilot’s flights, because the history window and the fields may have changed.Never decide what to request from the token’s scope. Requesting something that is switched off just returns 403.
Every scope works on every plan. The plan sets how far back you can read and how much detail comes back.
| Free | Frequent Flyer | Adventurer | |
|---|---|---|---|
| Flights, flight detail and tracks | New flights only | Last 30 days | Whole logbook |
| Stats | Whole logbook | Whole logbook | Whole logbook |
Free has no history. You see only flights that first reached Gaggle after the pilot connected your app, whatever their flight date. A manual entry the pilot adds later counts as new; the flights already in the logbook never do. Frequent Flyer’s window is by flight date, and Adventurer has no window.
historyFrom in /v1/me is where the window starts: 30 days back (the start of a UTC day, so it moves forward once a day), or (Free) the exact moment the pilot connected. On Adventurer it is null: there is no window, you see the whole logbook. A flight outside the window answers 404 and does not appear in the list. Webhooks follow the same windows.
id, source (recording, import or manual), hasTrack and updatedAt are always present.
| Field | Free | Frequent Flyer | Adventurer |
|---|---|---|---|
date (take-off time, UTC), durationMinutes | Yes | Yes | Yes |
site (take-off site name) | Yes | Yes | Yes |
aircraft (name, engineName) | Yes | Yes | Yes |
takeOffCoordinates (lat, lng) | Yes | Yes | Yes |
flightType | Yes | Yes | Yes |
distanceKm | Yes | Yes | |
weather | Yes |
Fields your pilot’s plan does not include are left out of the JSON. Treat every optional field as optional.
distanceKm is rounded to 0.1 km. Weather units: temperature in °C (to 0.1), humidity in percent, pressure in hPa, visibility in metres, windSpeed and gustSpeed in metres per second, and windDirection in degrees (where the wind comes from). Fields the source did not provide are left out, and flights entered by hand carry wind only.
| Free | Frequent Flyer | Adventurer | |
|---|---|---|---|
| Lifetime flights and airtime | Yes | Yes | Yes |
| Lifetime distance | Yes | Yes | |
| Per year (flights, airtime and distance) | Yes | Yes | |
| Per month, and per aircraft | Yes |
Tracks are the same on every plan. A track has every recorded point, and each point has time, latitude, longitude and altitude, as recorded on the device (or in the imported file), not smoothed or corrected. The tracks follow the same history window as flights. Providers can work out speed, heading, climb rate and similar values from the points.
Stats are counted from the pilot’s whole logbook, but only flights at the sharing levels the pilot allows you to see count (manual entries always do). years come newest first, each year’s months are in calendar order and list only months with flights, and distances are rounded to 0.1 km. aircraft lists each aircraft by number of flights, most first.
If a pilot upgrades or downgrades, the new plan applies on your next request and Gaggle sends you a connection.updated webhook with the new plan. Re-read /v1/me and re-sync flights: a downgrade shortens the history window and removes fields (distance, weather) and stats detail, an upgrade extends the window and adds them.
Pilots are told on the consent screen what their plan gives your app, and are offered an upgrade there. Pilots can read how connected apps work in the help center: Connected apps. It helps to say in your own product what you do with each plan, so pilots know why a richer plan can be worth it.