Data

Overview

SDK fetches data from the server and caches it locally automatically.

DataQuery and SkyPath.shared.dataHistoryTime determines the data types and history time to be fetched from the server.

A corresponding SkyPathDelegate function is called when new data is fetched from the server.

Query data with specific configuration to get data from local storage.

H3 resolution 5 is used by SkyPath for the turbulence reports area.

Offline First

The SDK is offline first. All tracked turbulence data is stored offline until successfully sent to the server and the fetched data from the server is stored on the disk and accessible offline according to the description below. All configurations are stored on the disk and stay across app launches until explicit change.

Data Query

At first request, the whole data according to SkyPath.dataQuery is fetched and then only the new data that appeared (delta) is fetched to save network traffic. When cached data expires or a delta can't be received, the whole fresh data will be received again.

There are thousands of turbulence reports around the globe. To reduce network traffic usage and keep only data that is currently needed the data fetch is separated into the different types controlled by the SkyPath.dataQuery object that is set initially to default values and can be updated at any time. All of the below are optional to set but recommended due to your specific flow.

After updating SkyPath.dataQuery in any way, the check, if needed to fetch new data, will be made. If the change requires a new server fetch, the server request will be made immediately. No need to call SkyPath.fetchData(refresh:).

You can update data queries at any time. When updating just one field, use one call.

SkyPath.shared.dataQuery.types = [.turbulence]

When updating multiple fields prefer to copy a current object, modify, and set to update dataQuery in SDK in one call only. On any dataQuery object update SDK will check if need to update the data, for example, because the polygon has been updated. Updating dataQuery multiple times immediately could result in a situation when you will not get fresh data immediately but in the next fetch cycle in a minute or so.

var dataQuery = SkyPath.shared.dataQuery
dataQuery.types = [.turbulence]
dataQuery.polygon = somePolygon
SkyPath.shared.dataQuery = dataQuery

info

Updating SkyPath.dataQuery will trigger a fetch from the server if needed automatically. Receiving server response will take some time so SkyPathDelegate callbacks will be called in a delay, not immediately after the SkyPath.dataQuery update. Delegate callbacks will not be called if no new server fetch is needed or no new data will be received.

tip

Update the visible data by querying SDK after updating the SkyPath.dataQuery not waiting for the SkyPathDelegate. SDK caches data locally, so querying after the DataQuery update will return cached data if any. Then, update data again in the SkyPathDelegate callback.

Route Corridor (Polygon)

Route corridor polygon is a geo-fence area to fetch data inside only. It should be a valid GeoJSON Polygon RFC 7946. Use your route line coordinates to create a polygon with some width distance (50-150 NM is good).

SDK will fetch all data in the corridor at first and then only the delta since the previous fetch in this corridor. When changing the corridor to a different then all data will be fetched in the new corridor (not delta) and then will use delta again. So the route corridor should change only when the route line changes. Changing corridors frequently will result in big network traffic use. Also, choose the corridor width according to your needs because a bigger width and bigger corridor will consume more network traffic.

warning

Frequent changes and a bigger width of the corridor consume more network traffic.

It is fetched separately from other data types and as fast as possible, and also stored offline. Stored on disk, accessible offline.

let polygon: [CLLocationCoordinate2D] = []
SkyPath.shared.dataQuery.polygon = polygon

According to GeoJSON Polygon RFC 7946 it should be a closed ring with up to 250 coordinates, otherwise SkyPath.didFailToFetchNewData(with:type:) will be called with an error. It is recommended to have fewer coordinates and simplify the polygon with enough tolerance.

To make a route corridor and simplification of the polygon you can use the provided [CLLocationCoordinate2D].buffer(widthNM:simplify:tolerance:) from the SDK. Usage example (a background thread is recommended to not block the main thread):

// where `polygon` is [CLLocationCoordinate2D]
dataQuery.polygon = polygon.buffer(widthNM: 100, simplify: true)

warning

For performance and network optimization, we recommend limiting the polygon to an area no larger in size than the route corridor in 250 NM width.

Viewport

A viewport is a polygon of a visible map area in the app to fetch the right data when it's needed. Please keep in mind, that the SDK will try to fetch the data for the viewport as soon as possible after updating SkyPath.shared.dataQuery.viewport. So to save network traffic consider updating viewport when it's needed.

All data in the viewport will be fetched at first and then a delta will be fetched only. But when changing a viewport all data will be fetched again.

warning

Frequent changes and a bigger viewport consume more network traffic.

A good place could be when the pilot moved the map manually, released the finger and the map stopped moving after animation, or when the focused map area is moved by code far from the previously focused area. Stored on disk, accessible offline.

let polygon: [CLLocationCoordinate2D] = []
SkyPath.shared.dataQuery.viewport = polygon

