com.webos.service.location

Note
This API has been available since API level 11.

API Summary

Provides basic location services for single or multiple position fixes. This service connects to Luna bus to interact with other system components (e.g. apps, services) that require location services.

Overview of the API

Decides the type of location service provider based on the request parameters. Once a suitable location service provider is selected, the service uses the location service provider to construct positions fix(es). webOS uses the following location service providers for position fixing:

GPS / AGPS
WPS / CellID.
Geocoding / Reverse geocoding (prerequisites : check "Google Geocoding API Key" section below)
Mock: Enables to test location features with fake information.

Note: The location service provider is also called a location source and location handler.

Google Geocoding API Key

To use the GeoCoding functionality, you must have the Geocoding API keys to authenticate requests associated with your project for usage and billing purposes. You must perform the following steps:

Sign up and create a billing account with Google Maps Platform.
Follow steps to get GeoCoding API key.
Encrypt generated GeoCoding key with base64 encoding, execute following command in terminal
$ echo "GEOCODING_KEY" | base64
<<ENCRYPTED_GEOCODING_KEY>>
Write encrypted key in file /etc/location/wsp.conf present on your device. Create following file:
{
  "wpsName": "google",
  "apiKey": "ENCRYPTED_GEOCODING_KEY",
  "services": [
  {
  "features": ["geocode", "reverseGeocode"],
  "url": "https://maps.googleapis.com/maps/api/geocode/json?"
  }
  ]
}
If the location service is already running, reboot the device.

Methods

getAllLocationHandlers

ACG: location.query

Added: API level 11

Description

Gets a list of the available location handlers, along with each handler's attributes including name and state.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true: Get notifications. false: Notifications are not required. Default: true

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications.

Possible values are:

true: Get notifications.
false: Notifications are not required.

Default: true

Call Returns

Name	Required	Type	Description
handlers	Optional	Object array: handler	Contains each handler's name and state in an object array.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name	Required	Type	Description
handler	Optional	Object array: handler	Contains each handler's name and state in an object array.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getAllLocationHandlers '{}'

Response:

{
"errorCode":0,
"returnValue":true,
"handlers":[
{
"state":true,
"name":"gps"
},
{
"state":true,
"name":"network"
}
]
}

getGeoCodeLocation

ACG: location.query

Added: API level 11

Description

Transforms a given street address or other description of a location into a coordinate (latitude, longitude).

Important points:

Supports Google Geocoding API.
Prerequisite:
- Set up the Geocoding API key as described in Google Geocoding API Key.
- Enable network location provider state by:
  # luna-send -f -n 1 luna://com.webos.service.location/setState '{"Handler":"network","state":true}'
For more details, see Google official documents.

Parameters

Name	Required	Type	Description
address	Required	String	Indicates formatted user-readable address lines. Note: Either address or component parameter is required for the getGeoCodeLocation service to transform the address successfully.
components	Required	Object array: components	Indicates the component filter required. Note: Either address or component parameter is required for the getGeoCodeLocation service to transform the address successfully.
bounds	Optional	Object array: bounds	The bounding box of the viewport within which to bias geocode results more prominently.
language	Optional	String	Indicates the language through which the results are displayed.
region	Optional	String	Indicates the region code, specified as a ccTLD ("top-level domain") a two-character value.

Call Returns

Name	Required	Type	Description
response	Optional	object	Indicates the response received from google geocoding service.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getGeoCodeLocation '{
"address":"221-2, Yangjae 2-dong, Seocho-gu, Seoul, Korea"
}'

Response:

getGpsSatelliteData

ACG: location.query

Added: API level 30

Description

Gets the satellite information.

Prerequisite: The GPS feature of the device has to be powered ON.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Indicates whether to subscribe to related events. Possible values are: true: Subscribe. false: Do not subscribe. Default: true

Name

Required

Type

Description

Optional

Boolean

Indicates whether to subscribe to related events.

Possible values are:

true: Subscribe.
false: Do not subscribe.

Default: true

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
visibleSatellites	Optional	Number	Indicates the number of visible (detectable) satellites.
satellites	Optional	Object array: satellite	Contains each satellite's information in an object array.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
visibleSatellites	Optional	Number	Indicates the number of visible (i.e., detectable) satellites.
satellites	Optional	Object array: satellite	Contains each satellite's information in an object array.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getGpsSatelliteData '{}'

