The Compass API allows a PhoneGap program to determine the device’s heading along a two-dimensional plane roughly corresponding to the surface of the earth. Many modern smartphones have a physical compass (on a chip), and the API simply queries the chip and returns an angle between 0 and 360 indicating the direction the device is pointing. A value of 0 indicates the device is pointing north, 90 indicates it is pointing east, 180 refers to south, and 270 refers to west.
Not all smartphones have a compass. The iPhone series of devices have always had one, but RIM didn’t add one until BlackBerry 7 OS devices.
The Compass API works ...