Heading

In all typical use cases, you should use heading. These use cases include rotating the floor plan / map automatically or showing the current walking direction to the user as an arrow. 

Heading reacts quickly to any movement of the device. Thus, when the user stands still and rotates the phone, heading follows the device's rotations on xy-plane in real time.

In more technical terms, heading indicates the direction the phone's y-axis* points towards. The phone's y-axis points forward when holding the phone in portrait mode, screen towards the ceiling. 

The heading angle definition is : 0 for north, 90 is east, and so on.  

To access heading, use the Orientation API. Here's a complete example for Android.

*Note that when in landscape mode, the y-axis points to the right or left.

The screenshot below shows heading in red and bearing in blue, just after stopping walking and turning the device 90 deg counterclockwise. Heading follows in real time.

Bearing

Note! In most typical use cases you should use heading instead (see above). 

Bearing indicates direction of walking and hence reacts slowly and inaccurately to quick turns of the device itself. Bearing is accurate when walking. 

The bearing angle definitions are the same as for heading above.

On Android, bearing is accessible from IALocation.getBearing().

On iOS API is CoreLocation compatible and the  bearing calculated by IndoorAtlas is called course. It's available as standard CLLocation class.

3D Orientation API

The full orientation of the device in ENU coordinates is given by the orientation quaternion. The given quaternion can be used to project from phone sensor coordinates to local ENU (east, north, up) coordinates.

The heading and orientation provided by IndoorAtlas takes into account the local variations in the magnetic field and can be more precise and stable than what is provided by Android and iOS platforms currently.

The 3D orientation API can be utilized e.g. in Virtual Reality (VR) applications. See example in Android SDK Examples or iOS SDK Examples repository.

Note that IndoorAtlas has a separate Augmented Reality (AR) API.