Response:

{
"visibleSatellites":25,
"satellites":[
{
"prn":1,
"index":0,
"azimuth":64,
"snr":0,
"elevation":15,
"usedInFix":false,
"hasAlmanac":true,
"hasEphemeris":true
},
{
"prn":2,
"index":1,
"azimuth":265,
"snr":0,
"elevation":11,
"usedInFix":false,
"hasAlmanac":true,
"hasEphemeris":true
},
{
"prn":68,
"index":24,
"azimuth":49,
"snr":0,
"elevation":49,
"usedInFix":false,
"hasAlmanac":false,
"hasEphemeris":false
}
],
"errorCode":0,
"returnValue":true
}

getGpsStatus

ACG: location.query

Added: API level 11

Description

Gets the current status of the GPS engine. Used for notifying device users that the GPS engine has started or stopped.

GPS engine is started when a method that needs the engine to work is called.
GPS engine is turned off when all the received requests have been handled or canceled, thus when there is nothing left for it to do. System-wise, when all luna-commands related to the engine starting are canceled, the GPS engine is powered OFF.

Prerequisite: For getGpsStatus method to work, the GPS feature of the device has to be powered ON.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true: Get notifications. false: Notifications are not required. Default: true

Name

Required

Type

Description

Optional

Boolean

Subscribe for notifications.

Possible values are:

true: Get notifications.
false: Notifications are not required.

Default: true

Call Returns

Name	Required	Type	Description
state	Optional	Boolean	Indicates the status of a GPS engine. Possible values are : true: GPS engine has been started. false: GPS engine has been stopped.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name	Required	Type	Description
state	Optional	Boolean	Indicates the status of a GPS engine. Possible values are: true: GPS engine has been started. false: GPS engine has been stopped.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getGpsStatus '{}'

Response:

{
"state":false,
"errorCode":0,
"returnValue":true
}

Subscription response:

{
"state":false,
"errorCode":0,
"returnValue":true
}

getLocationHandlerDetails

ACG: location.query

Added: API level 11

Description

Gets the details of the given location handler (Location service provider).

Parameters

Name	Required	Type	Description
Handler	Required	String	Indicates the location of the service provider. Possible values are: gps network

Name

Required

Type

Description

Handler

Required

String

Indicates the location of the service provider.

Possible values are:

gps
network

Call Returns

Name	Required	Type	Description
accuracy	Optional	Number	Accuracy of the requested location. 1: High 2: Medium 3: Low
powerRequirement	Optional	Number	Power requirement for TTFF (Time To First Fix): 1: High 2: Medium 3: Low
requiresNetwork	Optional	Boolean	Indicates whether the location handler requires a network. true: Network is required. false: Network is not required.
requiresCell	Optional	Boolean	Indicates whether the location handler requires a cell. true: Cell is required. false: Cell is not required.
monetaryCost	Optional	Boolean	Indicates whether the location handler is allowed to charge the user. true: Charging allowed. false: Charging is not allowed.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getLocationHandlerDetails '{
"Handler":"gps"
}'

Response:

{
"requiresNetwork":false,
"requiresCell":false,
"monetaryCost":false,
"powerRequirement":1,
"errorCode":0,
"returnValue":true,
"accuracy":1
}

getLocationUpdates

ACG: location.query

Added: API level 11

Description

Requests a single location fix based on the given criteria. If the subscription value is set to true, it requests for continuous location fixes.

Note:

