Skip to main content

Social reports

|

Social reports are user-generated alerts about real-time driving conditions or incidents on the road, including accidents, police presence, road construction, and more.

Users can create reports with category, name, image, and other parameters. They can vote on accuracy, comment on events, confirm or deny validity, and delete their own reports. Social reports are visible to all users with the social overlay enabled and a compatible map style.

Report categories​

The following categories and subcategories are provided in the form of a hierarchical structure, based on the OverlayCategory class:

┌ Police Car (id 256)
│   - My Side (id 264)
│   - Opposite Side (id 272)
│   - Both Sides (280)
└■
┌ Fixed Camera (id 512)
│   - My Side (id 520)
│   - Opposite Side (id 528)
│   - Both Sides (536)
└■
┌ Traffic (id 768)
│   - Moderate (id 776)
│   - Heavy (id 784)
│   - Standstill (792)
└■
┌ Crash (id 1024)
│   - My Side (id 1032)
│   - Opposite Side (id 1040)
└■
┌ Crash (id 1024)
│   - My Side (id 1032)
│   - Opposite Side (id 1040)
└■
┌ Road Hazard (id 1280)
│   - Pothole (id 1288)
│   - Constructions (id 1296)
│   - Animals (id 1312)
│   - Object on Road (id 1328)
│   - Vehicle Stopped on Road (id 1344)
└■
┌ Weather Hazard (id 1536)
│   - Fog (id 1544)
│   - Ice on Road (id 1552)
│   - Flood (id 1560)
│   - Hail (id 1568)
└■
┌ Road Closure (id 3072)
│   - My Side (id 3080)
│   - Opposite Side (id 3088)
│   - Both Sides (id 3096)
└■

The main categories and subcategories can be retrieved via the following snippet:

List<SocialReportsOverlayCategory> categories = SocialOverlay().getReportsOverlayInfo().getCategories(String());

for (auto category : categories)
{
    GEM_INFO_LOG("Category name: %s", category.getName());
    GEM_INFO_LOG("Category id: %d", category.getUid());

    for (auto subCategory : category.getSubcategories())
    {
        GEM_INFO_LOG("Subcategory name: %s", subCategory.getName());
        GEM_INFO_LOG("Subcategory id: %d", subCategory.getUid());
    }
}

More details about the OverlayCategory class structure can be found in the Overlay documentation.

Step 1: Prepare and upload a report​

Before uploading a social report, prepare it first. The SocialOverlay class provides two flavors of prepareReporting to handle the report preparation phase.

The first prepareReporting method takes a category ID and uses the current user's location or a specified data source, while the second method accepts both a category ID and a Coordinates entity, enabling reporting from a different location. These methods return an integer called prepareId, which is passed to the report method to upload a social overlay item.

Prepare and report a social overlay item:

// Example coordinates, the current position from PositionService can be used here
Coordinates reportCoordinates( 51.51907, -0.12892 ); 

// Get the prepare id. Handle any error as needed.
int prepareId = SocialOverlay().prepareReporting(reportCoordinates);

// Get the subcategory id
auto info = SocialOverlay().getReportsOverlayInfo();
List<SocialReportsOverlayCategory> categs = info.getCategories(String());

int subcategId = 0;

// Find the desired subcategory id (replace with your own logic to select the subcategory). We're chosing "Fog" as an example since it doesn't require a map matched position.
for( auto categ : categs)
{
    List<SocialReportsOverlayCategory> subcategories = categ.getSubcategories();
            
    for( auto subcateg : subcategories)
    {
        if(subcateg.getName() == "Fog") // Example subcategory name
        {
            subcategId = subcateg.getUid();
            break;
        }
    }
}

// Do the reporting
auto reportErr = SocialOverlay().report(
    prepareId,
    subcategId,
    String(), // description
    Image(), // snapshot
    ParameterList(), // additional parameters
    yourProgressListenerImpl
    );

// Check reportErr for errors.

// Wait for the operation to complete (replace with your own synchronization mechanism).
WAIT_UNTIL( std::bind( &YourProgressListenerImpl::IsFinished, yourProgressListenerImpl ), 15000 );

// Get the operation's error (replace with your own error retrieval mechanism). Handle it.
auto operationErr = yourProgressListenerImpl->GetError();

If you want to use a location from a specific data source, you can pass the data source to the prepareReporting method, as shown below:

// Assuming 'ds' is an instance of a valid DataSource
int prepareId = SocialOverlay().prepareReporting(ds, 0);
danger

prepareReporting must be called with a DataSource whose position data is classified as high accuracy by the map-matching system (the only exception is the Weather Hazard category (and its subcategories), categId = 1536, which does not require accurate positioning). If a high-accuracy data source is not provided, the method returns error::KNotFound and the report cannot be prepared.

The report is displayed for a limited duration before being automatically removed.