The simplest viewport polygon would be a currently visible rectangle on the map like [NorthWest, NorthEast, SouthEast, SouthWest, NorthWest]. For a more complex polygon, the following rules are applied.

Should be a closed ring and have max 250 coordinates, otherwise SkyPath.didFailToFetchNewData(with:type:) will be called with an error. Simplify the polygon with enough tolerance.

To make a viewport and simplification of the polygon you can use the provided [CLLocationCoordinate2D].buffer(widthNM:simplify:tolerance:) from the SDK. Usage example (a background thread is recommended to not block the main thread):

// where `polygon` is [CLLocationCoordinate2D]
dataQuery.viewport = polygon.buffer(widthNM: 100, simplify: true)
// or
dataQuery.viewport = polygon.simplify()

warning

For performance and network optimization, the SDK could fetch the viewport differently. See details below.

The viewport will be one of the following types inside the SDK based on its size. Separation is done inside the SDK automatically. The Continental United States area is used to illustrate the approximate size as 1x.

• Small - less than 0.5x
• Small-Medium - 0.5x
• Medium - 1x
• Large - more than 2x

Small

• All severities are fetched.
• The whole viewport is fetched.

Small-Medium

• All severities are fetched.
• The whole viewport is fetched.

Medium

• Smooth severity is not fetched.
• The whole viewport is fetched.

Large

• Smooth severity is not fetched.
• Only the max area of 2x in the middle of the viewport is fetched.

tip

Hide the smooth severity on the map on the corresponding zoom level which depends on the map library, so we provided the Continental US area as a reference for the viewport area.

History Time

Set DataHistoryTime to fetch data for. It's an enum with cases: halfHour, hour, twoHours and fourHours. The default is twoHours. The server does some data precalculations so only the specified time frames are supported.

SkyPath.shared.dataHistoryTime = .twoHours

When started, SDK fetches initial data from time back in time and then receives only updates since the last update.

It determines the data history to be fetched from the server. So if it is set to .twoHours for example (the default one), there will be no data locally available for more than 2 hours. If need 4 hours of history, set SkyPath.dataHistoryTime to .fourHours.

Changing from lower time to higher will require an API request to fetch data, when changing from higher to lower time, data could be available immediately as it was already included in the higher history time fetch. Alternatively, time can be set to .fourHours once to fetch 4 hours of history data always and then just query with a different time history to show on the map. Please note, that it will increase network traffic but will allow having more data available immediately and offline during changing time history.

Update

Data is updated every 1 minute.

When the data query route polygon or the viewport is changed, they are fetched as fast as possible not waiting for the next time interval.

You can set SkyPath.dataUpdateEnabled to false to disable periodic new data fetch from the server. Can be updated at any time in the project. Value is stored across app launches until changed.

When you change some query parameters SDK will start fetching fresh data immediately if needed. No need to force fetch manually.

At some point, if need to fetch fresh data immediately (not after a data query update) call the following:

SkyPath.shared.fetchData(refresh: true)

warning

Frequent fetchData(refresh: true) consumes more network traffic

It could be helpful to know if SkyPath data was updated a long time ago (when offline for example), so check when the last time data was successfully received from the server.

SkyPath.shared.dataUpdatedAt

info

Implement SkyPathDelegate.didFailToFetchNewData(with:type:) to monitor if there is any error and handle it accordingly.

Stop Fetching

The preferred way to stop data fetching is to change the SkyPath.shared.dataUpdateEnabled = false.

Based on your implementation you can use other options:

• Set DataQuery.types to an empty set SkyPath.shared.dataQuery.types = [].

• Remove the polygon, and viewport in the SkyPath.dataQuery. It can stop fetching because no area is set to fetch data in.

SDK will continue recording and reporting data.

info

Removing a flight by SkyPath.setFlight(nil) does not stop fetching data because SDK allows fetching data without it, for example for a map visible viewport.

Data Types

SkyPath provides different data types, see DataTypeOptions. The default is turbulence only. Set it if you need more than just turbulence data.

SkyPath.shared.dataQuery.types = [.turbulence]

Turbulence Severity

Color Legend

Smooth #FFFFFF (alpha 0.6) Border #898989 (alpha 0.8) ⬡
Light #FFF04C (alpha 0.8) ⬣
Light-Moderate #FFBC09 (alpha 0.8) ⬣
Moderate #FF7100 (alpha 0.8) ⬣
Moderate-Occasionally Severe #FF0000 (alpha 0.8) ⬣

By default, all severities of turbulence will be fetched, but you can provide a minimum severity to fetch.

SkyPath.shared.dataQuery.minSev = .moderate

.none or smooth severity means that the pilot who crossed this hexagon didn't experience any turbulence, so his report is none. Each hexagon can have multiple reports left for it because multiple flights crossed this hexagon. By default, TurbulenceQuery has aggregate = true which means you'll get one TurbulenceItem per hexagon with the most severe report for this hexagon.