Timeout period for getLocationUpdates is 12 minutes. This method will enable location handlers according to the criteria passed in the request.
setState method should be used to enable a handler.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true: Get notifications. false: Notifications are not required. It will however provide only a single response, but only when updates are available Default: true
minimumInterval	Optional	Number	Indicates the minimum time interval between location updates. Possible Range: 0 <= minimumInterval <= 3600000(in milliseconds).
minimumDistance	Optional	Number	Indicates the minimum distance between location updates. Possible Range: 0 <= minimumDistance <= 60000(in metres).
Handler	Optional	String	Indicates the type of location service provider. Possible values are : "gps" "network" "passive"
responseTimeout	Optional	Number	Indicates the response timeout (time until the first position fix is returned ). Possible Range: 0 <= responseTimeout <= 720(in seconds).

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.
timestamp	Optional	Number (int64_t)	Indicates the time at which the location fix was created(in milliseconds).
latitude	Optional	Number (double)	Indicates latitude. Possible range : -90.0 ~ 90.0(in degrees).
longitude	Optional	Number (double)	Indicates longitude. Possible Range: -180.0 ~ 180.0(in degrees).
altitude	Optional	Number (double)	Indicates the altitude above sea level(in meters), returns -1 if the altitude is unknown.
direction	Optional	Number (double)	Indicates the horizontal direction traveled by the device (in degrees), returns -1 if unknown. Possible Range: 0.0 ~ 360.0 (in degrees).
speed	Optional	Number (double)	Indicates the value of Velocity overground(in meters/second),returns -1 if unknown.
horizAccuracy	Optional	Number (double)	Indicates the estimated horizontal accuracy value of this location(in meters), returns -1 if unknown.
vertAccuracy	Optional	Number (double)	Indicates the estimated vertical accuracy value of this location (in meters), returns -1 if unknown.

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.
timestamp	Optional	Number (int64_t)	Indicates the time at which the location fix was created(in milliseconds).
latitude	Optional	Number (double)	Indicates latitude. Possible Range: -90.0 ~ 90.0(in degrees).
longitude	Optional	Number (double)	Indicates longitude. Possible Range: -180.0 ~180.0(in degrees).
altitude	Optional	Number (double)	Indicates the altitude value above sea level(in meters), returns -1 if unknown.
direction	Optional	Number (double)	Indicates the horizontal direction traveled by the device, returns -1 if unknown. Possible Range: 0.0 ~ 360.0(in degrees).
speed	Optional	Number (double)	Indicates the device velocity over ground.(meters/second), returns -1 if unknown.
horizAccuracy	Optional	Number (double)	Indicates the estimated horizontal accuracy of this location (in meters), returns -1 if unknown.
vertAccuracy	Optional	Number (double)	Indicates the estimated vertical accuracy of a location (in meters), returns -1 if unknown.

Example

Example

# luna-send -f -n 1 luna://com.webos.service.location/getLocationUpdates '{
"Handler":"gps"
}'

Response: Only subscription response is provided. This will be available only when location data is available.

Subscription response:

{
"returnValue":true,
"speed":-1,
"longitude":127.034097,
"errorCode":0,
"horizAccuracy":73,
"vertAccuracy":-1,
"direction":-1,
"timestamp":1410827340157,
"altitude":-1,
"latitude":37.460605
}

Example

# luna-send -f -i luna://com.webos.service.location/getLocationUpdates '{
"subscribe":true,
"Handler":"gps",
"minimumDistance":100,
"minimumInterval":20000
}'

Response: Only subscription response is provided. This will be available only when location data is available.

Subscription response:

{
"returnValue":true,
"errorCode":0,
"timestamp":1392866287000,
"latitude":37.460523,
"longitude":127.034235,
"altitude":40,
"direction":162,
"speed":-1,
"horizAccuracy":20,
"vertAccuracy":-1
},
{
"returnValue":true,
"errorCode":0,
"timestamp":139286777000,
"latitude":36.4656443,
"longitude":128.035654,
"altitude":41,
"direction":163,
"speed":-1,
"horizAccuracy":21,
"vertAccuracy":-1
}

getNmeaData

ACG: location.query

Added: API level 30

Description

Gets a NMEA sentence from a GPS receiver.

Parameters

Name	Required	Type	Description
subscribe	Optional	Boolean	Indicates whether to subscribe to related events. true: Subscribe. false: Do not subscribe. Default: true

Name

Required

Type

Description

Optional

Boolean

Indicates whether to subscribe to related events.

true: Subscribe.
false: Do not subscribe.

Default: true

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
timestamp	Optional	Number (int64_t)	Indicates the time when a raw NMEA sentence is received from the satellite(in milliseconds).
nmea	Optional	String	Contains the NMEA sentence.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
timestamp	Optional	Number (int64_t)	Indicates the time when a raw NMEA sentence is received from the satellite(in milliseconds).
nmea	Optional	String	Contains the NMEA sentence.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getNmeaData '{}'

