Skip to content

Latest commit

 

History

History
489 lines (367 loc) · 29 KB

api_reference.md

File metadata and controls

489 lines (367 loc) · 29 KB
Raw

API Reference

This geolocation API is multi-threaded for maximum efficiency and reduced impact on user experience.

IMPORTANT - READ THIS FIRST! There are important differences between GPS Provider data, Network Provider data and Cellular data. It can be confusing.

  • GPS Provider data is focused on providing a device location using latitude and longitude information via a GPS.
  • Network Provider data is focused on providing a device location using latitude and longitude via information from the cellular network or WiFi.
  • Cellular data is focused on providing cell tower meta-data via information from the cellular network. It may or may not contain a lat/lon. More info below.

Methods

Method Returns Description
start callback Starts any location providers that were specified in the configuration options.
stop callback Stops all location processes. This will also automatically occur when the app is placed in the background. The app will continue to consume memory.
kill callback Shuts down all location activities, stops all threads and destroys the application instance. Can be used to hard stop a runaway GPS process, for example, or to simply close the application and stop all processes.

Method Callback Signatures

stop()

The stop() method attempts to gracefully stop all location providers that have been enabled in the configuration options. It provides both success and error callbacks. The error callbacks originate from their designated location provider. The success callback looks like this:

    {
        "stopLocation":[
            {"provider":"gps","success":true},
            {"provider":"network","success":true},
            {"provider":"cell","success":true}
        ]
    }

kill()

The kill() method attempts to forcefully stop all location providers that have been enabled in the configuration options. It also attempts to terminate the Cordova threadpool.

The error callbacks originate from their designated location provider. The success callback looks like this:

    {
    	"success": true
    }

start()

The documentation below provides details on the JSON data provided in the start() callback.

Configuration Options (Required)

Option Type Description
minTime integer The minimum time interval between location updates in milliseconds. Smaller numbers increase battery usage.
minDistance integer The minimum distance between location updates in meters. Smaller numbers increase battery usage.
noWarn boolean Display native warning popup dialog if GPS or Network is disabled. Only applies to Pre-M Android versions.
providers String Acceptable values to specify location providers are: "gps", "network", "cell", "all" or "some". Network provider may return locations if WiFi or cellular internet is enabled.
useCache boolean Will return cached values from any active location provider. While not gauranteed, both GPS and NETWORK providers have a cache.
satelliteData boolean If true it returns all available satellite data from the GPS receiver. Requires that the gps provider is also enabled.

CAUTION: Activating satellite data will increase CPU and memory usage.
buffer boolean If true it will start a buffer that returns the averaged geometric center of GPS and/or NETWORK locations. Use this when requirements call for determining a single, best location. The buffer uses a FIFO ordering, so new values added and old values are removed.
bufferSize integer The maximum number of elements allowed within the buffer. It's strongly recommended to use as small of a buffer size as possible to minimize memory usage and garbage collection. Experiment to see what works best. This property will be ignored if buffer is set to false. Buffers larger than 30 elements may not be necessary.

CAUTION: Increasing the buffer size will increase CPU and memory usage.
SignalStrength boolean Whether or not to return cellular signal strength data.

GPS and Network Data

Whenever a location event is successful, this plugin will return the following location data in the form of a JSON payload. This section provides a description of the attribute/value pairs that are returned.

Note: All locations generated by the native LocationManager are guaranteed to have a valid latitude, longitude, and timestamp (both UTC time and elapsed real-time since boot), all other parameters are optional.

Example:

	{
    "provider":"gps",
    "latitude":"42.05991886",
    "longitude":"-105.00000",
    "altitude":"1565.0",
    "accuracy":"9.0",
    "bearing":"0.0",
    "speed":"1.0",
    "timestamp":"1449876957000",
    "cached":"false"
    }
Property Type Value Description
provider String "gps" or "network" Let's you determine where this data is coming from. Network can be cellular and/or WiFi.
latitude String number Latitude in degrees. 0.0 is a valid WGS 84 location off the coast of Africa.
longitude String number Longitude in degrees. 0.0 is a valid WGS 84 location off the coast of Africa.
altitude String number Altitude if available, in meters above the WGS 84 reference ellipsoid.
accuracy String number Get the estimated accuracy of this location, in meters.

Android defines accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.

