Geo Spatial Service on cloud provides the storage, retrieval, querying and updating geo data. One can store the geo data by unique handler on the cloud and can apply search, update and query on it. Geo spatial query includes finding nearby/In circle target point from given point using geo points stored on the cloud.
In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.
ServiceAPI api = new ServiceAPI("<API_KEY>","<SECRET_KEY>");
After initialization, developer needs to call the buildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of GeoService, buildGeoService() method needs to be called.
GeoService geoService = api.buildGeoService();
Once the API instance has been retrieved, You are ready to use the functions available for that particular API.
The methods available under a particular API will return the domain object (like Geo in this case) as a response which will have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have provided the JSON response with every function detail which can be retrieved by calling the toString() on the returned object.
String geoStorageName = "geoTest";
ArrayList<GeoPoint> geoList = new ArrayList<GeoPoint>();
GeoPoint gp = new GeoPoint();
gp.setMarker("Maplewood, NJ");
gp.setLat(new BigDecimal(-74.2713));
gp.setLng(new BigDecimal(40.73137));
geoList.add(gp);
Geo geo = geoService.createGeoPoints(geoStorageName,geoList); /* returns the Geo object. */
String storageName = geo.getStorageName();
ArrayList<Geo.Point> pointList = geo.getPointList();
for(Geo.Point point : pointList)
{
System.out.println("lat is " + point.getLat());
System.out.println("lng is " + point.getLng());
System.out.println("marker is " + point.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. */
The functions available under Geo Spatial API can throw some exceptions in abnormal conditions. Example of the same has been given below.
E.g. If App developer is trying to delete the storage that does not exist, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "2903" and the details as "No Geo Storage exists with name '<storageName>'".
String storageName = "geoTest";
try
{
Geo geo = geoService.deleteStorage(storageName);
}
catch(App42Exception ex)
{
int appErrorCode = ex.getAppErrorCode();
int httpErrorCode = ex.getHttpErrorCode();
if(appErrorCode == 2903)
{
// Handle here for Not Found (No Geo Storage exists with name '<storageName>'.)
}
else if(appErrorCode == 1401){
// handle here for Client is not authorized
}
else if(appErrorCode == 1500){
// handle here for Internal Server Error
}
String jsonText = ex.getMessage(); /* returns the Exception text in JSON format. (as shown below)*/
}
{
"app42Fault": {
"httpErrorCode": 404,
"appErrorCode": 2903,
"message": "Not Found",
"details": "No Geo Storage exists with name 'geoTest'"
}
}
Below are the HTTP Error Codes and their description, the function under the Geo Spatial API can throw.
/* 1400 - BAD REQUEST - The Request parameters are invalid 1401 - UNAUTHORIZED - Client is not authorized 1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again */
Below are the Application Error Codes and their description, the function under the Geo Spatial API can throw.
/* 2900 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>' and Distance In KM '<distanceInKM>'. 2901 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>' and Radius In KM '<radiusInKM>'. 2902 - NOT FOUND - No Geo Storage exists. 2903 - NOT FOUND - No Geo Storage exists with name '<storageName>'. 2904 - NOT FOUND - No Geo Points in the storage '<storageName>' exist. 2905 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>'. */
Various functions available under Geo Spatial API has been explained below.
Stores the geo points with unique handler on the cloud. Geo point data contains lat, lng and marker of the point.
Parameters:
Returns:
Response: Geo Object
String geoStorageName = "geoTest";
ArrayList<GeoPoint> geoList = new ArrayList<GeoPoint>();
GeoPoint gp = new GeoPoint();
gp.setMarker("Maplewood, NJ");
gp.setLat(new BigDecimal(-74.2713));
gp.setLng(new BigDecimal(40.73137));
geoList.add(gp);
Geo geo = geoService.createGeoPoints(geoStorageName,geoList); /* returns the Geo object. */
System.out.println("storageName is " + geo.getStorageName();
ArrayList<Geo.Point> pointList = geo.getPointList();
for(Geo.Point point : pointList)
{
System.out.println("lat is " + point.getLat());
System.out.println("lng is " + point.getLng());
System.out.println("marker is " + point.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"points": {
"point": [
{
"lat": -73.99171,
"lng": 40.73887,
"marker": "10gen Office"
},
{
"lat": -73.98814,
"lng": 40.741405,
"marker": "Flatiron Building"
},
{
"lat": -73.99781,
"lng": 40.73913,
"marker": "Players Club"
},
{
"lat": -73.99249,
"lng": 40.738674,
"marker": "City Bakery"
}
]
}
}
}
}
}
} Search the near by point in given range(In KM) from specified source point. Points to be searched should already be stored on cloud using unique storage name handler.
Parameters:
Returns:
Response: Geo Object
Exception:
/* 2900 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>' and Distance In KM '<distanceInKM>'. 2905 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>'. */
String storageName = "geoTest";
BigDecimal lat = new BigDecimal(-73.99171);
BigDecimal lng = new BigDecimal(40.738868);
BigDecimal distanceInKM = new BigDecimal(1);
Geo geo = geoService.getNearByPointsByMaxDistance(storageName, lat, lng, distanceInKM); /* returns the Geo object. */
System.out.println("geoStorageName is " + geo.getStorageName());
System.out.println("sourceLat is " + geo.getSourceLat());
System.out.println("distanceInKM is " + geo.getDistanceInKM());
System.out.println("sourceLng is " + geo.getSourceLng());
ArrayList<Geo.Point> pointList = geo.getPointList();
for (Geo.Point point : pointList)
{
System.out.println("lat is " + point.getLat());
System.out.println("lng is " + point.getLng());
System.out.println("marker is " + point.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. (as shown below)*/ }
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"sourceLat": -73.99171,
"sourceLng": 40.738868,
"distanceInKM": 1,
"points": {
"point": [
{
"lat": -73.99171,
"lng": 40.73887,
"marker": "10gen Office"
},
{
"lat": -73.99249,
"lng": 40.738674,
"marker": "City Bakery"
},
{
"lat": -73.98814,
"lng": 40.741405,
"marker": "Flatiron Building"
},
{
"lat": -73.99781,
"lng": 40.73913,
"marker": "Players Club"
}
]
}
}
}
}
}
} Search the near by point from specified source point. Points to be searched should already be stored on cloud using unique storage name handler.
Parameters:
Returns:
Response: Geo Object
Exception:
/* 2905 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>'. */
String storageName = "geoTest";
BigDecimal lat = new BigDecimal(-73.99171);
BigDecimal lng = new BigDecimal(40.738868);
int resultLimit = 2;
Geo geo = geoService.getNearByPoint(storageName, lat, lng, resultLimit); /* returns the Geo object. */
System.out.println("geoStorageName is " + geo.getStorageName());
System.out.println("sourceLat is " + geo.getSourceLat());
System.out.println("distanceInKM is " + geo.getDistanceInKM());
System.out.println("sourceLng is " + geo.getSourceLng());
ArrayList<Geo.Point> pointList = geo.getPointList();
for (Geo.Point point : pointList)
{
System.out.println("lat is " + point.getLat());
System.out.println("lng is " + point.getLng());
System.out.println("marker is " + point.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"sourceLat": -73.99171,
"sourceLng": 40.738868,
"distanceInKM": null,
"points": {
"point": [
{
"lat": -73.99171,
"lng": 40.73887,
"marker": "10gen Office"
},
{
"lat": -73.99249,
"lng": 40.738674,
"marker": "City Bakery"
}
]
}
}
}
}
}
}
Search the near by point from specified source point with in specified radius. Points to be searched should already be stored on cloud using unique storage name handler.
Parameters:
Returns:
Response: Geo Object
Exception:
/* 2901 - NOT FOUND - No destination found using given parameter Lat : '<lat>' Long : '<lng>' and Radius In KM '<radiusInKM>'. */
String storageName = "geoTest";
BigDecimal lat = new BigDecimal(-73.99171);
BigDecimal lng = new BigDecimal(40.738868);
BigDecimal radiusInKM = new BigDecimal(1);
int resultLimit = 1;
Geo geo = geoService.getPointsWithInCircle(storageName, lat, lng, radiusInKM, resultLimit); /* returns the Geo object. */
System.out.println("geoStorageName is " + geo.getStorageName());
System.out.println("sourceLat is " + geo.getSourceLat());
System.out.println("distanceInKM is " + geo.getDistanceInKM());
System.out.println("sourceLng is " + geo.getSourceLng());
ArrayList<Geo.Point> pointList = geo.getPointList();
for (Geo.Point point : pointList)
{
System.out.println("lat is " + point.getLat());
System.out.println("lng is " + point.getLng());
System.out.println("marker is " + point.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"sourceLat": -73.99171,
"sourceLng": 40.738868,
"distanceInKM": null,
"points": {
"point": {
"lat": -73.99249,
"lng": 40.738674,
"marker": "City Bakery"
}
}
}
}
}
}
} Fetch the name of all storage stored on the cloud.
Parameters:
Returns:
Response: ArrayList<Geo> Object
Exception:
/* 2902 - NOT FOUND - No Geo Storage exists. */
ArrayList<Geo> geoList = geoService.getAllStorage(); /* returns the list of Geo object. */
for (Geo geo : geoList)
{
System.out.println("storageName is " + geo.getStorageName());
System.out.println("createdOn is " + geo.getCreatedOn());
}
String jsonResponse = geoList.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": [
{
"storageName": "geoTest",
"createdOn": "2012-05-10T06:13:39.000Z"
},
{
"storageName": "GEO Storage",
"createdOn": "2012-05-10T06:48:12.000Z"
}
]
}
}
}
} Get All Point from storage.
Parameters:
Returns:
Response: Geo Object
Exception:
/* 2904 - NOT FOUND - No Geo Points in the storage '<storageName>' exist. */
String storageName = "geoTest";
Geo geo = geoService.getAllPoints(storageName); /* returns the Geo object. */
System.out.println("storageName is " + geo.getStorageName());
ArrayList<Geo.Point> pointList = geo.getPointList();
for (Geo.Point points: pointList)
{
System.out.println("lat is " + points.getLat());
System.out.println("lng is " + points.getLng());
System.out.println("marker is " + points.getMarker());
}
String jsonResponse = geo.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"points": {
"point": [
{
"lat": -73.99171,
"lng": 40.73887,
"marker": "10gen Office"
},
{
"lat": -73.98814,
"lng": 40.741405,
"marker": "Flatiron Building"
},
{
"lat": -73.99781,
"lng": 40.73913,
"marker": "Players Club"
},
{
"lat": -73.99249,
"lng": 40.738674,
"marker": "City Bakery"
},
{
"lat": -73.99249,
"lng": 40.738674,
"marker": "Splash Bar"
},
{
"lat": -73.98584,
"lng": 40.731697,
"marker": "Momofuku Milk Bar"
},
{
"lat": -73.9882,
"lng": 40.74164,
"marker": "Shake Shack"
},
{
"lat": -73.99408,
"lng": 40.75057,
"marker": "Penn Station"
},
{
"lat": -73.98602,
"lng": 40.74894,
"marker": "Empire State Building"
},
{
"lat": -73.99756,
"lng": 40.73083,
"marker": "Washington Square Park"
},
{
"lat": 106.9154,
"lng": 47.9245,
"marker": "Ulaanbaatar, Mongolia"
},
{
"lat": -74.2713,
"lng": 40.73137,
"marker": "Maplewood, NJ"
}
]
}
}
}
}
}
}
Delete the specifed Geo Storage from Cloud
Parameters:
Returns:
Response: App42Response Object
Exception:
/* 2903 - NOT FOUND - No Geo Storage exists with name '<storageName>'. */
String storageName = "geoTest"; App42Response response = geoService.deleteStorage(storageName); /* returns the App42Response object. */ boolean success = response.isResponseSuccess(); String jsonResponse = response.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": true,
"geo": {
"storage": {
"storageName": "geoTest",
"createdOn": "2012-05-10T06:13:39.000Z"
}
}
}
}
}