Response:

{
"timestamp":1410848850316,
"nmea":"$GPGSV,4,1,13,01,13,067,,02,13,268,,04,33,060,,06,46,286,*7A",
"errorCode":0,
"returnValue":true
}

Subscription response:
{
"timestamp":1410848850316,
"nmea":"$GPGSV,4,1,13,01,13,067,,02,13,268,,04,33,060,,06,46,286,*7A",
"errorCode":0,
"returnValue":true
}

{
"timestamp":1410848862346,
"nmea":"$GPGSV,4,2,13,01,13,069,,02,13,265,,04,33,060,,03,46,286,*7A",
"errorCode":0,
"returnValue":true
}

getReverseLocation

ACG: location.query

Added: API level 11

Description

Transforms a given coordinate (latitude, longitude) into a (partial) address.

Note: The amount of detail in a reverse geocoded location description may vary. For example, one location might contain the full street address of the closest building, while another location might contain only a city name and postal code.

Important points:

Supports Google Reverse Geocoding API.
Prerequisite:
- Set up the Geocoding API key as described in Overview of the API > Google Geocoding API Key.
- Enable network location provider state by:
  # luna-send -f -n 1 luna://com.webos.service.location/setState '{"Handler":"network","state":true}'
For more details, see Google official documents.

Parameters

Name	Required	Type	Description
latitude	Required	Number (double)	Indicates latitude. Possible range: -90.0 ~ 90.0(in degrees).
longitude	Required	Number (double)	Indicates longitude. Possible range: -180.0 ~ 180.0.(in degrees).
language	Optional	String	Indicates the language in which the address(result) is returned.
result_type	Optional	array	Indicates the type of address.
location_type	Optional	array	Indicates the type of location.

Call Returns

Name	Required	Type	Description
response	Optional	object	Indicates the response received from Google geocoding.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getReverseLocation '{
"latitude":37.461192,
"longitude":127.035238
}'

Response:

