Using geospatial data
Using Apstrata, developers can persist their data into key/value pairs structures called documents that are saved in their application store. The values that are associated to documents fields can be of type string, text, numeric, file or geospatial. A geospatial field has a value that is expressed in terms of latitude and longitude, with a precision of 10 meters (4 digits), e.g: myLocation=51.1234,1.1234.
Saving a document that contains geospatial fields is no different from saving any other document and is done using the SaveDocument API. As you would expect it, querying documents that contain geospatial field also does not differ from querying any other document and is done using the Query API.
Example 1: save the player's location
You are implementing a cool mobile game and you would like to save the current location of your players, in order for example to customize the game, suggest contextual information, or inform them of an event related to your application that is taking place near them. Once it retrieves the player's location from their mobile device, the client-side part of your application can pass it along with other values to create or update a document on your Apstrata back-end.
curl -X POST "https://varick.apstrata.com/apsdb/rest/O763A7F690/SaveDocument?apsws.time=1418992125166" -F apsws.responseType=json -F apsws.authMode=simple -F apsdb.store=DefaultStore -F location=51.1234,1.1234 -F location.apsdb.fieldType=geospatial -F player=gangsta -F apsws.authSig=1933c4b633b2ad05c40c2bd7c7ad0aa8
// Prepare the parameters to send
var params = {
"apsdb.store": "DefaultStore", // "DefaultStore" is the name by default. If you did not rename your store, this line is optional
"location": "51.1234,1.1234",
"location.apsdb.fieldType": "geospatial" // we specify that the "location" field is of type "geospatial"
"player": "gangsta" // fields are of type "string" by default, so no need to specify it for "player"
}
// Invoke the API using the native "apsdb" object
// Since we're not uploading files, we send "null" in place of the "files" parameter
var response = apsdb.callApi("SaveDocument", params, null); // the response JSON object contains the "key" field, document key of the created document
String response = "no response yet";
try {
String authKey = "O763A7F690"; // Replace with your Application key
String baseURL = "https://sandbox.apstrata.com/apsdb/rest";
// Sign your call with a signature based on your application key and secret to authenticate against Apstrata
// Simple signature is used in this example
String secret = "S4A0120A6E64952FE75285BD0XD243S2"; // Replace with your application secret
Connection ownerConnection = new OwnerConnection(baseUrl, authKey, secret);
Client client = new Client(baseURL, authKey, ownerConnection);
Client.AuthMode mode = Client.AuthMode.SIMPLE;
// Prepare the parameters to send to the SaveDocument API
List<NameValuePair> parameters = new ArrayList<NameValuePair>();
parameters.add(new BasicNameValuePair("apsdb.store","DefaultStore")); // "DefaultStore" is the name by default. If you did not rename your store, this line is optional
parameters.add(new BasicNameValuePair("location","51.1234,1.1234")); // we add the "location" field to our document
parameters.add(new BasicNameValuePair("score.apsdb.fieldType","numeric")); // we specify that the "location" field is of type "geospatial"
parameters.add(new BasicNameValuePair("player","gangsta")); // fields are of type "string" by default, so no need to specify it for "player"
// Invoke the API using the above Client instance
// Since we're not uploading files, we send "null" in place of the "files" parameter
response = client.callAPIJson("SaveDocument", parameters, null, mode); // the response JSON object contains the "key" field, document key of the created document
} catch (Exception e) {
response = "Error: " + e.getMessage();
e.printStackTrace();
}
Example 2: find the players around me, sorted by ascending distance
Let us now assume that you would like your players to be able to locate other players around them (within a distance of 200 meters max), allowing them for example to build up a team in a multiplayer location-based configuration of your game (e.g. territory control). Using Apstrata Query API, this is very simple to do, as demonstrated in the below example
curl "https://varick.apstrata.com/apsdb/rest/O763A7F690/Query?apsws.time=1419327347756 &apsws.authSig=1933c4b633b2ad05c40c2bd7c7ad0aa8 &apsws.responseType=json&apsws.authMode=simple&apsdb.store=DefaultStore &apsdb.query=location"%"3Cgeospatial"%"3E"%"20within(51.1234"%"2C1.1234"%"2C200) &apsdb.queryFields=player%2C%20location%2C%20distance(location%2C'51.1234'%2C'1.1234') &apsdb.sort=distance(location"%"2C51.1234"%"2C1.1234)"%"3CASC"%"3E"
// Prepare the parameters for the API
var params = {
"apsdb.store": "DefaultStore", // "DefaultStore" is the name by default. If you did not rename your store, this line is optional
"apsdb.query": "location<geospatial> within(51.1234,1.1234,200)", // find all documents having a field name "location" of type "geospatial" with values falling in the given coordinates within a distance of 200m
"apsdb.sort": "distance(location,51.1234,1.1234)<ASC>", // sort by distance from this location, in ascending order
"apsdb.queryFields": "player,location,distance(location,'51.1234','1.1234')" // return player and location fields, and build a derived distance field using the location field and given start point
}
var response = apsdb.callApi("Query", params, null);
String response = "no response yet";
try {
String authKey = "O763A7F690"; // Replace with your Application key
String baseURL = "https://sandbox.apstrata.com/apsdb/rest";
// Sign your call with a signature based on your application key and secret to authenticate against Apstrata
// Simple signature is used in this example
String secret = "S4A0120A6E64952FE75285BD0XD243S2"; // Replace with your application secret
Connection ownerConnection = new OwnerConnection(baseUrl, authKey, secret);
Client client = new Client(baseURL, authKey, ownerConnection);
Client.AuthMode mode = Client.AuthMode.SIMPLE;
// Prepare the parameters to send to the SaveDocument API
List<NameValuePair> parameters = new ArrayList<NameValuePair>();
parameters.add(new BasicNameValuePair("apsdb.store","DefaultStore")); // "DefaultStore" is the name by default. If you did not rename your store, this line is optional
parameters.add(new BasicNameValuePair("apsdb.query","location<geospatial> within(51.1234,1.1234,200)")); // find all documents having a field name "location" of type "geospatial" with values
parameters.add(new BasicNameValuePair("apsdb.queryFields","player, location, distance(location,'51.1234','1.1234')")); // return player and location fields, and build a derived distance field using the location field and given start point
parameters.add(new BasicNameValuePair("apsdb.sort","distance(location,51.1234,1.1234)<ASC>")); // sort by distance from this location, in ascending order
// Invoke the API using the above Client instance
// Since we're not uploading files, we send "null" in place of the "files" parameter
response = client.callAPIJson("Query", parameters, null, mode); // the response JSON object contains the "key" field, document key of the created document
} catch (Exception e) {
response = "Error: " + e.getMessage();
e.printStackTrace();
}