Review this page to learn more about integrating the Loki JavaScript API into your website.

Table of Contents

Get started in 7 lines of code 

<html>
<head>
<title>Loki Javascript API</title>
<script type="text/javascript" src="http://loki.com/plugin/files/loki.js"></script>
<script type="text/javascript">
//<![CDATA[
function load()
{
  var loki = LokiAPI();
  loki.onSuccess = function(location) {alert(location.latitude+', '+location.longitude)}
  loki.onFailure = function(error) {alert(error)}
  loki.setKey('[your_key_here]');
  loki.requestLocation(true,loki.NO_STREET_ADDRESS_LOOKUP);
}
//]]>
</script>
</head>
<body onLoad="load();">
<h1>Simple Loki Javascript API Example</h1>
</body>
</html>

Here you see a simple example of how to implement the API in only a few lines of Javascript. Now you will probably want to do some more intelligent error handling and do something a little more interesting with the user's location, but as you can see its easy to integrate Loki into any website.

Lets go through the steps...

  1. var loki = new LokiAPI() Create a new instance of the Loki object. The included loki.js file handles switching between NPAPI-based browsers, like Firefox and Safari, and ActiveX. If the plugin isn't already detected on the user's machine the constructor will start the installation of the plugin as well.
  2. loki.onSuccess = function(location){} Setup your onSuccess handler -- it gets passed a 'location' object
  3. loki.onFailure = function(error, message){} Setup your onFailure handler -- it gets passed an error code and an error message that you can display to your users.
  4. loki.setKey() Set your Application Key. If you don't already have one, you will need to register for an API Key
  5. loki.requestLocation(); Finally, request the location from the toolbar

Thats it! If you want to learn more about each step, keep reading. If you have any other questions please email us at support@loki.com and we will be happy to help

Additional Resources

Plugin Installation

In many cases a user won't already have the plugin installed on their machine. In order to make the process as seamless as possible we use a Java applet to try to install the plugin onto the user's machine. The LokiAPI() constructor will attempt to see if the plugin exists, if not it will load the applet and the applet will attempt to do the installation. In this case the user will typically see a JVM screen asking if the user trusts "Skyhook Wireless". This is because the default applet is signed by Skyhook. For better integration, we can assist developers in getting a signed version of the installer so it has their companies name on it.

If the user doesn't have a JVM installed or it doesn't load for some reason the helper javascript file will offer a native installer for the user's platform.

Once the plugin is installed on the user's machine the location request will be executed and the request handler will be called. Once a plugin is installed it is persistent across domains and requests until the user chooses to uninstall it. So subsequent request will not have to use the applet installer.

Plugin Detection

