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
iOS/iPadOS Permissions
- Location Services - more on enabling specific iOS/iPadOS permissions here

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

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();

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