Observation-Lib

Observation-Lib contains methods that allow you to save features or observations to cloud storage supported by HERE and also retrieve them from this storage after Live Sense SDK detects them. This can be leveraged for real time alerts between vehicles in the vicinity.

Requirements and Assumptions

The following list describes assumptions and requirements for this function:

• The customer owns and maintains the cloud storage.
• This library is not available for self-serve customers. To contact us for more details, see Help.
• To locate the detected features accurately on any given map, add a geolocation to the feature details.

Usage - Data Hub

This library provides methods to validate credentials, save and retrieve features from Data Hub.

1. Initialization

Initialize LSODataHubClient with LSOClient that is used to call the methods of Observation library.

LSODataHubClient(String spaceID, String token)

This client object can be used for calling public methods of the utility.

Parameters:

• spaceID: ID of Data Hub space where data is to be stored
• token: Authorization token to authorize the interfacing. Token should have get, put and read access to Data Hub space

Example:

LSODataHubClient client = new LSODataHubClient("spaceID", "token")

Error

• Unauthorized - Error received if user is not entitled to access Observation Library.

2. Validate Credentials

Verify if the credentials provided during initialization are valid. If valid, listener will receive a success response with status code 200.

public void validateCredentials(@NotNull LSOEventSyncListener eventSyncListener)

Callbacks:

• LSOEventSyncListener: Listener to be notified upon request success or error.

Example:

        try {
            LSOClient client = new LSODataHubClient("spaceID", "token");
            client.validateCredentials(new LSOEventSyncListener() {
                @Override
                public void onSuccess(@NotNull LSOResponse response) {
//                    Status code - success if 200 received
                    int statusCode = response.getStatusCode();
                }

                @Override
                public void onError(@NotNull LSOError error) {
                    // Error fetching data
                    String errorMessage = error.getMessage();
                }
            });
        } catch (AuthorizationException aee) {
            // current license is not entitled to use Observation Library
            String exceptionMessage = aee.getMessage();
        }

3. Put Observations

Pushes a list of observations to the Data Hub space.

public void putObservations(@NotNull LSOData obsData, @NotNull LSOEventSyncListener eventSyncListener)

Parameters:

• lsoData :- LSOData object containing list of observations, Customer ID, Submit Timestamp (Mention below).

Callbacks:

• response: Callback when the data is successfully pushed to the data hub
• error: Callback when there is an error

Example:

        try {
            LSOClient client = new LSODataHubClient("spaceID", "token");
            client.putObservations(LSOData, new LSOEventSyncListener() {
                @Override
                public void onSuccess(@NotNull LSOResponse response) {
                    // Data Published, 2XX if success
                    int statusCode = response.getStatusCode();
                }

                @Override
                public void onError(@NotNull LSOError error) {
                    // Data not published, failure status code and message
                    int errorCode = error.getStatusCode();
                    String errorMessage = error.getMessage();
                }
            });
        } catch (AuthorizationException aee) {
            // current license is not entitled to use Observation Library
            String exceptionMessage = aee.getMessage();
        }

4. Get Observations

Retrieve observations asynchronously within a specified area centered at given coordinates (latitude, longitude).To filter the observations for a specific date range, you need to specify the range in from and to parameters.

 public void getObservations(double latitude, double longitude, double radiusInMeters, @NotNull LSOEventSyncListener eventSyncListener)

Parameters:

• latitude: Latitude (in degrees) of the search area's center point
• longitude: Longitude (in degrees) of the search area's center point
• radiusInMeters: Radius (in meters) of the search area. Capped at 2000 meters
• eventSyncListener: Listener to be notified upon the request's success or error

Callbacks:

• onSuccess: LSOResponse object with success code, success message and LSOData
• onError: LSOError object with error code, error message and extra message (if any)

Example:

         try {
            LSOClient client = new LSODataHubClient("spaceID", "token");
            client.getObservations(40.758043, -73.985542, 2000, new LSOEventSyncListener() {
                @Override
                public void onSuccess(@NotNull LSOResponse response) {
//                    Data fetched successfully
                    LSOData lsoData = response.getData();
                }

                @Override
                public void onError(@NotNull LSOError error) {
                    // Error fetching data
                    String errorMessage = error.getMessage();
                }
            });
        } catch (AuthorizationException aee) {
            // current license is not entitled to use Observation Library
            String exceptionMessage = aee.getMessage();
        }

5. Get Observations for a given Date Range

Request observations asynchronously within a specified search area centered at point (latitude, longitude) and provided date range.

 public void getObservations(double latitude, double longitude, double radiusInMeters, @NotNull Calendar sinceDate, @NotNull Calendar tillDate, @NotNull LSOEventSyncListener eventSyncListener)

Parameters:

• latitude: Latitude (in degrees) of the search area's center point
• longitude: Longitude (in degrees) of the search area's center point
• radiusInMeters: Radius (in meters) of the search area. Capped at 2000 meters
• sinceDate: Start date for fetching observations based on their timestamp
• tillDate: End date for fetching observations based on their timestamp
• eventSyncListener: Listener to be notified upon the request's success or error

Callbacks:

• onSuccess: LSOResponse object with success code, success message and LSOData
• onError: LSOError object with error code, error message and extra message (if any)

Example:

        try {
            Calendar startDate = Calendar.getInstance();    // Calender object with start date
            Calendar tillDate = Calendar.getInstance();     // Calender object with till date
            LSOClient client = new LSODataHubClient("spaceID", "token");
            client.getObservations(40.758043, -73.985542, 2000, startDate, tillDate,
            new LSOEventSyncListener() {
                @Override
                public void onSuccess(@NotNull LSOResponse response) {
                    // Data fetched successfully
                    LSOData lsoData = response.getData();
                }

                @Override
                public void onError(@NotNull LSOError error) {
                    // Error fetching data
                    String errorMessage = error.getMessage();
                }
            });
        } catch (AuthorizationException aee) {
            // current license is not entitled to use Observation Library
            String exceptionMessage = aee.getMessage();
        }

Points to Remember

• Live Sense SDK does not cache any data or feature that was have not successfully saved to the cloud due to any reason like network unavailability, server/cloud service unavailability, or invalid credentials.
• Data Hub was previously named as 'XYZ'.
• To add any extra detail to each feature, you can use the customPayload object.
• Every public method throws AuthorizationException if the current license is not entitled to use Observation Library.

Additional Resources

• There is an example bundled within the download package where a very basic usage of this library is demonstrated. Feel free to experiment with the code of the example. It includes a readme that lists the steps required to run the example.