Ramani API Framework for Android

With the Ramani API Framework for Android, you can add map data to your application. The API automatically handles access to the map servers, returns tiled-map displays (retina optimized), and provides a variety of charts returned as PNG-image or Scalable Vector-Graphics (SVG) for further client-side interactions.

Supported Platforms

With the Ramani API Framework for Android, you can build apps that target native 32-bit or 64-bit devices running Android 4.0.3 and later.

Developing an application with the Ramani API Framework for Android requires the following:

  • Android SDK Tools 15 or later.
  • Google Maps SDK V2 or later.

Getting the Ramani API Framework for Android

The Ramani API Framework for Android is distributed as a zip file containing a static framework.


Adding the Google Maps Android API to your project

Before you can add our map services to your application, you will need to add the Google Maps SDK to your project. You can follow this instruction to add the Google Maps SDK to your project.


Adding the Ramani API Framework for Android to your project

  1. Launch ADT and either open an existing project, or create a new project.
  2. Add the Ramani.jar to /libs folder of your project then add to build path
  3. Add import com.ujuizi.ramani.RSMapServices; to your code.

Obtaining the Ramani Example Application for Android (optional)

To illustrate how the use our Maps-API, we provide an example application for Android 5.0 (API level 21, "Lollipop") that demonstrates some of the API methods listed below.


Add your API-Key (apiKey)

You must provide the API-Key that you get from our client-area webpage before the API can access our map services. Please register here if you have not done already.


            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone{
  
            @Override
              public void onMapReady(GoogleMap googleMap) {

              mRSMapServices = new RSMapServices();
                  mRSMapServicesapiKey("API_KEY", "USERNAME", getApplicationContext(), this);
              }

                @Override
              public void APICheckDone(boolean isSuccess) {
                  if (isSuccess) {
                    //your code here
                  }
              }
          }

          

Note: Replace API_KEY with the string API_KEY that you created from client area.


Get a Map Layer (getMap)

With the Ramani API Framework for Android, you can add a Map Layer to your application. The code below demonstrates how to add a map layer to an existing MainActivity.




            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone{
  
            @Override

              public void onMapReady(GoogleMap googleMap) {
              mRSMapServices = new RSMapServices();
                  mRSMapServicesapiKey("API_KEY", "USERNAME", getApplicationContext(), this);
              }

                @Override
              public void APICheckDone(boolean isSuccess) {

                  if (isSuccess) {
                    //your code here

                    if (isSuccess) {
                     TileProvider tp = mRSMapServices.getMap("LAYER_ID");
                        if (tp != null) {
                            mMap.addTileOverlay(new TileOverlayOptions().tileProvider(tp));
                        }
                    }
                  }
              }

          }

          

Note: Replace layerID with the string name of the ID of a layer of your choice. A valid string consist of a layerID/param combination. You can obtain the layer ID/param-combination from the Layer Information-widget as part of our Stream Data Library (SDL).

Example: Once in the DDL-interface > select Layer entitled: Sentinel-3: Global Leaf-Area Index > leaf area index. Then from the Layer information-widget find the > Layer ID : simS3seriesLaiGlobal/lai


Get Location Info (getFeatureInfo)



                  public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                        RamaniListener.onGetFeatureInfoDone {

                    @Override
                      public void onMapReady(GoogleMap googleMap) {

                      mRSMapServices = new RSMapServices();
                          mRSMapServices.apiKey("API_KEY", "USERNAME", getApplicationContext(), this);


                           mMap.setOnMapClickListener(new GoogleMap.OnMapClickListener() {
                              @Override
                              public void onMapClick(LatLng latLng) {

                                  mRSMapServices.getFeatureInfo(latLng,"LAYER_ID" , MapsActivity.this);
                                  mRSMapServices.getFeatureInfoJson(latLng, "LAYER_ID", MapsActivity.this);
                              }
                          });
                      }

                      @Override
                      public void featureInfo(String data) {
                        //add your code here
                      }

                      @Override
                      public void featureInfoJson(JSONObject dataJson) {
                        //add your code here
                      }


                  }


          

