API: Return Device Location

Allows you to check the device's geolocation coordinates and placemark data.

Requirements

Kiosk Pro Plus and Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Check Location Coordinates
      • On JavaScript API Request Only - requests location data using the kp_Geolocation_requestLocation function.
      • On App Launch & On JavaScript API Request - for a stationary kiosk, defining these variables once when the app is launched may be sufficient and will help prevent battery drain from regular location monitoring.
      • Continuously & On JavaScript API Request - queries once a minute for new location data.
  • iOS/iPadOS Permissions
    • Location Services - more on enabling specific iOS/iPadOS permissions here


Triggers via API Functions

Check Location Coordinates

This function allows the app to request and return current location coordinates for the device.  

Format
kp_Geolocation_requestLocation(callback);
		
Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(error, location);
		
Callback return values
  • error - [array] if defined, the function was unable to successfully access location services and return a location. Formatted as an associative array of key-value pairs with the following keys:
    • domain
    • code
    • description
    • failureReason
    • recoverySuggestion
    • debugDescription
  • location - [array] if defined, the function successfully returned a location. Formatted as an associative array of key-value pairs with the following keys:
    • latitude - [string] the latitude, measured in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator
    • longitude - [string] the longitude, measured in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian
    • altitude - [string] the altitude, measured in meters. Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level
    • horizontalAccuracy - [string] the radius of uncertainty for the location, measured in meters. The location’s latitude and longitude identify the center of the circle, and this value indicates the radius of that circle. A negative value indicates that the latitude and longitude are invalid
    • verticalAccuracy - [string] the accuracy of the altitude value, measured in meters. When this property contains 0 or a positive number, the value in the altitude property is plus or minus the specified number of meters. When this property contains a negative number, the value in the altitude property is invalid. Determining the vertical accuracy requires a device with GPS capabilities. Thus, on some devices, this property always contains a negative value
    • speed - [string] the speed of the location in m/s. Negative if the device is not currently moving
    • course - [string] the course of the location in degrees true North. Negative if the device is not currently moving. Range: 0.0 - 359.9 degrees, 0 being true North
    • timestamp - [string] the the time at which this location check occurred
    • accuracy - [string] the equivalent of "horizontalAccuracy", included for backward compatibility


Check Location Placemark

This function triggers a callback returning arrays with the location placemark information for the device, which represents Apple's best approximation of a full physical address for the device.

Note that Apple rate-limits requests to its geocoding endpoint for placemark data - they recommend only requesting new placemark information if you don't have a previous location, if the user has moved a meaningful distance from the previous location, such as 1000 meters, and if it's been 60 seconds since the last geocode request.

Format
kp_Identification_requestDeviceContextInfo(callback);
		
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback format
callback(deviceInfo);
		
Callback return values deviceInfo - [array] containing the following:
  • locationIdentification - [array] containing key-value pairs for the following:
    • currentLocationPlacemark - [string] the user-friendly information returned by Apple for a specific location. For example, “Name: 440 Sagner Avenue | Thoroughfare: Sagner Avenue | SubThroughfare: 440 | Locality: Frederick | Sublocality: NA | AdministrativeArea: MD | SubadministrativeArea: Frederick | PostalCode: 21701 | ISOCountryCode: US”
    • currentLocationDescription - [string] the last returned location coordinates for the device. For example, “+39.4114944,-77.4046826 | +/-65.00m(speed -1.00 mps / course -1.00) | 2020-09-16 17:23:58 + 0000”


Notifications via API Callbacks

On Location Update

This callback is triggered by the app when the location is updated through the app's 'Update Location Coordinates Automatically' setting, which must be set to 'Continuously' to trigger this on an ongoing basis or 'On App Launch' to trigger this once on app launch.

This callback does not return coordinate data directly, but instead can be defined in the head of your page to trigger one of the functions described above to return new location data.

Format
kp_LocationTracker_locationDidUpdate();
		


Deprecated

App-Defined Location Variables

Deprecated as these variables are injected by the app into the page and, as such, are not reliably available at the 'onLoad' event. This associative array returns key-value pairs defining the coordinates, accuracy, and timestamp of the most recent location check.

Format
window.kioskpro_location[value];
		
Return Values
  • latitude - the latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator
  • longitude - the longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian
  • accuracy - the radius of uncertainty for the location, measured in meters
  • timestamp - the time at which this location check occurred


Sample Code

  • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
  • To run sample code, set the app's homepage to kioskgroup.com/location-api
  • To download a .zip of sample code, click here.

Change Log

  • Added in version 1.0. Ability to check location coordinates on demand added in version 9.2. Ability to return placemark data added and app-defined variables deprecated in version 10.0

Still stuck? How can we help? How can we help?