In statistical terms, it is assumed that location errors are random with a normal distribution, so the 68% confidence circle represents one standard deviation. Note that in practice, location errors do not always follow such a simple distribution.

This accuracy estimation is only concerned with horizontal accuracy, and does not indicate the accuracy of bearing, velocity or altitude if those are included in this Location.
bearing String number The bearing, in degrees. Bearing is the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range (0.0, 360.0] if the device has a bearing.
speed String number The speed if it is available, in meters/second over ground.
timestamp String number Return the UTC time of this fix, in milliseconds since January 1, 1970.

Note that the UTC time on a device is not monotonic: it can jump forwards or backwards unpredictably.

All locations generated by the LocationManager are guaranteed to have a valid UTC time, however remember that the system time may have changed since the location was generated.
cached String boolean Whether or not the location data, either GPS or Network, was returned from the device cache.

Note: cached data can be very unpredictable, use with caution and make sure to compare the timestamp with current time to establish the age of the cached location.

Buffered GPS and Network Data

If you set the buffer configuration option to true this will enable new attribute/value pairs to be included in the return payload that are in addition to the GPS and Network elements listed above.

Buffering is typically used in commercial and government applications that require greater accuracy for determining static locations. Using the buffer will minimize location fluctuations by providing an averaged geometric center of cartesian coordinates.

Best practices for buffer requires the user to hold the device still in one location until the desired accuracy level is reached and the buffer is full. An all-JavaScript (non-native Android) sample app can be found in the html5-geolocation-tool-js Field Location Template.

Note that cached location data is not buffered since there will only one cached location per provider.

Example:

    {
    "provider":"gps",
    "latitude":39.91974497,
    "longitude":-105.11730789,
    "altitude":1651,
    "accuracy":48,
    "bearing":0,
    "speed":0,
    "timestamp":1452634769000,
    "cached":false,
    "buffer":true,
    "bufferSize":10,
    "bufferedLatitude":39.919744632857146,
    "bufferedLongitude":-105.11730871142859,
    "bufferedAccuracy":48
    }
Property Type Value Description
buffer String boolean Indicates whether or not buffering has been activated.
bufferSize String integer Indicates the number of elements within the buffer. You can compare this value against the maxBufferSize as set in the configuration options.
bufferedLatitude String number The buffer's geometric latitudinal center. Value is latitude in degrees.
bufferedLongitude String number The buffer's geometric longitudinal center. Value is longitude in degrees.
bufferedAccuracy String number The buffer's average horizontal accuracy in meters. It may be possible to have a buffered accuracy equal to 0.0.

Satellite Data

If you have the Configuration option satelliteData to true, then for each satellite detected by the GPS the following data will be returned as JSON in the callback. This section provides a description of the attribute/value pairs that are returned.

Note: it's up to the GPS to determine whether or not any values will be provided for each property, this is especially true as the GPS warms up.

The plugin assigns a number to each satellites simply to make it easy to iterate through the JSON file. These numbers infer no actual relationship to a particular satellite. The PRN number is the actual satellite identifier.

Property Type Value Description
provider String "satellite" Let's you determine where this data is coming from.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
number String number Each satellite is assigned a sequential number for assisting with iterating the JSON. The numbers are simply a matter of convienence and have no other relationship with the satellite data.
PRN String integer Returns the PRN (pseudo-random number) for the satellite. For more info see this wikipedia article. Numbers 01 thru 32 represent GPS satellites. GLONASS uses higher numbers.
timeToFirstFix String milliseconds Returns the time required to receive the first fix since the most recent restart of the GPS engine.
usedInFix String boolean Indicates whether or not a satellite was used to determine a GPS fix.
azimuth String number Returns the azimuth of the satellite in degrees. The azimuth can vary between 0 and 360.
elevation String number Returns the elevation of the satellite above the horizon in degrees. The elevation can vary between 0 and 90.
hasEphemeris String boolean Returns true if the GPS engine has ephemeris data for the satellite.
hasAlmanac String boolean Returns true if the GPS engine has almanac data for the satellite.
SNR String number Returns the signal to noise ratio for the satellite.

Cellular Data

If you have the providers Configuration option set to cell or all then this API will attempt to retrieve low-level data about the cellular service.

