PlaceEngine API JavaScript Library

By using the PlaceEngine API JavaScript library, you can use PlaceEngine's "Get Location" feature via JavaScript. It is now easily possible to create location aware web applications by using this interface.

Tutorial

Getting an Application Key

In order to use the PlaceEngine API JavaScript Library you must obtain and Application Key first. Please see the PlaceEngine Enabled Site Application Key Page, in order to obtain an Application Key.

Sample1: Hello Location

A very simple example that gives the current location after clicking a button. [ Try ]

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Hello Location</title>
<script src="http://www.placeengine.com/javascripts/pengine.js" type="text/javascript"></script>  *1
<style type="text/css">
.peui input {margin:0 0 -4px 0;}
</style>
</head>

<body>
<h1>Hello Location</h1>

<div class="peui">
<input alt="Register Location" src="/images/wide_bt2.png" type="image"
    onclick="pe.registerLocation()" />  *2
<input alt="Get Location" src="/images/wide_bt1.png" type="image"
    onclick="pe.getLocation()" />     *3
<span id="pestatus"></span>   *4
</div>

<script type="text/javascript">
var pe = new PEngine({
    idstatus:"pestatus",   *5
    appkey:"......."       *6
});
</script>

</body>
</html>

*1: Incorporates the PlaceEngine Javascript Library.

*2: Defines the "Register Location" button. When you click on this button, you will be redirected to the PlaceEngine Register Location Page.

*3: Defines the "Get Location" button. When this button is clicked, the getLocation method of the PEngine objected (pe) will be called. When this method is called, this application will communicate with the PlaceEngine Client in order to access Wi-Fi information, and send the retrieved Wi-Fi information to the PlaceEngine Server in order to convert it to location information.

*4: Html span element used to display Location information. Here we used the id "pestatus".

*5: Configure the id used to display the location information as defined in Step *4.

*6: Specify your Application Key here.

Sample2: PlaceEngine + Google Maps

In the first example, after executing "Get Location", location information was displayed in the tag id specified in idstatus. In this example we show the use of a user defined callback function that can be called accordingly after executing "Get Location".

The following code block shows how to incorporate Google Maps by using the callback function. When the "Get Location" button is clicked, the map will scroll to show the current location in the center. [ Try ]

(For information on Google Maps API please refer to sites such as: (Google Maps API ) )

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>PlaceEngine + Google Maps</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=...."  *1
      type="text/javascript"></script>
<script src="http://www.placeengine.com/javascripts/pengine.js" type="text/javascript"></script>
<script type="text/javascript">  *2
    //<![CDATA[
    var map = null;
    function load() {
      if (GBrowserIsCompatible()) {
        map = new GMap2(document.getElementById("map"));
        map.addControl(new GLargeMapControl());
        map.addControl(new GScaleControl());
        map.setCenter(new GLatLng(35.67134, 139.76516), 17);
      }
    }
    //]]>
</script>
<style type="text/css">
.peui input {margin:0 0 -4px 0;}
</style>
</head>

<body onload="load()" onunload="GUnload()">

<h1>PlaceEngine + Google Maps</h1>

<div id="map" style="width: 500px; height: 300px"></div>

<div class="peui">
<input alt="Register Location" src="http://www.placeengine.com/images/wide_bt2.png" type="image"
        onclick='pe.registerLocation(map)' />  *3
<input alt="Get Location" src="http://www.placeengine.com/images/wide_bt1.png" type="image"
        onclick='pe.getLocation()' />
<span id="pestatus"></span>
</div>

<script type="text/javascript">
var pe = new PEngine({
  onGetLocation: function(x, y, r, info) {   *4
    if (map != null) map.panTo(new GLatLng(y, x));
    if (document.getElementById("pestatus")!=null) {
      document.getElementById("pestatus").innerHTML = info.addr;
    }
  },
  idstatus:"pestatus",
  appkey:"....."  *5
});
</script>

</body>
</html>

*1: Specify API Key for Google Maps.

*2: Javascript for configuring Google Maps.

*3: Defines the "Register Location" button. If you specify a Google Maps Object (map) as an argument, the PlaceEngine register location page will show the same map that was displayed when "Register Location" was clicked.

*4: Defines callback function: onGetLocation as an argument. The arguments passed to the callback functions are defined as follows:

function(x, y, r, info)
  x    Longitude
  y    Latitude
  r    Error Code: If succesful, return value is > 0. If an error occurs, the return value is  < 0
  info Misc attribute information. Address information is returned in info.addr

In this example, the map scrolls to the position returned in longitude/latitude and a string specifying the address is also displayed.

*5: Specify your PlaceEngine Application Key here.

Sample3: Yahoo Maps + PlaceEngine

