com.webos.service.location

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:

    1. Sign up and create a billing account with Google Maps Platform.
    2. Follow steps to get GeoCoding API key.
    3. Encrypt generated GeoCoding key with base64 encoding, execute following command in terminal
      echo "GEOCODING_KEY" | base64
      <<ENCRYPTED_GEOCODING_KEY>>
    4. 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?"
              }
          ]
      }

    5. If the location service is already running, reboot the device.

    Methods

    getAllLocationHandlers

    Description

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

    Parameters

    Name

    Required

    Type

    Description

    subscribeOptionalboolean

    Subscribe for notifications.

    Possible values are:

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

    Default: true

    Call Returns

    Name

    Required

    Type

    Description

    handlersOptionalObject array: handler

    Contains each handler's name and state in an object array.

    returnValueRequiredboolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Subscription Returns

    Name

    Required

    Type

    Description

    handlerOptionalObject array: handler

    Contains each handler's name and state in an object array.

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

    # 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

    Description

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

    Important points:

    Parameters

    Name

    Required

    Type

    Description

    addressRequiredstring

    Indicates formatted user-readable address lines.

    Note: Either address or component parameter is required for the getGeoCodeLocation service to transform the address successfully.

    componentsRequiredObject array: components

    Indicates the component filter required.

    Note: Either address or component parameter is required for the getGeoCodeLocation service to transform the address successfully.

    boundsOptionalObject array: bounds

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

    languageOptionalstring

    Indicates the language through which the results are displayed.

    regionOptionalstring

    Indicates the region code, specified as a ccTLD ("top-level domain") a two-character value.

    Call Returns

    Name

    Required

    Type

    Description

    responseOptionalobject

    Indicates the response received from google geocoding service.

    returnValueRequiredboolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Example

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

    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 2(i)-dong, Seocho-gu, Seoul, South Korea",
                "partial_match":true,
                "address_components":[
                   {
                      "long_name":"221-2",
                      "short_name":"221-2",
                      "types":[
                         "premise",
                         "political"
                      ]
                   },
                   {
                      "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"
                      ]
                   }
                ],
                "types":[
                   "premise",
                   "political"
                ]
             }
          ]
       }
    }

    getGpsStatus

    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

    subscribeOptionalBoolean

    Subscribe for notifications.

    Possible values are:

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

    Default: true

    Call Returns

    Name

    Required

    Type

    Description

    stateOptionalBoolean

    Indicates the status of a GPS engine.

    Possible values are :

    • true: GPS engine has been started.
    • false: GPS engine has been stopped.
    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Subscription Returns

    Name

    Required

    Type

    Description

    stateOptionalBoolean

    Indicates the status of a GPS engine.

    Possible values are:

    • true: GPS engine has been started.
    • false: GPS engine has been stopped.
    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

    # 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

    Description

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

    Parameters

    Name

    Required

    Type

    Description

    HandlerRequiredString

    Indicates the location of the service provider.

    Possible values are:

    • gps
    • network

    Call Returns

    Name

    Required

    Type

    Description

    accuracyOptionalNumber

    Accuracy of the requested location.

    • 1: High
    • 2: Medium
    • 3: Low
    powerRequirementOptionalNumber

    Power requirement for TTFF (Time To First Fix):

    • 1: High
    • 2: Medium
    • 3: Low
    requiresNetworkOptionalboolean

    Indicates whether the location handler requires a network.

    • true: Network is required.
    • false: Network is not required.
    requiresCellOptionalboolean

    Indicates whether the location handler requires a cell.

    • true: Cell is required.
    • false: Cell is not required.
    monetaryCostOptionalboolean

    Indicates whether the location handler is allowed to charge the user.

    • true: Charging allowed.
    • false: Charging is not allowed.
    returnValueRequiredboolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Example

    # 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

    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

    subscribeOptionalboolean

    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

    minimumIntervalOptionalNumber

    Indicates the minimum time interval between location updates.

    Possible Range: 0 <= minimumInterval <= 3600000(in milliseconds).

    minimumDistanceOptionalNumber

    Indicates the minimum distance between location updates.

    Possible Range: 0 <= minimumDistance <= 60000(in metres).

    HandlerOptionalstring

    Indicates the type of location service provider.

    Possible values are :

    • "gps"
    • "network"
    • "passive"
    responseTimeoutOptionalNumber

    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

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    timestampOptionalNumber (int64_t)

    Indicates the time at which the location fix was created(in milliseconds).

    latitudeOptionalNumber (double)

    Indicates latitude.

    Possible range : -90.0 ~ 90.0(in degrees).

    longitudeOptionalNumber (double)

    Indicates longitude.

    Possible Range: -180.0 ~ 180.0(in degrees).

    altitudeOptionalNumber (double)

    Indicates the altitude above sea level(in meters), returns -1 if the altitude is unknown.

    directionOptionalNumber (double)

    Indicates the horizontal direction traveled by the device (in degrees), returns -1 if unknown.

    Possible Range: 0.0 ~ 360.0 (in degrees).

    speedOptionalNumber (double)

    Indicates the value of Velocity overground(in meters/second),returns -1 if unknown.

    horizAccuracyOptionalNumber (double)

    Indicates the estimated horizontal accuracy value of this location(in meters), returns -1 if unknown.

    vertAccuracyOptionalNumber (double)

    Indicates the estimated vertical accuracy value of this location (in meters), returns -1 if unknown.

    Subscription Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    timestampOptionalNumber (int64_t)

    Indicates the time at which the location fix was created(in milliseconds).

    latitudeOptionalNumber (double)

    Indicates latitude.

    Possible Range: -90.0 ~ 90.0(in degrees).

    longitudeOptionalNumber (double)

    Indicates longitude.

    Possible Range: -180.0 ~180.0(in degrees).

    altitudeOptionalNumber (double)

    Indicates the altitude value above sea level(in meters), returns -1 if unknown.

    directionOptionalNumber (double)

    Indicates the horizontal direction traveled by the device, returns -1 if unknown.

    Possible Range: 0.0 ~ 360.0(in degrees).

    speedOptionalNumber (double)

    Indicates the device velocity over ground.(meters/second), returns -1 if unknown.

    horizAccuracyOptionalNumber (double)

    Indicates the estimated horizontal accuracy of this location (in meters), returns -1 if unknown.

    vertAccuracyOptionalNumber (double)

    Indicates the estimated vertical accuracy of a location (in meters), returns -1 if unknown.

    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
    }

    # 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
    }

    getReverseLocation

    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 > "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: https://developers.google.com/maps/documentation/geocoding/?hl=en.

    Parameters

    Name

    Required

    Type

    Description

    latitudeRequireddouble

    Indicates latitude.

    Possible range: -90.0 ~ 90.0(in degrees).

    longitudeRequireddouble

    Indicates longitude.

    Possible range: -180.0 ~ 180.0.(in degrees).

    languageOptionalstring

    Indicates the language in which the address(result) is returned.

    result_typeOptionalarray

    Indicates the type of address.

    location_typeOptionalarray

    Indicates the type of location.

    Call Returns

    Name

    Required

    Type

    Description

    responseOptionalobject

    Indicates the response received from Google geocoding.

    returnValueRequiredboolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Example

    # 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

    Description

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

    Parameters

    Name

    Required

    Type

    Description

    HandlerRequiredstring

    Indicates the type of location service provider.

    Possible values are :

    • gps
    • network
    subscribeOptionalboolean

    Subscribe for notifications.

    Possible values are:

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

    Default: true

    Call Returns

    Name

    Required

    Type

    Description

    stateOptionalNumber

    Indicates the state of the handler.

    Possible values are :

    • 0: Disabled
    • 1: Enabled
    returnValueRequiredboolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalstring

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

    Subscription Returns

    Name

    Required

    Type

    Description

    stateOptionalNumber

    Indicates the state of the handler.

    Possible values are :

    • 0: Disabled.
    • 1: Enabled.
    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

    # 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
    }

    setState

    Description

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

    Parameters

    Name

    Required

    Type

    Description

    HandlerRequiredString

    Indicates the type of location service provider.

    Possible values are :

    • gps
    • network
    stateRequiredBoolean

    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

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

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

    Response:

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

    mock/enable

    Description

    Enables a mock location of the given provider.

    Parameters

    Name

    Required

    Type

    Description

    nameRequiredString

    Name of the location service provider.

    Possible values:

    • gps
    • network

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

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

    Response:

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

    mock/disable

    Description

    Disables the mock location of the given provider.

    Parameters

    Name

    Required

    Type

    Description

    nameRequiredString

    Indicates the name of the location service provider.

    Possible values are :

    • gps
    • network

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

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

    Response:

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

    mock/setLocation

    Description

    Sets a mock location for the given provider.

    Parameters

    Name

    Required

    Type

    Description

    nameRequiredString

    Indicates the name of the location service provider.

    Possible values are :

    • gps
    • network
    locationRequiredObject: location

    Indicates the information about a mock location.

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    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.
    errorCodeRequiredNumber

    The error code for the failed operation.

    errorTextOptionalString

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

    Example

    # 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
    }

    Objects

    location

    Indicates the object of location for mock.

    Name

    Required

    Type

    Description

    speedRequiredNumber (double)

    Speed, in meters/second overground.

    longitudeRequiredNumber (double)

    Indicates longitude.

    Possible Range: -180.0 ~180.0(in degrees).

    horizAccuracyRequiredNumber (double)

    Indicates the accuracy of this location(in meters).

    verAccuracyRequiredNumber (double)

    Indicates the accuracy of this location(in meters).

    headingRequiredNumber (double)

    Indicates the horizontal direction traveled by the device.

    Possible Range: -360.0 ~360.0(in degrees).

    timestampRequiredNumber (int8_t)

    Indicates the time when the location fix was created(in milliseconds).

    altitudeRequiredNumber (double)

    Indicates the altitude(in meters) above the WGS 84 reference ellipsoid.

    latitudeRequiredNumber (double)

    Indicates latitude.

    Possible Range: -90.0 ~90.0(in degrees).

    handler

    Contains a handler's name and state.

    Name

    Required

    Type

    Description

    nameRequiredString

    Indicates the name of the handler.

    stateRequiredBoolean

    Indicates the state of the handler.

    components

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

    Name

    Required

    Type

    Description

    routeOptionalString

    Indicates long or short name of a route.

    localityOptionalString

    Indicates the locality.

    administrative_areaOptionalString

    Indicates the administrative area.

    postal_codeOptionalString

    Indicates the postal code.

    countryOptionalString

    Indicates the country name or a two letter ISO 3166-1 country code.

    bounds

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

    Name

    Required

    Type

    Description

    southwestLatRequiredNumber (double)

    Indicates the latitude of southwest direction.

    southwestLonRequiredNumber (double)

    Indicates longitude of southwest direction.

    northeastLatRequiredNumber (double)

    Indicates latitude of northeast direction.

    northeastLonRequiredNumber (double)

    Indicates longitude of northeast direction.

    API Error Codes Reference

    Error Code

    Error Text

    Error Description

    0Success

    Indicates that the operation was successfully executed.

    1Time out

    The operation's return is overtime.

    3Unkown error

    Indicates that the reason for the occurrence of the error is unknown/ambiguous.

    5Location source is off

    Indicates that the location source is unavailable to get the location information.

    10Invalid input

    Indicates the input provided is invalid.

    11No internet connection

    Indicates that the current internet connection is closed (unavailable).

    13Out of memory

    Indicates that the device is out of memory.

    21Failed to read the WSP Configuration file

    Indicates that the configuration file wsp.conf is missing or it has an invalid JSON.

    22Failed to get the WSP name in conf file

    Indicates that the wspName file is missing or its value is empty.

    23Failed to get the WSP API Key in conf file

    Indicates that apiKey file is missing or its value is empty.

    24Failed to get the WSP service list in conf file

    Indicates that the services file is missing or its array has no members.

    25Failed 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.

    26Failed to get the WSP feature's URL in conf file

    Indicates that url file is missing or its value is empty.

    Contents