The reporting result is provided via the notifyComplete callback with the following error values:

  • error::KInvalidInput - Category ID is invalid, parameters are ill-formatted, or snapshot is an invalid image
  • error::KSuspended - Rate limit for the user is exceeded
  • error::KExpired - Prepared report is too old
  • error::KNotFound - No accurate data source is detected
  • KNoError - Operation succeeded

A reporting operation can be cancelled by calling the cancel method from the SocialOverlay class (applicable for other operations such as confirmReport, denyReport, updateReport, etc.) with the same progress listener object that was used to initiate the operation.

danger

Most report categories require the prepareReporting method to ensure higher report accuracy by confirming the user's proximity to the reported location. See the Get started with Positioning guide for more information about configuring the data source.

The prepareReporting method with custom Coordinates works only for Weather Hazard categories and subcategories contained within.

danger

While reporting events, the prepareReporting method needs to be in preparing mode (categId=0) rather than dry run mode (categId !=0).

Tip

The report function accepts the following optional parameters:

  • snapshot - Provide an image for the report (e.g., "png" or "jpeg")
  • params - A ParameterList configuration object for further customization of report details

These parameters are optional and can be omitted if not needed.

Step 2: Update a report​

Update an existing report's parameters using the SocialOverlay().updateReport method:

List<OverlayItem> overlayItems = mapView->cursorSelectionOverlayItems();

ParameterList newParameterList;
// populate it as needed

SocialOverlay().updateReport(
    overlayItems.front(),
    newParameterList,
    yourProgressListenerImpl);

The structure of the ParameterList object passed to the update method should follow the structure returned by the OverlayItem's previewData. The keys of the fields accepted can be found inside gem::opid namespace.

The updateReport method provides the following error values via the notifyComplete callback:

  • error::KInvalidInput - ParameterList's structure is incorrect
  • KNoError - Operation completed successfully
Tip

A user can obtain a report OverlayItem through the following methods:

  • Map Selection - Select an item directly from the map using the cursorSelectionOverlayItems method provided by the MapView
  • Search - Perform a search that includes preferences configured to return overlay items
  • Proximity Alerts - Via the AlarmListener, when approaching a report that triggers an alert

Step 3: Delete a report​

Delete a report using SocialOverlay().deleteReport. Only the original creator of the report has the authority to delete it.

The delete method provides the following error values on the notifyComplete method:

  • error::KInvalidInput - Item is not a social report overlay item or not the result of an alarm notification
  • error::KAccessDenied - User does not have the required rights
  • KNoError - Operation completed successfully

Step 4: Interact with reports​

Provide positive feedback​

Provide positive feedback for a reported event using SocialOverlay().confirmReport, which increases the score value within OverlayItem().previewData.

Provide negative feedback​

Deny inaccurate reports using SocialOverlay().denyReport, which accepts an OverlayItem object as its parameter. Reports with many downvotes are removed automatically.

Both confirmReport and denyReport provide the following error values using the notifyComplete callback:

  • error::KInvalidInput - Item is not a social report overlay item or not the result of an alarm notification
  • error::KAccessDenied - User already voted
  • KNoError - Operation completed successfully

Add comment​

Contribute comments to a reported event using SocialOverlay().addComment:

SocialOverlay().addComment(
    overlayItem,
    "This is a comment",
    yourProgressListenerImpl);

Added comments can be viewed within the OverlayItem's previewData.

The addComment method provides the following error values on the notifyComplete callback:

  • error::KInvalidInput - Item is not a social report overlay item or not the result of an alarm notification
  • error::KConnectionRequired - No internet connection is available
  • error::KBusy - Another comment operation is in progress
  • KNoError - Comment was added

Step 5: Get updates about a report​

Track changes to a report using the SocialReportListener class.

Create and register a listener for a specific OverlayItem report:

class MySocialReportListener : public ISocialReportListener
{
public:
    void onReportUpdated(const gem::OverlayItem& report) override
    {
        GEM_INFO_LOG("The report has been updated");
    }
};

auto yourSocialReportListener = StrongPointerFactory<MySocialReportListener>();

int error = SocialOverlay().registerReportListener(overlayItem, yourSocialReportListener);
if (error != KNoError)
{
    GEM_INFO_LOG("The register failed: %d", error);
}

The registerReportListener method returns the following possible values:

  • error::KInvalidInput - Provided OverlayItem is not a social overlay item
  • error::KExist - Listener already registered for the report
  • KNoError - Listener successfully registered

Unregister the listener:

auto error = SocialOverlay().unregisterReportListener(overlayItem, yourSocialReportListener);
if (error != KNoError) 
{
    GEM_INFO_LOG("The unregister failed");
}

The unregisterReportListener method returns the following possible values:

  • error::KInvalidInput - Provided OverlayItem is not a social overlay item
  • error::KNotFound - Listener was not registered for the report
  • KNoError - Listener successfully removed
Last updated on