App42 Cloud API

Java and Groovy Cloud SDK

Geo Spatial

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.

public Geo createGeoPoints(String geoStorageName, ArrayList<GeoPoint> geoPointsList) throws App42Exception

Stores the geo points with unique handler on the cloud. Geo point data contains lat, lng and marker of the point.

Parameters:

geoStorageName - Unique handler for storage name
geoPointsList - List of Geo Points to be saved

Returns:

Geo object containing list of Geo Points that have been saved

Response: Geo Object

For more details click Exception
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"
                            }
                        ]
                    }
                }
            }
        }
    }
}
public Geo getNearByPointsByMaxDistance(String storageName, BigDecimal lat, BigDecimal lng, BigDecimal distanceInKM) throws App42Exception

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:

storageName - Unique handler for storage name
lat - Latitude of source point
lng - Longitude of source point
distanceInKM - Range in KM

Returns:

Geo object containing the target points in ascending order of distance from source point.

Response: Geo Object

Exception:

The method throws the following exception with the error code.
/* 
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>'.
*/ 		         
For more details click Exception
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"
                            }
                        ]
                    }
                }
            }
        }
    }
}
public Geo getNearByPoint(String storageName, BigDecimal lat, BigDecimal lng, int resultLimit) throws App42Exception

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:

storageName - Unique handler for storage name
lat - Lattitude of source point
lng - Longitude of source point
resultLimit - Maximum number of results to be retrieved

Returns:

Geo object containing the target points in ascending order of distance from source point.

Response: Geo Object

Exception:

The method throws the following exception with the error code.
/* 
2905 - NOT FOUND - No destination found using given parameter Lat : '<lat>'  Long : '<lng>'.
*/ 		       
For more details click Exception
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"
                            }
                        ]
                    }
                }
            }
        }
    }
}
public Geo getPointsWithInCircle(String storageName, BigDecimal lat, BigDecimal lng, BigDecimal radiusInKM, int resultLimit) throws App42Exception

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:

storageName - Unique handler for storage name
lat - Lattitude of source point
lng - Longitude of source point
radiusInKM - Radius in KM
resultLimit - Maximum number of results to be retrieved

Returns:

Geo object containing the target points in ascending order of distance from source point.

Response: Geo Object

Exception:

The method throws the following exception with the error code.
/* 
2901 - NOT FOUND - No destination found using given parameter Lat : '<lat>'  Long : '<lng>' and Radius In KM '<radiusInKM>'.
*/ 		       
For more details click Exception
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"
                        }
                    }
                }
            }
        }
    }
}
public ArrayList <Geo> getAllStorage() throws App42Exception

Fetch the name of all storage stored on the cloud.

Parameters:

N/A

Returns:

Geo object containing List of all the storage created

Response: ArrayList<Geo> Object

Exception:

The method throws the following exception with the error code.
/* 
2902 - NOT FOUND - No Geo Storage exists.
*/ 		       
For more details click Exception
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"
                    }
                ]
            }
        }
    }
}
public Geo getAllPoints(String storageName) throws App42Exception

Get All Point from storage.

Parameters:

storageName - Name of the storage from which ponits have to be fetched

Returns:

Geo object containing all the stored Geo Points for the specified storage

Response: Geo Object

Exception:

The method throws the following exception with the error code.
/* 
2904 - NOT FOUND - No Geo Points in the storage '<storageName>' exist.
*/ 		      
For more details click Exception
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"
                            }
                        ]
                    }
                }
            }
        }
    }
}
public App42Response deleteStorage(String storageName) throws App42Exception

Delete the specifed Geo Storage from Cloud

Parameters:

StorageName - Name of the storage that has to be deleted

Returns:

App42Response if deleted successfully

Response: App42Response Object

Exception:

The method throws the following exception with the error code.
/* 
2903 - NOT FOUND - No Geo Storage exists with name '<storageName>'.
*/ 	       
For more details click Exception
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"
                }
            }
        }
    }
}