We have added a convenience function as part of the helper javascript to aid in the detection of the plugin, regardless of the platform or browser. You can call this function statically without having to call the constructor. This is meant to be used during page load -- if the user already has the plugin installed, we recommend requesting location during the body onLoad event. You can call the function like this

  if (LokiAPI.isInstalled()) { //request location }
Branding

Since the Find Me Plugin offers its functionality for free the only thing we request is that our branding or attribution be shown somewhere prominent. For the sake of simplicity and convenience we only require that a small Loki logo be placed near the text executing the lookup or attribute be placed next to a map or search results. Images are available here or you can email support@loki.com to request a version that works with your background.

Reverse Geocoding

As a convenience we are able to return reverse geocoded metadata with each location request. We use a freely available dataset from the US Census Bureau called TIGER. While this can be convenient for displaying address information to a user instead of a latitude and longitude, you should be warned that reverse geocoding has its drawbacks.

  • We currently only offer reverse geocoding services in the US
  • TIGER doesn't take property lines into account, so the house_number will almost always be incorrect by a few digits
  • It requires an additional resource hit on the server. So if you don't require it, please don't request it
IP Geolocation

As a fallback we offer a method to get the user's location based on IP Geolocation. We only recommend this as a fallback as accuracy can vary wildly and will only, at best, tell you what city the user is in. We also recommend messaging to the user that a less accurate technology was used to locate them. If we are unable to determine the user's location using Wi-Fi positioning you will receive an error -- this could happen due to no wireless adapter, the wireless adapter might be turned off, no nearby APs or we don't recognize any of the APs. To determine the user's location based on IP Geolocation, you will need to call a separate method:

  loki.requestIPLocation();

You can request reverse geocoding, but only city level and above will be available.

Uninstalling

Windows NPAPI plugin (Firefox, Opera, Safari)

Uninstall Shield can be used for uninstalling the plugin. It can be found in Add/Remove programs under Loki Browser Plugin.

Information about saved permissions and first run is stored in registry in HKEY_CURRENT_USER\Software\Skyhook Wireless\Loki Plugin. This key should be removed if you want to remove saved permissions information, and reset first run state.

Windows ActiveX Plugin (Internet Explorer)

Uninstall Shield can be used for uninstalling the plugin. It can be found in Add/Remove programs under Loki ActiveX Plugin.

Information about saved permissions and first run is stored in registry in HKEY_CURRENT_USER\Software\Skyhook Wireless\Loki Plugin. This key should be removed if you want to remove saved permissions information, and reset first run state.

OSX

Move the following files to the trash to uninstall. Be sure to restart your browser after deleting them to remove them from memory

/Library/Internet Plug-Ins/Loki.plugin

Information about saved permissions and first run is stored in standard property storage. It is specific for browser:
Safari uses: ~/Library/Preferences/com.apple.Safari.plist
Firefox uses: ~/Library/Preferences/org.mozilla.firefox.plist
Opera uses: ~/Library/Preferences/com.operasoftware.Opera.plist

These files should be also removed if you want to remove saved permissions information, and reset first run state.

API

Loki.requestLocation(latlon_lookup, address_lookup )

This method initiates the scan and the actual location request. It has two parameters that define what information you want to request from the user.

  • latlon_lookup bool - this parameter tells Loki whether or not you want the user's latitude and longitude as part of the location object.
  • address_lookup int - This parameter identifies if you want the full reverse geocode or a subset of that returned as part of the location object. We have set some constants in the Loki object so that it makes it easier to remember. There are 3 options:
    • loki.NO_STREET_ADDRESS_LOOKUP - 0
    • loki.LIMITED_STREET_ADDRESS_LOOKUP - 1
      • city
      • region
      • region_code
      • postal_code
      • country
      • country_code
    • loki.FULL_STREET_ADDRESS_LOOKUP - 2
      • house_number
      • street
      • city
      • region
      • region_code
      • postal_code
      • country
      • country_code
Loki.requestIPLocation(latlon_lookup, address_lookup )

This method initiates a request to the server for the users geolocation based on their IP address. You can learn more about this technology here. The parameters are the same as Loki.requestLocation().

Loki.setKey( string key )

setKey requires one parameter, key, which is the Application Key you were assigned when you registered with loki.com. If you have not registered, you can do so by visiting http://loki.com/developers/register/. If the key is invalid, the onFailure callback will be executed with error code 4 – Invalid Application Key.

Loki.onSuccess( object location )

If the call to the server executes successfully, this callback function will be executed and passed a location object. The location object could have the following attributes based on the parameter used during the requestLocation() call:

latitude A floating number. Example: 42.350827
longitude A floating number. Example: -71.049465
accuracy Horizontal positioning error measured in meters. Example: 21
house_number The house number of the street address. Example: 34 in "34 Farnsworth St"
street The name of the street. Example: Farnsworth St in "34 Farnsworth St"
city The name of the city: Example: Boston
region Internationalized. In most countries this maps to a State name, Province name or the equivalent. Example: Massachusetts or Ontario
region_code Internationalized. In most countries this maps to a State code, Province code or the equivalent. Example: MA or ON
postal_code In countries that support postal codes this field will be populated. Example: 02210 or A9A A9A
country The name of the country. Example: United States
country_code The character code representing the country: Example: US
accuracy Horizontal positioning error measured in meters. Example: 21
Loki.onFailure( int error, string message )

If the request to the server fails this callback function will be executed and passed an error code. A request could fail for a number of reasons, either client-side or server side. The error code will denote what type of error occurred and a human readable error message is also returned. The following error codes are possible:

  • 1 - Scanner not found
  • 2 - Wi-Fi not available
  • 3 - No Wi-Fi in range
  • 4 - Invalid Application Key
  • 5 - Location server unavailable
  • 6 - Location cannot be determined
  • 7 - Proxy unauthorized
  • 8 - File I/O Error
  • 9 - Invalid File format
  • 1000 - Plugin could not be installed
  • 1001 - User denied location request

Support

If you have any questions, comments or bugs to report you can email us at support@loki.com.