This API is non-specific in that it will attempt to return most cellular data that is available on the device. To clarify: 'most' cellular data means there may be some operational aspects of the native Android API that either aren't currently included or were unintentionally missed.

Data will be returned under two circumstances:

A full set of detailed information is available via the android.telephony class documentation.

IMPORTANT Please make note of the following:

  • There are minimum device SDK requirements. API level 18 is the current minimum to take advantage of this specific functionality. The plugin will turn off this functionality if the API level is less than 18.
  • Activating cellular data may result in additional network charges for the user.
  • This information is not gauranteed.
  • This information may still be provided by the device even if Location is turned off.
  • The TelephonyManager API may not work correctly on all devices.
  • To make use of this data you'll need access to a cell tower database. We don't provide cell tower location data, however there are databases and services available. One example provider is the OpenCellId organization.
  • Take extra steps to protect the input data when using this API. Check for null or Integer.MAX_VALUE.

Examples:

	// cell_info wcdma - valid
	
	{
	"provider":"cell_info",
	"type":"wcdma",
	"timestamp":1461272187532,
	"cid":40052763,
	"lac":38995,
	"mcc":310,
	"mnc":410,
	"psc":217
	}
	
	// cell_location gsm - valid
	
	{
	"provider":"cell_location",
	"type":"gsm",
	"timestamp":1461274048131,
	"cid":40052763,
	"lac":38995,
	"psc":87
	}
	
	// cell_info wcdma - not valid
	// Problem: device returning max integer values.
	
	{
	"provider":"cell_info",
	"type":"wcdma",
	"timestamp":1461272187532,
	"cid":2147483647,
	"lac":2147483647,
	"mcc":2147483647,
	"mnc":2147483647,
	"psc":217
	}

cell_info CDMA Data

Property Type Value Description
provider String cell_info Let's you determine where this data is coming from.
type String cdma Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
baseStationId integer 0 - 65535 Base Station Id. Integer.MAX_VALUE if unknown.
latitude number +-90 Decimal degrees. Integer.MAX_VALUE if unknown.
longitude number +-180 Decimal degrees. Integer.MAX_VALUE if unknown.
networkId integer 0 - 65535 Network Id. Integer.MAX_VALUE if unknown.
systemId integer 0 - 32767 System Id. Integer.MAX_VALUE if unknown.

cell_info LTE Data

Property Type Value Description
provider String cell_info Let's you determine where this data is coming from.
type String lte Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
ci integer 0 - ~134,217,727 28-bit Cell Identity, Integer.MAX_VALUE if unknown.
mcc integer 0 - 999 3-digit Mobile Country Code. Integer.MAX_VALUE if unknown.
mnc integer 0 - 999 3-digit Mobile Network Code. Integer.MAX_VALUE if unknown.
pci integer 0 - 503 Physical Cell Id. Integer.MAX_VALUE if unknown.
tac integer 0 - 65535 16-bit Tracking Area Code. Integer.MAX_VALUE if unknown.

cell_info GSM Data

Property Type Value Description
provider String cell_info Let's you determine where this data is coming from.
type String gsm Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
cid integer 0 - 268435455 CID 28-bit UMTS Cell Identity described in TS 25.331. Integer.MAX_VALUE if unknown.
lac integer 0 - 65535 16-bit Location Area Code. Integer.MAX_VALUE if unknown.
mcc integer 0 - 999 3-digit Mobile Country Code. Integer.MAX_VALUE if unknown.
mnc integer 0 - 999 3-digit Mobile Network Code. Integer.MAX_VALUE if unknown.
psc integer 0 - 511 9-bit UMTS Primary Scrambling Code described in TS 25.331. Integer.MAX_VALUE if unknown.

cell_info WCDMA Data

Property Type Value Description
provider String cell_info Let's you determine where this data is coming from.
type String wcdma Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
cid integer 0 - 268435455 CID 28-bit UMTS Cell Identity described in TS 25.331. Integer.MAX_VALUE if unknown.
lac integer 0 - 65535 16-bit Location Area Code. Integer.MAX_VALUE if unknown.
mcc integer 0 - 999 3-digit Mobile Country Code. Integer.MAX_VALUE if unknown.
mnc integer 0 - 999 3-digit Mobile Network Code. Integer.MAX_VALUE if unknown.
psc integer 0 - 511 9-bit UMTS Primary Scrambling Code described in TS 25.331. Integer.MAX_VALUE if unknown.

