Skip to content

08 Traffic information

Overview

In this tutorial, you will learn how to retrieve traffic information from the PTV NavigationSDK.

Base

Use Tutorial07 as a starting point for this project.

Prerequisites

Please copy the following files from the Tutorial08 folder to your project directory:

  • TrafficDialog.cpp
  • TrafficDialog.h
  • trafficdialog.ui
  • TrafficModel.cpp
  • TrafficModel.h

Also replace

  • mainwindow.ui

with the one from Tutorial08.

Note

When replacing an .ui file, the build system sometimes doesn't recognize the file has change. As a workaround simply modify the file (for example add and remove a space) and save it so that its time stamp changes.

Add the new files to the CMakeLists.txt file:

set(Tutorial_RES
    ...
    trafficdialog.ui
)

set(Tutorial_SRCS
    ...
    TrafficDialog.cpp
    TrafficModel.cpp
)

set(Tutorial_HEADER
    ...
    TrafficDialog.h
    TrafficModel.h
)

Call cmake ../ in the build directory or build the ALL_BUILD project of the solution to update it.
Also, always trigger a rebuild after copying to ensure that replaced files will be newly built.

Obtaining a key

You will need an API key for using the traffic information functionality in the SDK. Please contact the PTV Navigator product management to obtain such a key if you haven't already got one.

Retrieving traffic informations

Traffic incidents can be fetched by the SDK from an external server. The incidents hold information about what has happend, where it happend, how long the incident will last and more. Traffic results will be shown automatically as icons and traces on the map. To consider traffic in a route calculation (and therefore to probably bypass a traffic jam), set the SDK_RouteOptions member "TrafficFactor" to > 0.

The struct SDK_TrafficSearchResult has the following members:

Type Name Description
SDK_HDRINFO size Size of struct - for controlling
SDK_HDRINFO version Version of struct - for controlling. Use SDK_TrafficSearchResultVERSION
SDK_CHAR_T description[512] Description of the incident
SDK_CHAR_T reportId[100] Unique identifier for an incident
SDK_CHAR_T providerName[100] Name of the content provider
SDK_CHAR_T countryCode[5] Country code (ISO 3166-1-alpha-2)
SDK_CHAR_T stateCode[5] Country sub state code
SDK_CHAR_T startTime[50] Start time of the incident, in utc time
SDK_CHAR_T endTime[50] End time of the incident, in utc time
SDK_INT4 tmcEventCode TMC event code of the incident
SDK_INT4 category Category of the incident, see TrafficSearchCategories
SDK_INT4 delay Delay of the incident in [s]
SDK_INT4 delayOnRoute Delay of the parts of the incident which lie directly on the route in [s]
SDK_INT4 delayOnOtherEvent Same as delayOnRoute, but also on an other event with higher restriction
SDK_BOOL delayDeliveredByServer Flag whether the delay was supplied by the server or was calculated internally
SDK_INT4 averageSpeed Average speed on this incident [km/h]
SDK_INT4 eventLength Length of the event in [m]
SDK_INT4 eventLengthOnRoute Length of the event parts on the route in [m]
SDK_INT4 distanceFromStart Distance of the first segment of the event to the start of the route [m]
SDK_DOUBLE distance Distance of the first polypoint to the search midpoint [m]
SDK_INT4 status Status of the incident in relation to the last search, see TrafficStatus
SDK_Position startPosition First point in the incident polygon
SDK_BOOL onRoute Event is part of route
SDK_BOOL routingRelevant Event is part of route and considered while routing, otherwise probably it is out of time
SDK_BOOL info Event is only an information, advice or warning without a delay
SDK_BOOL onlyTruck Event is only relevant for trucks
SDK_INT4 simplifiedCategory Simplified traffic category (SDK_TI_DEFAULT, SDK_TI_JAM, SDK_TI_HEAVY, SDK_TI_BLOCKED)

The following steps are necessary to retrieve traffic information:

  • Initialize the web search by calling SDK_SetTrafficSearchWebConfiguration()
  • Call SDK_SearchTrafficInformation() to start an asynchronous call to a traffic REST service
  • Implement a callback that will be notified when a traffic search request has finished