Note: The getFeatureInfo operation is designed to provide clients with more information of the features for a single point.

Note: You can get json return by accessing RSMapServices.getFeatureInfoJson().


Get a Vertical Profile (getVerticalProfile)



                public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                      RamaniListener.onGetVerticleProfileDone {

                    @Override
                      public void onMapReady(GoogleMap googleMap) {
                      mRSMapServices = new RSMapServices();
                          mRSMapServices.apiKey("API_KEY", "USERNAME", getApplicationContext(), this);

                         

                      mMap.setOnMapLongClickListener(new GoogleMap.OnMapLongClickListener() {
                              @Override
                              public void onMapLongClick(LatLng latLng) {

                                  mRSMapServices.getVerticleProfile(latLng,"LAYER_ID", MapsActivity.this);
                                  mRSMapServices.getVerticleProfileJson(latLng,"LAYER_ID", MapsActivity.this);
                              }
                          });

                      }


                    @Override
                      public void getVerticleProfile(Bitmap result) {
                        //add your code here
                      }

                      @Override
                      public void getVerticleProfileJSONObject(JSONObject result) {

                        //add your code here
                      }
                }


          

Note: Same as Get Point Info (getFeatureInfo), but along a vertical dimension instead of a single point. Only works on layers that have a vertical dimension (explore the maps we have on offer in our DDL).

Example: For example, nitrates in the depth of the ocean.


Get a Time-series Profile (getTimeseriesProfile)



                public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onGetTimeSeriesProfile {


                @Override
                  public void onMapReady(GoogleMap googleMap) {
                  mRSMapServices = new RSMapServices();
                      mRSMapServices.apiKey("API_KEY", "USERNAME", getApplicationContext(), this);

                     

                   mMap.setOnMarkerClickListener(new GoogleMap.OnMarkerClickListener() {
                          @Override
                          public boolean onMarkerClick(Marker marker) {
                              LatLng latLng = marker.getPosition();

                              mRSMapServices.getTimeseriesProfile(latLng, "LAYER_ID",this);

                              mRSMapServices.getTimeseriesProfileJson(latLng, "LAYER_ID", this);

                              return true;
                          }
                      });

                  }


                 @Override
                  public void getTimeSeriesProfile(Bitmap result) {
                    //add your code here
                  }

                  @Override
                  public void getTimeSeriesProfileJSONObject(JSONObject result) {
                  //add your code here

                  }


              }

          

Note: Same as Get Location Info (getFeatureInfo) but varying in time (along a temporal dimension). Only works on layers that have a temporal dimension (explore the maps we have on offer in our DDL).

Example: For example, LAI over the seasons of the year.


Get a Horizontal Profile (getTransect)



            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onGetTransectDone {

                @Override
                  protected void onCreate(Bundle savedInstanceState) {
                      super.onCreate(savedInstanceState);

                      setContentView(R.layout.activity_maps);
                      Button btnTransect = (Button) findViewById(R.id.getTransect_btn);


                      btnTransect.setOnClickListener(new View.OnClickListener() {
                          @Override
                          public void onClick(View v) {


                              ArrayList bbox = new ArrayList<>();
                              bbox.add( new LatLng(52.3756,  6.4819));

                              bbox.add(new LatLng(52.315266, 6.301601));


                              mRSMapServices.getTransect(bbox, "LAYER_ID", MapsActivity.this);
                              mRSMapServices.getTransectJson(bbox, "LAYER_ID" ,MapsActivity.this);
                          }
                      });
                  }


                 @Override
                  public void getTransectBitmap(Bitmap result) {
                    //add your code here
                  }

                  @Override
                  public void getTransectJson(JSONObject result) {
                  //add your code here
                  }

              }



          