cell_location CDMA Data

Property Type Value Description
provider String cell_location Let's you determine where this data is coming from.
type String cdma Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
baseStationId integer ? Base Station Id. -1 if unknown.
latitude number -90 - 90 Decimal degrees. Integer.MAX_VALUE if unknown.
longitude number -180 - 180 Decimal degrees. Integer.MAX_VALUE if unknown.
networkId integer ? Network Id. -1 if unknown.
systemId integer ? System Id. -1 if unknown.

cell_location GSM Data

Property Type Value Description
provider String cell_location Let's you determine where this data is coming from.
type String gsm Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
cid integer ? GSM cell id, -1 if unknown, 0xffff max legal value.
lac integer ? GSM Location Area Code-1 if unknown, 0xffff max legal value.
psc integer ? UMTS Primary Scrambling Code, -1 if unknown or GSM.

Signal Strength Data

Signal strength data will vary depending on your device and cellular providers. The data is derived from either a change in SignalStrength or a change in CellInfo data.

signalStrength

This information is delivered when the functionality is available on a device, and only when the signal strength changes and the JavaScript application has specified the signalStrength option as true. Note, there can be many changes in signal strength per minute.

More information can be derived from the Android SDK source code.

If you see any of the following in AndroidStudio debugger, they are default values and may indicate the device isn't reporting anything valid for those properties:

	// Default values
	mGsmSignalStrength = 99;
    mGsmBitErrorRate = -1;
    mCdmaDbm = -1;
    mCdmaEcio = -1;
    mEvdoDbm = -1;
    mEvdoEcio = -1;
    mEvdoSnr = -1;
    mLteSignalStrength = 99;

Example console.log:

// Contains both invalid and valid values
"Signal Strength JSON: 
		{
		"provider":"signal_strength",
		"type":"signal_strength",			
		"timestamp":1473784636478,
		"cdmaDbm":-120,
		"cdmaEcio":-160,
		"evdoDbm":-120,
		"evdoEcio":-1,
		"evdoSnr":-1,
		"gsmBitErrorRate":0,
		"gsmSignalStrength":11,
		"level":3,
		"isGSM":true
		}"
Property Type Value Description
provider String signal_strength Let's you determine where this data is coming from.
type String signal_strength Depends on the device, cell service provider and how many radios are active. It can return multiple values.
timestamp number milliseconds Time right now based on the Calendar whose locale is determined by system settings. Gregorian calendar assumes counting begins at the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. For more info see java.util.Calendar.
cdmaDbm integer ? CDMA RSSI value in dBm.
cdmaEcio integer ? CDMA Ec/Io value in dB*10.
evdoDbm integer ? EVDO RSSI value in dBm.
evdoEcio integer ? EVDO Ec/Io value in dB*10.
evdoSnr integer ? Signal to noise ratio.
gsmBitErrorRate integer 0-7, 99 GSM bit error rate as defined in TS 27.007 8.5.
gsmSignalStrength integer 0-31, 99 GSM Signal Strength as defined in TS 27.007 8.5.
level integer 0 - 4 An abstract level value for the overall signal strength.

The integer value represents the general signal quality. This may take into account many different radio technology inputs. 0 represents very poor signal strength while 4 represents a very strong signal strength.

cellSignalStrengthCdma

This information is provided when a change is detected in the CellInfoCdma data and the JavaScript application has specified the signalStrength option as true.

This information will be returned as part of the cell_info payload.

More information can be derived from the Android SDK source code.

If you see any values in AndroidStudio debugger that represent Integer.MAX_VALUE, for example mCdmaEcio = 2147483647, then most likely the device isn't reporting anything valid for that property.

