Child pages
  • Geospatial queries
Skip to end of metadata
Go to start of metadata

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.

Back to the map 

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();
}
Try it!

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();
}
Try it!

Dig deeper

Related tutorials