{
"errorCode":0,
"returnValue":true,
"response":{
"status":"OK",
"results":[
{
"geometry":{
"location":{
"lng":127.0350491,
"lat":37.4615406
},
"viewport":{
"northeast":{
"lng":127.0510565,
"lat":37.4703969
},
"southwest":{
"lng":127.0190417,
"lat":37.4526833
}
},
"location_type":"ROOFTOP"
},
"formatted_address":"221-2 Yangjae-dong, Seocho-gu, Seoul, South Korea",
"types":[
"premise",
"political"
],
"address_components":[
{
"long_name":"221-2",
"short_name":"221-2",
"types":[
"premise",
"political"
]
},
{
"long_name":"Yangjae-dong",
"short_name":"Yangjae-dong",
"types":[
"sublocality_level_2",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
},
{
"long_name":"137-130",
"short_name":"137-130",
"types":[
"postal_code"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.034843,
"lat":37.4614812
},
"viewport":{
"northeast":{
"lng":127.0361919802915,
"lat":37.4628301802915
},
"southwest":{
"lng":127.0334940197085,
"lat":37.4601322197085
}
},
"bounds":{
"northeast":{
"lng":127.0353746,
"lat":37.4618054
},
"southwest":{
"lng":127.0343114,
"lat":37.461157
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Yangjae-daero 11-gil, Seocho-gu, Seoul, South Korea",
"types":[
"sublocality_level_4",
"sublocality",
"political"
],
"address_components":[
{
"long_name":"Yangjae-daero 11-gil",
"short_name":"Yangjae-daero 11-gil",
"types":[
"sublocality_level_4",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
},
{
"long_name":"137-130",
"short_name":"137-130",
"types":[
"postal_code"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.0381702,
"lat":37.4731977
},
"viewport":{
"northeast":{
"lng":127.0510671,
"lat":37.485449
},
"southwest":{
"lng":127.0210832,
"lat":37.4518118
}
},
"bounds":{
"northeast":{
"lng":127.0510671,
"lat":37.485449
},
"southwest":{
"lng":127.0210832,
"lat":37.4518118
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Yangjae-dong, Seocho-gu, Seoul, South Korea",
"types":[
"sublocality_level_2",
"sublocality",
"political"
],
"address_components":[
{
"long_name":"Yangjae-dong",
"short_name":"Yangjae-dong",
"types":[
"sublocality_level_2",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
},
{
"long_name":"137-130",
"short_name":"137-130",
"types":[
"postal_code"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.0373502,
"lat":37.4732704
},
"viewport":{
"northeast":{
"lng":127.0510671,
"lat":37.485449
},
"southwest":{
"lng":127.0210832,
"lat":37.4518118
}
},
"bounds":{
"northeast":{
"lng":127.0510671,
"lat":37.485449
},
"southwest":{
"lng":127.0210832,
"lat":37.4518118
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Yangjae-dong, Seocho-gu, Seoul, South Korea",
"types":[
"postal_code"
],
"address_components":[
{
"long_name":"137-130",
"short_name":"137-130",
"types":[
"postal_code"
]
},
{
"long_name":"Yangjae-dong",
"short_name":"Yangjae-dong",
"types":[
"sublocality_level_2",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.0454009,
"lat":37.4449319
},
"viewport":{
"northeast":{
"lng":127.0639699,
"lat":37.4785793
},
"southwest":{
"lng":127.0293703,
"lat":37.4259627
}
},
"bounds":{
"northeast":{
"lng":127.0639699,
"lat":37.4785793
},
"southwest":{
"lng":127.0293703,
"lat":37.4259627
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Yangjae 2(i)-dong, Seocho-gu, Seoul, South Korea",
"types":[
"postal_code"
],
"address_components":[
{
"long_name":"137-132",
"short_name":"137-132",
"types":[
"postal_code"
]
},
{
"long_name":"Yangjae 2(i)-dong",
"short_name":"Yangjae 2(i)-dong",
"types":[
"sublocality_level_2",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.0413547,
"lat":37.4707419
},
"viewport":{
"northeast":{
"lng":127.0639699,
"lat":37.4785793
},
"southwest":{
"lng":127.0293703,
"lat":37.4259627
}
},
"bounds":{
"northeast":{
"lng":127.0639699,
"lat":37.4785793
},
"southwest":{
"lng":127.0293703,
"lat":37.4259627
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Yangjae 2(i)-dong, Seocho-gu, Seoul, South Korea",
"types":[
"sublocality_level_2",
"sublocality",
"political"
],
"address_components":[
{
"long_name":"Yangjae 2(i)-dong",
"short_name":"Yangjae 2(i)-dong",
"types":[
"sublocality_level_2",
"sublocality",
"political"
]
},
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
},
{
"long_name":"137-130",
"short_name":"137-130",
"types":[
"postal_code"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.0324112,
"lat":37.4837121
},
"viewport":{
"northeast":{
"lng":127.0948845,
"lat":37.5260893
},
"southwest":{
"lng":126.9795193,
"lat":37.4259627
}
},
"bounds":{
"northeast":{
"lng":127.0948845,
"lat":37.5260893
},
"southwest":{
"lng":126.9795193,
"lat":37.4259627
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Seocho-gu, Seoul, South Korea",
"types":[
"sublocality_level_1",
"sublocality",
"political"
],
"address_components":[
{
"long_name":"Seocho-gu",
"short_name":"Seocho-gu",
"types":[
"sublocality_level_1",
"sublocality",
"political"
]
},
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
}
]
},
{
"geometry":{
"location":{
"lng":126.9779692,
"lat":37.566535
},
"viewport":{
"northeast":{
"lng":127.1823,
"lat":37.6956
},
"southwest":{
"lng":126.7968,
"lat":37.4346
}
},
"bounds":{
"northeast":{
"lng":127.18359,
"lat":37.7017495
},
"southwest":{
"lng":126.7645827,
"lat":37.4259627
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"Seoul, South Korea",
"types":[
"locality",
"political"
],
"address_components":[
{
"long_name":"Seoul",
"short_name":"Seoul",
"types":[
"locality",
"political"
]
},
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
}
]
},
{
"geometry":{
"location":{
"lng":127.766922,
"lat":35.907757
},
"viewport":{
"northeast":{
"lng":129.584671,
"lat":38.6169312
},
"southwest":{
"lng":124.608139,
"lat":33.1061096
}
},
"bounds":{
"northeast":{
"lng":130.9232178,
"lat":38.6169312
},
"southwest":{
"lng":124.608139,
"lat":33.1061096
}
},
"location_type":"APPROXIMATE"
},
"formatted_address":"South Korea",
"types":[
"country",
"political"
],
"address_components":[
{
"long_name":"South Korea",
"short_name":"KR",
"types":[
"country",
"political"
]
}
]
}
]
}
}

getState

ACG: location.query

Added: API level 11

Description

Gets the current state of the given handler. Application settings can use this to update location settings.

Parameters

Name	Required	Type	Description
Handler	Required	String	Indicates the type of location service provider. Possible values are : gps network
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true: Get notifications. false: Notifications are not required. Default: true

Name

Required

Type

Description

Handler

Required

String

Indicates the type of location service provider.

Possible values are :

gps
network

Optional

Boolean

Subscribe for notifications.

Possible values are:

true: Get notifications.
false: Notifications are not required.

Default: true

Call Returns

Name	Required	Type	Description
state	Optional	Number	Indicates the state of the handler. Possible values are : 0: Disabled 1: Enabled
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name	Required	Type	Description
state	Optional	Number	Indicates the state of the handler. Possible values are : 0: Disabled. 1: Enabled.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/getState '{"Handler":"network"}'

Response:

{
"state":1,
"errorCode":0,
"returnValue":true
}

Subscription responses:

{
"state":1,
"errorCode":0,
"returnValue":true
},
{
"state":0,
"errorCode":0,
"returnValue":true
}

mock/disable

ACG: location.operation

Added: API level 11

Description

Disables the mock location of the given provider.

Parameters

Name	Required	Type	Description
name	Required	String	Indicates the name of the location service provider. Possible values are : gps network

Name

Required

Type

Description

name

Required

String

Indicates the name of the location service provider.

Possible values are :

gps
network

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Required

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.location/mock/disable'{
"name":"gps"
}'

Response:

{
"returnValue":true,
"errorCode":0
}

mock/enable

ACG: location.operation

Added: API level 11

Description

Enables a mock location of the given provider.

Parameters

Name	Required	Type	Description
name	Required	String	Name of the location service provider. Possible values: gps network

Name

Required

Type

Description

name

Required

String

Name of the location service provider.

Possible values:

gps
network

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Required

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.location/mock/enable '{
"name":"gps"
}'

Response:

{
"returnValue":true,
"errorCode":0
}

mock/setLocation

ACG: location.operation

Added: API level 11

Description

Sets a mock location for the given provider.

Parameters

Name	Required	Type	Description
name	Required	String	Indicates the name of the location service provider. Possible values are : gps network NOTE: If 'name' field is set as network so for every mock/setLocation we need to call getLocationUpdates API with subscription false. (Since it different from GPS handler we wont get continuous reponse when subscription is true)
location	Required	Object: location	Indicates the information about a mock location.

Name

Required

Type

Description

name

Required

String

Indicates the name of the location service provider.

Possible values are :

gps
network

NOTE: If 'name' field is set as network so for every mock/setLocation we need to call getLocationUpdates API with subscription false. (Since it different from GPS handler we wont get continuous reponse when subscription is true)

location

Required

Object: location

Indicates the information about a mock location.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Required

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.location/mock/setLocation '{
"name":"gps",
"location":
{
"speed":-1,
"longitude":127.034097,
"horizAccuracy":30,
"verAccuracy":2,
"heading":-1,
"timestamp":1410827340157,
"altitude":-1,
"latitude":37.460605
}
}'

Response:

{
"returnValue":true,
"errorCode":0
}

setState

ACG: location.operation

Added: API level 11

Description

Enables or disables a location service provider in the setting menu.

Parameters

Name	Required	Type	Description
Handler	Required	String	Indicates the type of location service provider. Possible values are : gps network
state	Required	Boolean	Indicates whether to enable the location of the service provider. Possible values are: true: Enables the given location service provider. false: Disables the given location service provider.

Name

Required

Type

Description

Handler

Required

String

Indicates the type of location service provider.

Possible values are :

gps
network

state

Required

Boolean

Indicates whether to enable the location of the service provider.

Possible values are:

true: Enables the given location service provider.
false: Disables the given location service provider.

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Required	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Required

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -f -n 1 luna://com.webos.service.location/setState '{
"Handler":"gps",
"state":true
}'

Response:

{
"errorCode":0,
"returnValue":true
}

Objects

bounds

Indicates the bounding box of the viewport within which to bias geocode results more prominently.

Name	Required	Type	Description
southwestLat	Required	Number (double)	Indicates the latitude of southwest direction.
southwestLon	Required	Number (double)	Indicates longitude of southwest direction.
northeastLat	Required	Number (double)	Indicates latitude of northeast direction.
northeastLon	Required	Number (double)	Indicates longitude of northeast direction.

components

Indicates the component filter for which a geocode has to be generated.

Name	Required	Type	Description
route	Optional	String	Indicates long or short name of a route.
locality	Optional	String	Indicates the locality.
administrative_area	Optional	String	Indicates the administrative area.
postal_code	Optional	String	Indicates the postal code.
country	Optional	String	Indicates the country name or a two letter ISO 3166-1 country code.

handler

Contains a handler's name and state.

Name	Required	Type	Description
name	Required	String	Indicates the name of the handler.
state	Required	Boolean	Indicates the state of the handler.

location

Indicates the object of location for mock.

Name	Required	Type	Description
speed	Required	Number (double)	Speed, in meters/second overground.
longitude	Required	Number (double)	Indicates longitude. Possible Range: -180.0 ~180.0(in degrees).
horizAccuracy	Required	Number (double)	Indicates the accuracy of this location(in meters).
verAccuracy	Required	Number (double)	Indicates the accuracy of this location(in meters).
heading	Required	Number (double)	Indicates the horizontal direction traveled by the device. Possible Range: -360.0 ~360.0(in degrees).
timestamp	Required	Number (int8_t)	Indicates the time when the location fix was created(in milliseconds).
altitude	Required	Number (double)	Indicates the altitude(in meters) above the WGS 84 reference ellipsoid.
latitude	Required	Number (double)	Indicates latitude. Possible Range: -90.0 ~90.0(in degrees).

satellite

Contains satellite information.

Name	Required	Type	Description
index	Required	Number	Indicates the index of the satellite.
azimuth	Required	Number (double)	Indicates the azimuth value of the satellite(in degrees).
elevation	Required	Number (double)	Indicates the elevation of the satellite(in degrees).
prn	Required	Number	Indicates the PRN (pseudo-random number) for the satellite.
snr	Required	Number (double)	Indicates the signal to noise ratio for the satellite.
hasAlmanac	Required	Boolean	Indicates whether the GPS engine has almanac data for the satellite. Possible values are : true: GPS engine has almanac data for the satellite. false: GPS engine has no almanac data for the satellite.
hasEphemeris	Required	Boolean	Indicates whether the GPS engine has ephemeris data for the satellite. true: GPS engine has ephemeris data for the satellite. false: GPS engine has no ephemeris data for the satellite.
usedInFix	Required	Boolean	Indicates whether the satellite was used by the GPS engine in calculating the most recent GPS fix. true: Satellite was used. false: Satellite was not used.

API Error Codes Reference

Error Code	Error Text	Error Description
0	Success	Indicates that the operation was successfully executed.
1	Time out	The operation's return is overtime.
3	Unkown error	Indicates that the reason for the occurrence of the error is unknown/ambiguous.
5	Location source is off	Indicates that the location source is unavailable to get the location information.
10	Invalid input	Indicates the input provided is invalid.
11	No internet connection	Indicates that the current internet connection is closed (unavailable).
13	Out of memory	Indicates that the device is out of memory.
21	Failed to read the WSP Configuration file	Indicates that the configuration file wsp.conf is missing or it has an invalid JSON.
22	Failed to get the WSP name in conf file	Indicates that the wspName file is missing or its value is empty.
23	Failed to get the WSP API Key in conf file	Indicates that apiKey file is missing or its value is empty.
24	Failed to get the WSP service list in conf file	Indicates that the services file is missing or its array has no members.
25	Failed to get the WSP supported features list in conf file	Indicates that the features file is missing or its array has no members or present members are empty.
26	Failed to get the WSP feature's URL in conf file	Indicates that url file is missing or its value is empty.