Note: Same as Get Location Info (getFeatureInfo), but along a horizontal dimension. markers is ArrayList. The value of markers is multiple LatLng point.

Example: For example, atmospheric ozone along a line (single or multiple segments) crossing a city.


Get a Area Profile (getArea)


            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 

                  RamaniListener.onGetAreaDone {



              @Override
                protected void onCreate(Bundle savedInstanceState) {
                    super.onCreate(savedInstanceState);
                    setContentView(R.layout.activity_maps);
                    Button btnGetArea = (Button) findViewById(R.id.getArea_btn);

                    btnGetArea.setOnClickListener(new View.OnClickListener() {
                        @Override
                        public void onClick(View v) {

                            ArrayList rectOptions = new ArrayList<>();
                            rectOptions.add(new LatLng(52.4024, 6.0370));
                            rectOptions.add(new LatLng(52.5960, 6.2952));

                            rectOptions.add(new LatLng(52.5028, 6.7044));
                            rectOptions.add(new LatLng(52.3269, 6.9077));
                            rectOptions.add(new LatLng(52.1840, 6.6742));
                            rectOptions.add(new LatLng(52.2160, 6.2787));

                            mRSMapServices.getArea(rectOptions, "LAYER_ID", MapsActivity.this);
                            mRSMapServices.getAreaJson(rectOptions,"LAYER_ID","RETUNR_TYPE",MapsActivity.this);
                        }
                    });

                }


               @Override
                public void getArea(Bitmap result) {

                  //add your code here
                }


                @Override
                public void getAreaJSONObject(JSONObject result) {
                //add your code here
                }
            }

          

Note: Same as Get a Horizontal Profile (getTransect), but for an area defined by PolygonOptions, which must contain 3 or more elements to define a polygon.


Get a Area Profile and get return as Json (getAreaJson)

To get json return for this method you need to specify the RETURN_TYPE, for now we support these return types:

  • histogram
  • aggregate
  • all



            button.setOnClickListener(new View.OnClickListener() {

                @Override
                public void onClick(View v) {

                   PolygonOptions rectOptions = new PolygonOptions()
                    .add(new LatLng(52.4024,6.0370),
                         new LatLng(52.5960,6.2952),
                         new LatLng(52.5028,6.7044),
                         new LatLng(52.3269,6.9077),
                         new LatLng(52.1840,6.6742),
                         new LatLng(52.2160,6.2787)
                         );

                    Polygon polygon = map.addPolygon(rectOptions);
                    JSONObject jb = RSMapServices.getAreaJson(marker, "LAYER_ID", RETURN_TYPE);
                    Log.d(TAG, jb.toString());

                }
            });
          

sample of the return:



{
    "type": "GetAreaResponse",

    "area": {
        "crs": "EPSG:4326",
        "linestring": "3.53759765625 47.79839667295524,4.556673569110679 48.07338898931344,3.4914556008582487 47.49998727341379,5.2789456005429924 47.913809258555474,3.3776305571161824 46.756562106822706,5.6348949137565185 47.21247952521911,3.787219268892672 46.519273910457045,4.775344730497775 46.848707252177114,4.775344730497775 46.848707252177114,",
        "dataset": "Sentinel-3: Global Nighttime Lights",
        "variable": "Nighttime Lights",

        "units": "",
        "aggregate": {
            "mean": 6.622666666666683,
            "stdv": 8.875178801281983,
            "skew": 2.6443954084095673,
            "kurt": 9.388449667730299,

            "min": 0,
            "max": 61,
            "perc": 6,

            "median": 6
        },
        "histogram": [
            "{frequency=2.0, value=54.0}",
            "{frequency=1.0, value=56.0}",
            ...
            "{frequency=2.0, value=16.0}",
            "{frequency=1.0, value=15.0}",

            "{frequency=2.0, value=18.0}"
        ]

    }

}

          