First, we initialize the search by setting the search request url and some other data for starting a web request.
We call SDK_SetTrafficSearchWebConfiguration() with an SDK_TrafficSearchWebConfiguration struct.

The struct SDK_TrafficSearchWebConfiguration has the following members:

Type Name Description
SDK_HDRINFO size Size of struct - for controlling
SDK_HDRINFO version Version of struct - for controlling. Use SDK_TrafficSearchWebConfigurationVERSION
const SDK_WCHAR_T* url Eeb server url to use for the search, must be set to L"http://tidemo.ptvgroup.com/wfs"
const SDK_WCHAR_T* proxy Proxy server address, only used under Win32
const SDK_WCHAR_T* token Server token, set to the token given by PTV
const SDK_WCHAR_T* service Service name, must be set to L"WFS"
const SDK_WCHAR_T* serviceVersion Service version, must be set to L"1.0.0"
const SDK_WCHAR_T* request Service request, must be set to L"GetFeature"
const SDK_WCHAR_T* typeName Service provider name to use. Set to L"ptvgroup:tomtom_incidents" for tomtom or L"ptvgroup:nokia_incidents" for nokia
const SDK_WCHAR_T* outputFormat Service output format, must be set to L"JSON"
SDK_BOOL useProxy If true, use the given proxy server
SDK_BOOL useGZIP If true, use gzip
SDK_UINT4 timeout Server timeout [s]
SDK_BOOL doGetVolumeStatistics Retrieve server traffic volume statistics when set to true, not supported on every platform, see also SDK_GetTrafficSearchResultStatistics
SDK_BOOL doLogging If true, all incoming traffic data will get logged into files
SDK_BOOL doSimulation If true, the traffic data will be read from log files instead of fetching it from the server
const SDK_WCHAR_T* directoryLogging The directory where the traffic data should be logged, set to NULL if not used
const SDK_WCHAR_T* directorySimulation The directory from where the simulation data should be read, set to NULL if not used

As you can see, there are many options for configuring the server access, but most of the fields should be set to their default value that is given in the table.

After setting the web configuration, we call SDK_SearchTrafficInformation() with an SDK_TrafficSearchRequest struct. This struct holds information necessary for the upcoming search, such as the position the search should be started from, the range of the search, the type of search and the language of the retrieved messages.

The struct SDK_TrafficSearchRequest has the following members:

Type Name Description
SDK_HDRINFO size Size of struct - for controlling
SDK_HDRINFO version Version of struct - for controlling. Use SDK_TrafficSearchRequestVERSION
SDK_Position pos Center position to search traffic info [merc]
SDK_Position targetPos Optional target position for spanning a rectangle from start to target if type == SDK_TI_SEARCH_BOX
SDK_UINT4 distance First distance [km] to search from the given point, see comment below for details
SDK_UINT4 distance2 Second distance [km] to search from the given point, see comment below for details
SDK_UINT4 distance3 Third distance [km] to search from the given point, see comment below for details
SDK_UINT4 radius First radius [km] to search from the given point, see comment below for details
SDK_UINT4 radius2 Second radius [km] to search from the given point, see comment below for details
SDK_UINT4 radius3 Third radius [km] to search from the given point, see comment below for details
const SDK_WCHAR_T* filter Internal use only, must be set to NULL
const SDK_WCHAR_T* filter2 Internal use only, must be set to NULL
const SDK_WCHAR_T* filter3 Internal use only, must be set to NULL
SDK_INT4 languageCode Language code for the message text, see TrafficIsoCode for details
SDK_INT4 type Type of the search, see TrafficSearchMode for more details.

The distance and radius values describe the search distances in different situations. If type is set to SDK_TI_SEARCH_NORMAL, one search request will be sent to the server, if type is SDK_TI_SEARCH_COMPLEX, three requests will be sent.