Property Type Value Description
asuLevel integer 0 - 97, 99 Signal level as an asu value. 99 means unknown.
cdmaDbm integer ? CDMA RSSI value in dBm. Value >= -75 is great, >= - 85 is good, >= - 95 is moderate, >= - 100 poor. A value of -120 may indicate your device isn't reporting a value.
cdmaEcio integer ? CDMA Ec/Io value in dB*10. Value >= -90 is great, >= -110 is good, >= -130 is moderate, >= -150 is poor. A value of -160 may indicate your device isn't reporting a value.
cdmaLevel integer 0 - 4 CDMA as a level. A rough comparision between cdmaDbm and cdmaEcio.
dbm integer ? Signal strength as dBm.
evdoDbm integer ? EVDO RSSI value in dBm. Value >= -65 is great, >= -75 is good, >= -90 is moderate, >= -105 is poor. A value of -120 may indicate your device isn't reporting a value.
evdoEcio integer ? EVDO Ec/Io value in dB*10.
evdoLevel integer 0 - 4 A rough comparison between evdoDbm and evdoSnr.
evdoSnr integer 0 - 8 Valid values are 0-8. 8 is the highest signal to noise ratio.
level integer 0 - 4 Derived from a rough comparison between evdoLevel and cdmaLevel.

cellSignalStrengthWcdma

This information is provided when a change is detected in the CellInfoWcdma data and the JavaScript application has specified the signalStrength option as true.

This information will be returned as part of the cell_info payload.

More information can be derived from the Android SDK source code.

If you see any values in AndroidStudio debugger that represent Integer.MAX_VALUE, for example dBm = 2147483647, then most likely the device isn't reporting anything valid for that property.

Example console.log:

// Contains invalid values
"cell_info JSON: 
	{
	"provider":"cell_info",
	"type":"wcdma",
	"timestamp":1473784633808,
	"cid":2147483647,
	"lac":2147483647,
	"mcc":2147483647,
	"mnc":2147483647,
	"psc":150,
	"signalStrength":
		{
		"asuLevel":5,
		"dbm":-103,
		"level":2
		}
	}"

Example logcat:

// Contains valid values
CellInfoWcdma:
	{
	mRegistered=YES 
	mTimeStampType=oem_ril 
	mTimeStamp=608501062167412ns 
	CellIdentityWcdma:
		{ 
		mMcc=310
		mMnc=410 
		mLac=31251 
		mCid=65535 
		mPsc=100
		} 
	CellSignalStrengthWcdma: 
		ss=10 
		ber=99
	}
Property Type Value Description
asuLevel integer 0 - 31, 99 Get the signal level as an asu value between 0..31, 99 is unknown. Asu is calculated based on 3GPP RSRP. If asu = 0 (-113dB or less) this represents a very weak signal.
dbm integer ? Signal strength as dBm.
level integer 0 - 4 A rough analysis of signal strength. Zero means none or unknown, one is poor, two is moderate, three is good, four is great.

cellSignalStrengthGsm

This information is provided when a change is detected in the CellInfoGsm data and the JavaScript application has specified the signalStrength option as true.

This information will be returned as part of the cell_info payload.

More information can be derived from the Android SDK source code.

If you see any values in AndroidStudio debugger that represent Integer.MAX_VALUE, for example dBm = 2147483647, then most likely the device isn't reporting anything valid for that property.

Property Type Value Description
asuLevel integer 0 - 31, 99 Get the signal level as an asu value between 0..31, 99 is unknown. Asu is calculated based on 3GPP RSRP. If asu = 0 (-113dB or less) this represents a very weak signal.
dbm integer ? Signal strength as dBm. Max value of 2147483647 indicates the device isn't reporting a level.
level integer 0 - 4 A rough analysis of signal strength. Zero means none or unknown, one is poor, two is moderate, three is good, four is great.

cellSignalStrengthLte

This information is provided when a change is detected in the CellInfoLte data and the JavaScript application has specified the signalStrength option as true.

This information will be returned as part of the cell_info payload.

More information can be derived from the Android SDK source code.

If you see any values in AndroidStudio debugger that represent Integer.MAX_VALUE, for example mTimingAdvance = 2147483647, then most likely the device isn't reporting anything valid for that property.

Property Type Value Description
asuLevel integer 0 - 97, 99 an asu value between 0..97, 99 is unknown. Asu is calculated based on 3GPP RSRP.
dbm integer ? Signal strength as dBm.
level integer 0 - 4 A rough analysis of signal strength. Zero means none or unknown, one is poor, two is moderate, three is good, four is great. A rough comparison between RSSNR (Reference Signal Signal to Noise Ratio) and RSRP (Reference Signal Received Power).
timingAdvance integer Derived directly from the phone, this represents a MAC Control Element (MAC CE) used to control the timing of the uplink signal transmission. Max value of 2147483647 indicates the device isn't reporting an valid value.