Get Layer Attributes(getMetadata)


            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                  RamaniListener.onGetMetadataDone {

              @Override
                protected void onCreate(Bundle savedInstanceState) {
                    super.onCreate(savedInstanceState);
                    setContentView(R.layout.activity_maps);
                    Button btnGetLayerAttributes = (Button) findViewById(R.id.btn_get_layer_attributes);


                    btnGetLayerAttributes.setOnClickListener(new View.OnClickListener() {
                        @Override
                        public void onClick(View v) {

                            mRSMapServices.getLayerAttributes("LAYER_ID", MapsActivity.this);

                        }
                    });
                }

              @Override
                public void getMetadata(JSONObject metadata) {
                    if (metadata!=null){
                        try{

                            String numColorBands = metadata.getString("numColorBands");
                            String time = metadata.getString("nearestTimeIso");
                            String  defaultPalette = metadata.getString("defaultPalette");
                        } catch (JSONException e1) {
                            e1.printStackTrace();
                        }
                    }

                }
            }
          

Note: Use this method to get Layer attributes aka metadata. For more information about which parameters you can get follow this link.

Example: To obtain the temporal range of a time-series required by getTimeseriesProfile use (TIME), or to get the extremes of a layer (Min) and (Max) to set the scaleRange parameter.

Get dates for timeseries and get return as RSS

          
           
            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 

                  RamaniListener.onGetMetadataDone {


              @Override
                protected void onCreate(Bundle savedInstanceState) {
                    super.onCreate(savedInstanceState);
                    setContentView(R.layout.activity_maps);
                    Button btnGetDates = (Button) findViewById(R.id.btn_get_dates_for_time_series);


                    btnGetDates.setOnClickListener(new View.OnClickListener() {

                        @Override

                        public void onClick(View v) {
                            Map params = new HashMap();
                            params.put("item", "dates");
                            params.put("format", "rss");
                            mRSMapServices.setParams("params");
                            mRSMapServices.getLayerAttributes("LAYER_ID",MapsActivity.this);
                        }

                    });

                }

              @Override
                public void getMetadata(JSONObject metadata) {
                    if (metadata!=null){
                        try{
                           String numColorBands = metadata.getString("numColorBands");

                            String time = metadata.getString("nearestTimeIso");
                            String  defaultPalette = metadata.getString("defaultPalette");
                        } catch (JSONException e1) {
                            e1.printStackTrace();

                        }
                    }
                }

            }
          
        

Example: click to see the example.

Get dates with ISO8601 format

          
                     
          public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onGetMetadataDone {

            @Override
              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
                  setContentView(R.layout.activity_maps);
                  Button btnGetDates = (Button) findViewById(R.id.btn_get_dates_with_iso);

                  btnGetDates.setOnClickListener(new View.OnClickListener() {
                      @Override
                      public void onClick(View v) {

                          Map params = new HashMap();
                            params.put("item", "dates");
                            RSMapServices.setParams(params);
                          mRSMapServices.getLayerAttributes(layerID,MapsActivity.this);
                      }

                  });

              }


            @Override
              public void getMetadata(JSONObject metadata) {

                  if (metadata!=null){
                      try{
                          String numColorBands = metadata.getString("numColorBands");

                          String time = metadata.getString("nearestTimeIso");
                          String  defaultPalette = metadata.getString("defaultPalette");
                      } catch (JSONException e1) {
                          e1.printStackTrace();

                      }
                  }
              }


          }
          
        

Example: click to see the example.


Set Layer Attributes (setParams)




                  Map params = new HashMap();

                  params.put("ELEVATION", "1");
                  params.put("TIME", "2006-07-28T00:00:00.000Z/2006-08-01T00:00:00.000Z");
                  RSMapServices.setParams(params);

                   mRSMapServices.getTimeseriesProfile(latLng, "LAYER_ID",this);
                    mRSMapServices.getTimeseriesProfileJson(latLng, "LAYER_ID", this);




           


          

Note: Use this method to set Layer attributes. For more information about which parameters you can set follow this link.