This example shows how to incorporate Yahoo Map Web Service. [ Try ]

Sample4: Greasemonkey

Greasemonkey is a Firefox extension that allows users to incorporate scripts to add functions to existing web pages. By combining the PlaceEngine API and greasemonkey, it is possible to add the "Get Location" feature to show current location on existing web based map services. Here we show an example that uses 「Hatena Maps 」 .

* Since greasemonkey is dependent on the structure of a web site, if changes are made to the corresponding site, your script may cease to function. Please use at your own risk.

placeenginehatenamap.user.js

PlaceEngine for FON Maps greasemonkey

placeengineforfonmap.user.js

Reference

PEngine Object

var pe = new PEngine({ option_name: value, option_name: value, .... });

The line above shows how to create a PEngine Object. The options that can be passed when creating an PEngine Object are as follows:

Option_name	Value	Description
idstatus	tag name	Tage name used to display messages from PlaceEngine
appkey	string	Application Key
onFindClient	Callback Function	Called when the PlaceEngine Client is found
onGetLocation	Callback Function	Called when "Get Location" is executed
onMessage	Callback Function	Called when displaying a messages from PlaceEngine
debug	true/false	Debug Mode (default value: false)

PEngine Object Methods

pe.getLocation()

Used to "Get Location". This method initiates communication with the PlaceEngine Client in order to retrieve Wi-Fi signal pattern information. This Wi-Fi information is sent to the PlaceEngine server to obtain location information. This location information can be accessed via the onGetLocation callback function or displayed in the tag specified by idstatus. This method is usually used to specify the action to be taken when the "Get Location" button is clicked.

pe.registerLocation([map])

Used to open the PlaceEngine "Register Location" page. If you use GoogleMaps in your site, you can specify a Google Maps Object, map, to specify the center coordinates and zoom level used in the map on the PlaceEngine "Register Location" page.

pe.pingClient([ message ])

Used to find out if a PlaceEngine Client is running on the client device. A message is sent to the PlaceEngine Client to find out if there is one running. After configuring an onFindClient callback function, make a call to pingClient to detect a PlaceEngine Client. If one is running and a reply message is received, the onFindClient callback will be called.

* Note that if a PlaceEngine Client is not found, the onFindClient callback function will not be called.

If you specify an argument, "message", this string will be displayed in the tag specified by idstatus.

Callback Function

onFindClient

function(version)

Called when a PlaceEngine Client is detected on your client device.

Argument	Value
version	version string (ex: "w061214")

onGetLocation

function(x, y, r, info)

Argument	Value
x	Longitude (float)
y	Latitude (float)
r	Result Code: if successful, r > 0; if error occurs, r < 0
info	Attributes

Called when "Get Location" is executed. Latitude(y) and longitude(x) are specified in WGS format. A positive value for x denotes an eastern longitude value, where as a negative value denotes a western longitude value. A positive value for y denotes an northern latitude value, where as a negative value denotes a southern latitude value.

x = 135.6789,  y = 35.1234  denotes 135.6789 E, 35.1234 N
x = -47.91,    y = -15.78   denotes 47.91 W, 15.78 S

info attribute name	Description
addr	Address String (ex: "4-Chome, Ginza, Chuo-ku, Tokyo")
msg	Feedback Message
floor	Floor Information (ex: "2F")
t	Timestamp

r value	Description
> 0	Indicates success. The value indicates estimation accuracy level in meters.
-1	Could not retrieve Wi-Fi information (ex. Wi-Fi device is OFF)
-2	# of access points (AP) is zero (Wi-Fi device is enabled, but no APs found)
-4	Wi-Fi scan not permitted
-5	timeout
-6	Application Key not configured or invalid
≤ -100	Parameter Errors
-110	Location not registered in server
-111	Application Key not registered or invalid
-113	Request format error
-115	Timestamp discrepancy

Error codes: -1..-99 are specified by the PlaceEngine Client and error codes lower than or equal to -100 are specified by the PlaceEngine Server.

onMessage

function(message)

Is called when there is a message from PlaceEngine.

Argument	Value
message	Message String

Usage Techniques

Would like to show a different web page, when a PlaceEngine Client is found and when one is not found

For such a case one uses the onFindClient callback function. This callback function is called when a web page is opened and a PlaceEngine Client is detected on the client device.

var pe = new PEngine({onFindClient:function(v){...}});

When a PlaceEngine Client does not exist, this callback function will not be called. So when building a PlaceEngine enabled site, you should prepare a default page view to be displayed when a PlaceEngine Client is not found, and another view that is called by using this callback function showing PlaceEngine functionality (a default page view might not show all the PlaceEngine features that are only effective when the PlaceEngine Client is installed).