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/Option |
|---|---|---|
| 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/Option |
|---|---|---|
| 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/Option |
|---|---|---|
| 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/Option |
|---|---|---|
| rtag | >String containing Wi-Fi information | Mandatory |
| t | Timestamp | Mandatory |
| appk | Application Key | Mandatory |
| fmt | Can be omitted or specifiy: json | Option |
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 |