Example: Use the param (TIME) to set the temporal range of a time-series.


Get an animated Map (getAnimation)

With the Ramani API Framework for Android, you can create animated map layers (provided the dataset of interest has a temporal dimension). The code below demonstrates how to add an animated map layer to an existing MainActivity.


           public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onGetAnimation {

            @Override
              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
                  setContentView(R.layout.activity_maps);
                  Button btnGetAnimation = (Button) findViewById(R.id.btn_get_animation);
                  btnGetAnimation.setOnClickListener(new View.OnClickListener() {
                      @Override

                      public void onClick(View v) {
                          String[] timeStep = {
                                  "2010-09-08T00:00:00.000Z",
                                  "2010-09-15T00:00:00.000Z",
                                  "2010-09-27T00:00:00.000Z",
                                  "2010-10-04T00:00:00.000Z",
                                  "2010-10-14T00:00:00.000Z",
                                  "2010-10-26T00:00:00.000Z",
                                  "2010-11-05T00:00:00.000Z",
                                  "2010-11-12T00:00:00.000Z",
                                  "2010-11-19T00:00:00.000Z",
                                  "2010-11-22T00:00:00.000Z",

                                  "2010-11-24T00:00:00.000Z",
                                  "2010-11-29T00:00:00.000Z"
                          };

                          mRSMapServices.getAnimation("LAYER_ID",timeStep, MapsActivity.this);

                      }
                  });

              }

              @Override
              public void getAnimationList(ArrayList bitmaps) {
                  //add your animation here
              }
          }



          

Note: you can set the timeStep to compose the animation from the image sequence (timeseries).


Search using Elasticsearch (search)

Search data inside a vector layer and show it on the map.


            	
            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                  RamaniListener.onGetAreaDone {


              @Override
                protected void onCreate(Bundle savedInstanceState) {
                    super.onCreate(savedInstanceState);
                    setContentView(R.layout.activity_maps);
                    Button btnSearch = (Button) findViewById(R.id.search_btn);


                    btnSearch.setOnClickListener(new View.OnClickListener() {
                        @Override
                        public void onClick(View v) {
                            try {

                                JSONObject keywords = new JSONObject();
                                keywords.put("field_name", "value");

                                mRSMapServices.search(mMap, "LAYER_ID", "keywords", true, MapsActivity.this);
                            } catch (JSONException e) {
                                e.printStackTrace();
                            }
                        }
                    });

                }

               @Override
                public void getSearch(JSONObject result) {

                  //add your code here
                }

            }

          

Note: All you have to do before calling this method is selecting the corresponding layer in the Ramani Cloud Admin and click the “Index in Elasticsearch” button. Ramani Cloud will first map the table schema to an Elasticsearch type and then pipe the tabular data as GeoJSON to Elasticsearch.


Manipulate data of a vector map (sqlApi)

The first example shows how to search for a feature in a layer and show it on the map, the second shows how to insert a new point (i.e. GPS-location).


            	String query ="SELECT * FROM public.ec_example WHERE round(ST_Distance(ST_Transform(\"the_geom\",3857),
          	'ST_GeomFromText('POINT(551569.5961058318 6701998.640044251)',3857))) < 6114.9622628
          	ORDER BY round(ST_Distance(ST_Transform(\"the_geom\",3857),
          	ST_GeomFromText('POINT(551569.5961058318 6701998.640044251)',3857)))LIMIT 5";

            	JSONObject result = RSMapServices.sqlApi(query);


            	String insertQuery ="INSERT INTO public.road_pavement_qualities (the_geom ,time, longitude, latitude, accelx, accely,
          	accelz, orientx, orienty, orientz, magneticx, magneticy, magneticz, bearing, speed, gpsaccuracy, entropy, annotation_observe,
          	status, rpqs, annotation_predict) VALUES (ST_GeomFromText('POINT(110.597145 -7.002776666666667)',4326),
          	1434159945524,110.597145,-7.002776666666667, 4.338,3.217,4.616,2.2945807,-53.003002,1.0712337,
          	-2.5,41.25,-15.0,0.0,0.0,6.8,0.9999999999999998,null,
          	null,null,null);";

          	JSONObject result = RSMapServices.sqlApi(insertQuery);

          