In complex mode, the three requests differ in the expansion of the search and the road types which will be searched for traffic.
The road filtering is done by three filter parameters. These parameters will be set internally, so that in a complex search, the farther the distance is, only incidents on bigger roads are searched to minimize the data volume of a search. Manual filter setting needs a knowledge of the traffic server API, so set the filters to NULL to use the internal predefined values.

There are two main scenarios:

  • There is actually no route available: Traffic is searched in one or more circles around the given position. When SDK_TI_SEARCH_NORMAL is set, only one circle search is used with the value of "radius". When SDK_TI_SEARCH_COMPLEX is used, for every given radius a search request will be started with the approriate filter.
  • There is a route available: When SDK_TI_SEARCH_NORMAL is set, we search in a rectangular box around the route with a diagonal size of "distance" from the startpoint towards the route. This box will be enlarged by about 5%. When SDK_TO_SEARCH_COMPLEX is set, three boxes are created, each of them like in SDK_TI_SEARCH_NORMAL, box1 with "distance", box2 with "distance2" and box3 with "distance3". The boxes will be enlarged by an appropriate value of the radius parameters. The boxes and circles can be visualized by calling SDK_SetUserParam() with the first parameter set to SDK_SUP_DRAW_TRAFFIC_REQUEST_BOUNDINGS.

For now, we will set the required missing request parameters to:

  • distance = 30
  • distance2 = 60
  • distance3 = 100
  • radius = 50
  • radius2 = 100
  • radius3 = 300
  • type = SDK_TI_SEARCH_COMPLEX
  • languageCode = SDK_TI_ISO_EN

To set the web configuration, the initial search request parameters and to start a search, we add the following in our NavigationLoop class:

NavigationLoop.h: 

...
class NavigationLoop : public QObject, public QRunnable
{   
    Q_OBJECT
public:
    ...
    static SDK_INT4 SDK_API trafficCallback(SDK_INT4 current, SDK_INT4 total, SDK_INT4 job, SDK_ERROR error);
    void setTrafficWebConfig();
    void initTrafficRequest();
    void setTrafficSearchPosition(const SDK_Position& pos);
private:
    ...
    SDK_TrafficSearchRequest mTrafficRequest;
    SDK_TrafficSearchWebConfiguration mTrafficWebConfiguration;
signals:
    ...
    void trafficFinished(int);

NavigationLoop.cpp: 

NavigationLoop::NavigationLoop(MapWidget * map, TTSEngine * ttsEngine) : QObject(), QRunnable()
{
    ...
    setTrafficWebConfig();
    initTrafficRequest();
}
...
long loop = 0;
void NavigationLoop::run()
{
    SDK_GPSData gps;
    SDK_ERROR rc = GPSManager::getInstance()->getCurrentPosition(gps);
    if (rc == SDK_ERROR_Ok || rc == SDK_ERROR_SamePosition)
    {               
        if ((loop % 100) == 0)
        {
            setTrafficSearchPosition(gps.GPSPositionMerc);
            rc = SDK_SearchTrafficInformation(&mTrafficRequest, trafficCallback);
        }
        ...
    }
    ...
    loop++;
}

void NavigationLoop::setTrafficWebConfig()
{
    SDK_InitTrafficSearchWebConfiguration(&mTrafficWebConfiguration);

    mTrafficWebConfiguration.url = L"http://ti.ptvgroup.com/wfs";
    mTrafficWebConfiguration.proxy = 0;
    //mTrafficWebConfiguration.token = L"<YOUR TOKEN HERE PLEASE>";
    mTrafficWebConfiguration.service = L"WFS";
    mTrafficWebConfiguration.serviceVersion = L"1.0.0";
    mTrafficWebConfiguration.request = L"GetFeature";
    mTrafficWebConfiguration.typeName = L"ptvgroup:tomtom_incidents";
    mTrafficWebConfiguration.outputFormat = L"JSON";
    mTrafficWebConfiguration.timeout = 30;
    mTrafficWebConfiguration.useProxy = SDK_FALSE;
    mTrafficWebConfiguration.useGZIP = SDK_TRUE;
    mTrafficWebConfiguration.doLogging = SDK_FALSE;
    mTrafficWebConfiguration.doSimulation = SDK_FALSE;
    mTrafficWebConfiguration.doGetVolumeStatistics = SDK_TRUE;

    mTrafficWebConfiguration.directoryLogging = 0;
    mTrafficWebConfiguration.directorySimulation = 0;
}

void NavigationLoop::initTrafficRequest()
{
    SDK_InitTrafficSearchRequest(&mTrafficRequest);

    mTrafficRequest.distance = 30;
    mTrafficRequest.distance2 = 60;
    mTrafficRequest.distance3 = 100;
    mTrafficRequest.radius = 50;
    mTrafficRequest.radius2 = 100;
    mTrafficRequest.radius3 = 300;
    mTrafficRequest.type = SDK_TI_SEARCH_COMPLEX;
    mTrafficRequest.languageCode = SDK_TI_ISO_EN;
}

void NavigationLoop::setTrafficSearchPosition(const SDK_Position& pos)
{
    mTrafficRequest.pos = pos;
}

We initialize the web configuration with a valid url, the traffic token and the standard parameters like in the table above in setTrafficWebConfig(). Also, we initialize the search request with some example parameters. We won't change the language or the search type in this tutorial, so we only have to update the GPS position in our NavigationLoop::run() function before calling SDK_SearchTrafficInformation(). We do this by calling setTrafficSearchPosition() with the current position. After that, we start the search. To avoid searching every time the function is called (that would be around every 200ms), we add a variable called "loop" to reduce the update interval. SDK_SearchTrafficInformation() will return immediately because it spawns a new thread which takes care of traffic fetching.

The traffic callback

The SDK will call our callback function trafficCallback() when a previously triggered search has finished. The parameters of the callback are:

  • current: Always set by the SDK to 100, no need to check
  • total: Always set by the SDK to 100, no need to check
  • job: The job id. Can be either SDK_TI_JOB_SEARCH or SDK_TI_JOB_UPDATE. The first determines that the callback was triggered after a real search has taken place. The second will be set when the traffic items are updated without a search.
  • error: The error code the search returned

In our callback we emit the signal trafficFinished(), so we can react to the incoming events in our MainWindow (and therfore in the GUI thread).

Add the following code to the NavigationLoop class:

NavigationLoop.cpp 

...
SDK_INT4 SDK_API NavigationLoop::trafficCallback(SDK_INT4 current, SDK_INT4 total, SDK_INT4 job, SDK_ERROR error)
{    
    emit pThis->trafficFinished(error);
    return 1;
}

The receiver of this signal is void onTrafficFinished(int error) in our MainWindow class, so add the following code to the MainWindow class:

MainWindow.h: 

...
protected slots:
    ...
    void onTrafficFinished(int error);
...

MainWindow.cpp: 

MainWindow::MainWindow(QMainWindow * parent) : QMainWindow(parent)
{
    ...
    connect(mNavigationLoop, SIGNAL(trafficFinished(int)), this, SLOT(onTrafficFinished(int)));
    ...
}
...

void MainWindow::onTrafficFinished(int error)
{
    SDK_TrafficSearchResult * trafficResult;
    SDK_UINT4 trafficCount = 0;
    SDK_GetTrafficSearchResult(&trafficResult, &trafficCount, 0, 0);

    for (size_t i = 0; i < trafficCount; i++)
    {
        qDebug(trafficResult[i].description);
    }
}

We connect the signal trafficFinished() from the NavigationLoop with the onTrafficFinished() slot in the MainWindow constructor. The onTrafficFinished() function will retrieve the search results by calling SDK_GetTrafficSearchResult(). We then iterate over the returned results and output the description of the current result to the console.

Start the program and take a look at the Output window. When the search has finished, the descriptions of the traffic incidents will be printed to the console. Also, the incidents will be shown on the map.

Traffic dialog

Now we are going to show the traffic search results in a separate dialog. Let's take a look at the trafficdialog.ui file in the designer:

As you can see, this is a very simple dialog with only one listview as the central widget. The implementation of the class looks like this:

TrafficDialog.cpp: 

#include "../navigationsdk//SDKInterface.h"
#include "TrafficDialog.h"

TrafficDialog::TrafficDialog(QWidget *parent)
    : QDialog(parent)
{
    ui.setupUi(this);
    ui.listView->setModel(&mModel);
}

TrafficDialog::~TrafficDialog()
{
}

void TrafficDialog::setData(const std::vector<SDK_TrafficSearchResult>& result)
{
    mModel.setData(result);
}
To show the traffic incidents in the listview, we create a model called TrafficModel. We set this model to the listview and add a function TrafficDialog::setData() to add data to this model.

The model itself is subclassed from QAbstractListModel. In the data() function, it will return a QString representation of the description of a particular incident for showing in our listview:

TrafficModel.cpp: 

...
void TrafficModel::setData(const std::vector<SDK_TrafficSearchResult>& result)
{
    removeRows(0, mResult.size());
    mResult = result;
    QModelIndex topLeft = createIndex(0, 0);
    QModelIndex topBottomRight = createIndex(mResult.size() - 1, 0);
    emit dataChanged(topLeft, topBottomRight);
}

int TrafficModel::rowCount(const QModelIndex & /*parent*/) const
{
    return mResult.size();
}

QVariant TrafficModel::data(const QModelIndex &modelIndex, int role) const
{

    int index = modelIndex.row();

    if (role == Qt::DisplayRole)
    {
        return QString(mResult[index].description);
    }

    return QVariant();
}

To show the traffic dialog, we added a new action (in the mainwindow.ui) called actionShowTrafficResults to our MainWindow menu. We connect this action to the new slot actionShowTrafficResultsTriggered(), which will create a new traffic dialog.
The traffic dialog needs the traffic search result for showing the incidents. Therefore, we save the search result to the variable mTrafficResult in MainWindow::onTrafficFinished().

Add/Change the following to the MainWindow class:

MainWindow.h: 

...
#include "TrafficDialog.h"

class MainWindow : public QMainWindow
{
...
protected slots:
    ...
    void actionShowTrafficResultsTriggered(bool triggered);
private:
    std::vector<SDK_TrafficSearchResult> mTrafficResult;
    TrafficDialog * mTrafficDialog;
}

MainWindow.cpp: 

MainWindow::MainWindow(QMainWindow * parent) : QMainWindow(parent)
{
    ...
    mTrafficDialog = 0;
    connect(ui.actionShowTrafficResults, SIGNAL(triggered(bool)), this, SLOT(actionShowTrafficResultsTriggered(bool)));
}
...

void MainWindow::actionShowTrafficResultsTriggered(bool checked)
{
    disableNavigationLoopTimer();
    if (mTrafficDialog)
    {
        mTrafficDialog->setData(mTrafficResult);
        mTrafficDialog->exec();
    }       
    else
    {
        mTrafficDialog = new TrafficDialog(this);
        mTrafficDialog->setData(mTrafficResult);
        mTrafficDialog->exec();
    }
    enableNavigationLoopTimer();
}

void MainWindow::onTrafficFinished(int error)
{
    SDK_TrafficSearchResult * trafficResult;
    SDK_UINT4 trafficCount = 0;
    SDK_GetTrafficSearchResult(&trafficResult, &trafficCount, 0, 0);
    mTrafficResult.clear();
    mTrafficResult.reserve(trafficCount);
    for (size_t i = 0; i < trafficCount; i++)
    {
        mTrafficResult.push_back(trafficResult[i]);
    }

    if (trafficCount > 0)
        ui.actionShowTrafficResults->setEnabled(true);
    else
        ui.actionShowTrafficResults->setEnabled(false);
    ui.map->update();
}

MainWindow:: ~MainWindow()
{
    ...
    if (mTrafficDialog)
        delete mTrafficDialog;
}

In the destructor of our MainWindow, we delete the traffic dialog.

Now we can see the traffic results in our traffic dialog: