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.

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();
	BufferedReader reader = new BufferedReader(new InputStreamReader(urlc.getInputStream(), "UTF-8"));
	String s = "";
	for (String line = null; (line = reader.readLine()) != null; ) {
	    s += line;
	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)

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	

PlaceEngineClient-->		Return value from PlaceEngine Client

-->PlaceEngineServer		Request to PlaceEngine Server	

PlaceEngineServer-->		Return value from PlaceEngine Server	

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.


Used to detect a running instance of the PlaceEngine Client.


Parameter NameValueMandatory/Optional

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:


version Version String (ex. "w061130")


Used to retrieve Wi-Fi information.


Parameter NameValueMandatory/Optional
t Timestamp Mandatory
appkApplication KeyMandatory

Return Value:


rtagString containing Wi-Fi information
numapNumber of access points found, or error code

numap valueDescription
> 0Number 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:

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


Used to list the names of the LocalDBs supported.

Return Value:

A list of LocalDB names are return as follows:

["all", "tokyo"]


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 NameValueMandatory/Optional
t Timestamp Mandatory
appkApplication KeyMandatory

Return Value:

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


resultIf location estimation succeeds result >= 0, otherwise (result<0) denotes error code
infoAttribute information

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

Details for the return value: result are as follows:

0Both 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.


Estimates current location from Wi-Fi information retrieved.


Parameter NameValueMandatory/Optional
rtagString containing Wi-Fi informationMandatory
appkApplication KeyMandatory
fmtCan be omitted or specifiy: jsonOptional
quoteResult 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

rangeEstimation Accuracy Level(range >0), error code(range<0)
infoAttribute Information

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

info Attribute NameDescription
addrAddress String
msgFeedback Message
floorFloor Information(ex. "2F")

PlaceEngine Client Interface (Hybrid Estimation)


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


appkApplication KeyMandatory
fmtThe format of the result, either "json" or "jsonp". Default is "jsonp".Optional
mEstimation method(s)(*1), separated by commas. Default is "g,l,p".Optional
usecacheUsed cached results(*2). Either "0" (zero, don't use cache) or "1" (use cache). Default is "1".Optional
restrictRestrict 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

resultSuccess (>= 0), Error (< 0, see Error Code Table)
methodEstimation method used
tResult timestamp
infoAdditional attributes (name-value pairs).

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

"info" Attribute NamesMeaning
addrAddress string
floorFloor information (e.g. 2F)


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

JSON format specified for results
{ "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.
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.
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.
// 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.
// 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

-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.
©2007-2011 Koozyt, Inc. | Japanese / English