HOME | TOOLS | API | MAP

PlaceEngine API Local Application Programming

Here we provide details on how to interface a local application running on a client device (not a web service) to PlaceEngine. Currently, we do not distribute libraries to provide this functionality. We will show code in this page in Java, but it should be straightforward and applicable to any other programming language.

General Flow

You must have the PlaceEngine Client running on your device in order to interface a local application with PlaceEngine. You can communicate with the PlaceEngine Client via HTTP. The following two steps are necessary to implement the "Get Location" function.

• Retrieve Wi-Fi information from the PlaceEngine Client (http://localhost:5448)
• Send the retrieved Wi-Fi information to the PlaceEngine Server (http://www.placeengine.com)

Getting an Application Key

In order to access the PlaceEngine Client and PlaceEngine Server from your location application you must obtain an Application Key from the PlaceEngine site.

Please see the PlaceEngine Enabled Site Application Key Page, in order to obtain an Application key. Please specify the executable image name of the location application in the URL field. For example, if your executable file name is: abcd.exe, please specify abcd. For Java programs, please specify: java (or if you are using javaw, simply: javaw).

Example1 : Hello Location in Java

This is a java program that outputs the current location to the standard output device. ( source ) (error processing is abbreviated here to provide a simple example).

import java.net.*;
import java.io.*;
import java.util.*;

/** 
 *   PlaceEngine API Sample    
 */
public class PeTest {
    public static final String appk = "......";   // Application Key

    /** Send an HTTP request, and return the response as a string **/
    public static String getURL(String urlstr) throws MalformedURLException, ProtocolException, IOException { 
	URL url = new URL(urlstr);
	HttpURLConnection urlc = (HttpURLConnection)url.openConnection();
	urlc.connect();
	BufferedReader reader = new BufferedReader(new InputStreamReader(urlc.getInputStream(), "UTF-8"));
	String s = "";
	for (String line = null; (line = reader.readLine()) != null; ) {
	    s += line;
	}
	reader.close();
	urlc.disconnect();
	return s;
    }

    /** Process return value (in json format) of the loc request **/
    public static void printInfo(String s) {
	s = s.substring(1,s.length()-1);
	String param[] = s.split(",");
	String param2[] = s.split("\\{");

	if (param.length >= 4 && param2.length >= 2) {
	    System.out.println("Lat\t" + param[1]);
	    System.out.println("Lon\t" + param[0]);

	    String info[] = param2[1].substring(0, param2[1].length()-1).split(",");
	    for (int i = 0; i < info.length; i++) {
		String tk[] = info[i].split(":");
		String name = tk[0].substring(1,tk[0].length()-1);
		String value = tk[1];
		System.out.println(name + "\t" + value);
	    }
	}
    }

    public static void main(String[] argv) throws MalformedURLException, ProtocolException, IOException {
	/*        
	System.setProperty("http.proxyHost", "....");		// configure proxy if necessary
	System.setProperty("http.proxyPort", "....");
	*/
	System.setProperty("http.nonProxyHosts", "localhost");	// exclude localhost from proxy settings

        // Get Wi-Fi information
	long t = System.currentTimeMillis() / 1000;
        String req = "http://localhost:5448/rtagjs?t=" + t + "&appk=" + appk;
	System.out.println("-->PlaceEngineClient\n" + req + "\n");
	String res = getURL(req);
	System.out.println("PlaceEngineClient-->\n" + res + "\n");

        // Get location information from Wi-Fi information
	String v[] = res.substring(9, res.length()-2).split(", *");
	String rtag = v[0].substring(1, v[0].length()-1);
	int numap = Integer.parseInt(v[1]);

	if (numap > 0) {
	    String req2 = "http://www.placeengine.com/api/loc?t=" + t + "&rtag=" + rtag + "&appk=" + appk + "&fmt=json";
	    System.out.println("-->PlaceEngineServer\n" + req2 + "\n");
	    String res2 = getURL(req2);
	    System.out.println("PlaceEngineServer-->\n" + res2 + "\n");
	
	    // print location information reply (in json format)
	    printInfo(res2);
	}
    }
}

In this example, we request the location information to be in JSON (JavaScript Object Notation) format by specifying (fmt=json) to the PlaceEngine server. For more information regarding the JSON format, please refer to references such as www.json.org.

If you need to configure a proxy, please make sure that http communication within the localhost is not directed towards the proxy. The local application will not be able to communicate with the PlaceEngine Client if this is not correctly configured.

Output result:

C:\>java PeTest
-->PlaceEngineClient		Request to PlaceEngine Client	
http://localhost:5448/rtagjs?t=1165321003&appk=S7Rk0Bm3D....

PlaceEngineClient-->		Return value from PlaceEngine Client
recvRTAG("CgS4isZH-BPX....",6,1165321003,null,null);

-->PlaceEngineServer		Request to PlaceEngine Server	
http://www.placeengine.com/api/loc?t=1165321003&rtag=CgS4isZH-BPX....&appk=S7Rk0Bm3D....&fmt=json

PlaceEngineServer-->		Return value from PlaceEngine Server	
[139.730472,35.625954,15,{'addr':'東京都品川区東五反田三丁目','msg':'位置が取得できました','floor':'2F','t':1165321003}]

Lat	35.625954
Lon	139.730472
addr	'東京都品川区東五反田三丁目'
msg	'位置が取得できました'
floor	'2F'
t	1165321003

Example2 ： Hello Location Local Database version in Java

This example uses the newly added LocalDB function to determine current location (latitude and longitude only). Internet connection to the PlaceEngine server is not necessary. ( Source Code: LocalTest.java )

PlaceEngine Client Interface

Applications can communicate with the PlaceEngine Client by issuing HTTP GET requests to http://localhost:5448.

http://localhost:5448/ackjs?parameters

Used to detect a running instance of the PlaceEngine Client.

Parameters:

Parameter Name	Value	Mandatory/Optional
t	Timestamp	Mandatory

Timestamp must be specified in the number of seconds since January 1, 1970 00:00 UTC. In Java, you can use System.currentTimeMillis()/1000 to obtain this value.

Return Value:

ackRTAG(version);

Value	Description
version	Version String (ex. "w061130")

http://localhost:5448/rtagjs?parameters

Used to retrieve Wi-Fi information.

Parameter:

Parameter Name	Value	Mandatory/Optional
t	Timestamp	Mandatory
appk	Application Key	Mandatory

Return Value:

recvRTAG(rtag,numap,t);

Value	Description
rtag	String containing Wi-Fi information
numap	Number of access points found, or error code
t	Timestamp

numap value	Description
> 0	Number of access points found
-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

PlaceEngine Client Interface (LocalDB Function)

The interface used to access the LocalDB Function newly incorporated into the PlaceEngine Client (w070606, m070606 and higher) is described here. Previous versions of the Windows and Windows Mobile Clients or the Macintosh Version do not support this LocalDB function or API.

The LocalDB function is used to estimate only latitude and longitude information and does not provide the following information:

• Address
• Floor Information
• Estimation Accuracy Level
• Number of access points used to esimate location

LocalDB estimation API can only be accessed via a local application. Web applications must use the PlaceEngine Server functions.

http://localhost:5448/listdb

Used to list the names of the LocalDBs supported.

Return Value:

A list of LocalDB names are return as follows:

["all", "tokyo"]

http://localhost:5448/locdb?parameters

Used to retrieve Wi-Fi information and estimate the current location by using the local location database (LocalDB) maintained by the PlaceEngine Client.The PlaceEngine Server is not accessed.

Parameter:

Parameter Name	Value	Mandatory/Optional
t	Timestamp	Mandatory
appk	Application Key	Mandatory

Return Value:

A string with the following format that includes latitude, longitude, error code, and addition info is returned.

[x,y,result,info]

Value	Description
x	Latitude
y	Longitude
result	If location estimation succeeds result >= 0, otherwise (result<0) denotes error code
info	Attribute information

In the current implementation, the string "{}" is always returned in info.

Details for the return value: result are as follows:

0	Both Wi-Fi information was retrived and location was estimated successfully
-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
-110	corresponding AP info is not in the LocalDB

* Even if Wi-Fi information is successfully retrieved, if information regarding the access points scanned are not in the LocalDB, x and y will both take values of zero. A resuld code -110 is returned in this case.

PlaceEngine Server Interface

Applications can communicate with the PlaceEngine Server by issuing HTTP GET requests to http://www.placeengine.com/api.

http://www.placeengine.com/api/loc?parameters

Estimates current location from Wi-Fi information retrieved.

Parameters:

Parameter Name	Value	Mandatory/Optional
rtag	String containing Wi-Fi information	Mandatory
t	Timestamp	Mandatory
appk	Application Key	Mandatory
fmt	Can be omitted or specifiy: json	Optional
quote	Result string format(*1)	Optional

*1 If the "quote" parameter is not specified then single quotes are the default. Specifying "quote=double" returns double-quotes.

Return Value:

recvLoc(x,y,range,info);   -- when fmt is omitted
[x,y,range,info]           -- when fmt=json

Value	Description
x	Longitude
y	Latitude
range	Estimation Accuracy Level(range >0), error code(range<0)
info	Attribute Information

info is a string with the following format: {"Attribute_name1":Value1,"Attribute_name2":Value2,...}. The following attributes are available.

info Attribute Name	Description
addr	Address String
msg	Feedback Message
floor	Floor Information(ex. "2F")
t	Timestamp

PlaceEngine Client Interface (Hybrid Estimation)

http://localhost:5448/getlocjs?parameters

Perform a hybrid estimation technique based on GPS, the Local DB and the PlaceEngine server.

Parameters:

NAME	MEANING	Mandatory/Optional
appk	Application Key	Mandatory
fmt	The format of the result, either "json" or "jsonp". Default is "jsonp".	Optional
m	Estimation method(s)(*1), separated by commas. Default is "g,l,p".	Optional
usecache	Used cached results(*2). Either "0" (zero, don't use cache) or "1" (use cache). Default is "1".	Optional
restrict	Restrict the number of results(*3). "0" (zero, don't restrict) or "1" (restrict). Default is "0".	Optional

*1 Specify "g" to use GPS, "p" to query the PlaceEngine server, and "l" and use the Local DB. Each method is tried in the order it is specifed. If "usecache" is zero then the "p" method will access the internet.
*2 The results of periodic queries to the PlaceEngine server are cached internally and can be returned.
*3 Multiple results are usually returned when multiple estimation methods are specified. Specifying "restrict=1" in this instance will cause only the first result to be returned.

Return Value:

// format for multiple estimation results (multiple methods specified for "m")
recvLoc2([result1,result2,...]);   -- "fmt=jsonp" or nothing specified,
[result1,result2,...]              -- "fmt=json" specified

  // individual result format.
  {"r":result, "m":method, "t":t, "x":x, "y":y, "info":info}


// format for a single estimation result
recvLoc2({"r":result, "m":method, "t":t, "x":x, "y":y, "info":info});   -- "fmt=jsonp" or nothing specified,
{"r":result, "m":method, "x":x, "y":y, "info":info}                     -- "fmt=json" specified

RESULT FIELD	MEANING
result	Success (>= 0), Error (< 0, see Error Code Table)
method	Estimation method used
t	Result timestamp
x	Longitude
y	Latitude
info	Additional attributes (name-value pairs).

The "info" field has the format: { "name-1": value-1 [, "name-2": value-2 [, ...]] }

"info" Attribute Names	Meaning
addr	Address string
floor	Floor information (e.g. 2F)

Examples:

Estimation using defaults
http://localhost:5448/getlocjs?appk=xxx

recvLoc2({ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } })

JSON format specified for results
http://localhost:5448/getlocjs?appk=xxx&fmt=json

{ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } }

Use the PlaceEngine server and don't use the cache.
http://localhost:5448/getlocjs?appk=xxx&m=p&usecache=0

recvLoc2({ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } })

Use just Local DB estimation and don't use the cache.
http://localhost:5448/getlocjs?appk=xxx&m=l&usecache=0

recvLoc2({ "r": 0, "m": "l", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": null, "floor": null } })

Use Local DB estimation, then the PlaceEngine server, then GPS estimation.
http://localhost:5448/getlocjs?appk=xxx&m=l,p,g&usecache=0&fmt=json

// Note: actual results don't include CR/LF formatting.
// This shows successful Local DB and PlaceEngine estimation results, while GPS estimation wasn't available.
[
{ "r": 0, "m": "l", "t": 1236337593, "x": 139.7659, "y": 35.6814, "info": { "addr": null, "floor": null } },
{ "r": 0, "m": "p", "t": 1236337594, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都港区麻布十番四丁目", "floor": "3F" } }
]

Use Local DB estimation, then the PlaceEngine server, then GPS estimation.
http://localhost:5448/getlocjs?appk=xxx&m=l,p,g&restrict=1&usecache=0&fmt=json

// As "restrict=1" has been specified only one result has been returned.
// Local DB estimation failed, but the PlaceEngine estimation was successful hence that result was returned.
{ "r": 0, "m": "p", "t": 1236337594, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都港区麻布十番四丁目", "floor": "3F" } }

Error Code Table

ERROR	MEANING
0	Success
-1	Failed to access the Wi-Fi feature on the device (Wireless LAN could be switched off).
-2	No access points were detected (even though Wireless LAN is enabled and functioning normally).
-3	Failed to access the PlaceEngine server.
-4	Wi-Fi scanning access was denied.
-5	Notification window timed out (no response was received from the user).
-6	Application key wasn't specified or was invalid.
-7	Requested feature is disabled because Terminal Services is disabled (Windows XP/Vista only).
-8	Invalid parameter specified.
-9	Estimation results are unreliable (e.g. weak signal strength).
-10	Internal error occurred.
-11	The use of Wi-Fi for positioning purposes is forbidden by law in your area.
-12	Invalid language code specified.
-110	Failed to retrieve a result from the Local DB (e.g. database doesn't exist).
-111	Invalid "Referer" field within the URL request.
-113	URL Request format was invalid.
-115	System time mismatch between the PlaceEngine server and the local machine.