Store Point (storePoint)

Store a new or modified point feature on Ramani Cloud (currently only support for private layers):


            public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onStorePointDone {

            @Override

              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
                  setContentView(R.layout.activity_maps);
                   Button btnStorePoint = (Button) findViewById(R.id.store_point_btn);


                  btnStorePoint.setOnClickListener(new View.OnClickListener() {

                      @Override
                      public void onClick(View v) {


                          HashMap fields = new HashMap();
                          fields.put("id", "50");

                          LatLng point = new LatLng(52.4024, 6.0370);

                          mRSMapServices.storePoint("LAYER_ID", fields, point, MapsActivity.this);
                      }
                  });

              }

  
    @Override
    public void storePoint(JSONObject result) {
      //add your code here
    }

}    
Note: Allows the user to define series of points of interest and store these for repeated usage on different requests.


Store Polygon (storePolygon)

Store a (multi)polygon feature on Ramani Cloud (currently only support for private layers):


                      

          public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                RamaniListener.onStorePolygonDone {


            @Override
              protected void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);

                  setContentView(R.layout.activity_maps);
                  Button btnStorePoligon = (Button) findViewById(R.id.store_polygon_btn);


                  btnStorePoligon.setOnClickListener(new View.OnClickListener() {
                      @Override
                      public void onClick(View v) {

                          Map fields = new HashMap();

                          fields.put("id", "50");

                          ArrayList markers = new ArrayList<>();
                          markers.add(new LatLng(52.4024, 6.0370));
                          markers.add(new LatLng(52.5960, 6.2952));
                          markers.add(new LatLng(52.5028, 6.7044));
                          markers.add(new LatLng(52.3269, 6.9077));
                          markers.add(new LatLng(52.1840, 6.6742));
                          markers.add(new LatLng(52.2160, 6.2787));

                          mRSMapServices.storePolygon("LAYER_ID", fields, markers, MapsActivity.this);
                      }

                  });

              }

  
    @Override
    public void storePolygon(JSONObject result) {
      //add your code here
    }
}

          

Note: This function can be used to retrieve a pre-defined area for future usage..


Store Line (storeLine)

Store your (multi)line feature on Ramani Cloud (currently only support for private layers):

           

		        public class MapsActivity extends FragmentActivity implements RamaniListener.onAPICheckDone, 
                  RamaniListener.onStoreLineDone {

              @Override
                protected void onCreate(Bundle savedInstanceState) {
                    super.onCreate(savedInstanceState);
                    setContentView(R.layout.activity_maps);
                    Button btnStoreLine = (Button) findViewById(R.id.store_line_btn);
                    btnStoreLine.setOnClickListener(new View.OnClickListener() {
                        @Override
                        public void onClick(View v) {
                            Map fields = new HashMap();
                            fields.put("id", "50");
                            ArrayList markers = new ArrayList<>();
                            markers.add(new LatLng(52.4024, 6.0370));
                            markers.add(new LatLng(52.5960, 6.2952));

                            markers.add(new LatLng(52.5028, 6.7044));
                            markers.add(new LatLng(52.3269, 6.9077));
                            markers.add(new LatLng(52.1840, 6.6742));
                            markers.add(new LatLng(52.2160, 6.2787));

                            mRSMapServices.storeLine("LAYER_ID",fields,markers, MapsActivity.this);
                        }
                    });
                }

              
                @Override
                public void storeLine(JSONObject result) {
                  //add your code here
                }
}

          

Note: Useful to keep a line stored for future usage, e.g. for obtaining a Horizontal Profile (with getTransect) for the same region over different days..


© 2016 Ujuizi Laboratories