MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Location API

The Location API provides a library for location positioning, landmark management and mapping and navigation.


The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of QtMobility APIs into Qt. See the Quickstart guide for an example on how the namespace impacts on application development.

Location Positioning

Location data involves a precisely specified position on the Earth's surface — as provided by a latitude-longitude coordinate — along with associated data, such as:

  • The date and time at which the position was reported
  • The velocity of the device that reported the position
  • The altitude of the reported position (height above sea level)
  • The bearing of the device in degrees, relative to true north

This data can be extracted through a variety of methods. One of the most well known methods of positioning is GPS (Global Positioning System), a publicly available system that uses radiowave signals received from Earth-orbiting satellites to calculate the precise position and time of the receiver. Another popular method is Cell ID positioning, which uses the cell ID of the cell site that is currently serving the receiving device to calculate its approximate location. These and other positioning methods can all be used with the Location API; the only requirement for a location data source within the API is that it provides a latitude-longitude coordinate with a date/time value, with the option of providing the other attributes listed above.

Location data sources are created by subclassing QGeoPositionInfoSource and providing QGeoPositionInfo objects through the QGeoPositionInfoSource::positionUpdated() signal. Clients that require location data can connect to the positionUpdated() signal and call startUpdates() or requestUpdate() to trigger the distribution of location data.

A default position source may be available on some platforms. Call QGeoPositionInfoSource::createDefaultSource() to create an instance of the default position source; the method returns 0 if no default source is available for the platform.

The QGeoAreaMonitor class enables client applications to be notified when the receiving device has moved in or out of a particular area, as specified by a coordinate and radius. If the platform provides built-in support for area monitoring, QGeoAreaMonitor::createDefaultMonitor() returns an instance of the default area monitor.

Satellite information can also be distributed through the QGeoSatelliteInfoSource class. Call QGeoSatelliteInfoSource::createDefaultSource() to create an instance of the default satellite data source for the platform, if one is available. Alternatively, clients can subclass it to provide a custom satellite data source.

Requesting location data from data sources

To receive data from a source, connect to its positionUpdated() signal, then call either startUpdates() or requestUpdate() to begin.

Here is an example of a client that receives data from the default location data source, as returned by QGeoPositionInfoSource::createDefaultSource():

 class MyClass : public QObject
     MyClass(QObject *parent = 0)
         : QObject(parent)
         QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(this);
         if (source) {
             connect(source, SIGNAL(positionUpdated(QGeoPositionInfo)),
                     this, SLOT(positionUpdated(QGeoPositionInfo)));

 private slots:
     void positionUpdated(const QGeoPositionInfo &info)
         qDebug() << "Position updated:" << info;

Controlling aspects of data sources

The QGeoPositionInfoSource::setUpdateInterval() method can be used to control the rate at which position updates are received. For example, if the client application only requires updates once every 30 seconds, it can call setUpdateInterval(30000). (If no update interval is set, or setUpdateInterval() is called with a value of 0, the source uses a default interval or some other internal logic to determine when updates should be provided.)

QGeoPositionInfoSource::setPreferredPositioningMethods() enables client applications to request that a certain type of positioning method be used. For example, if the application prefers to use only satellite positioning, which offers fairly precise outdoor positioning but can be a heavy user of power resources, it can call this method with the QGeoPositionInfoSource::SatellitePositioningMethods value. However, this method should only be used in specialized client applications; in most cases, the default positioning methods should not be changed, as a source may internally use a variety of positioning methods that can be useful to the application.

Reading NMEA data

NMEA is a common text-based protocol for specifying navigational data. For convenience, the QNmeaPositionInfoSource is provided to enable client applications to read and distribute NMEA data in either real-time mode (for example, when streaming from a GPS device) or simulation mode (for example, when reading from a NMEA log file). In simulation mode, the source will emit updates according to the time stamp of each NMEA sentence to produce a "replay" of the recorded data.

Example: Creating a custom location data source

Generally, the capabilities provided by the default position source as returned by QGeoPositionInfoSource::createDefaultSource(), along with the QNmeaPositionInfoSource class, are sufficient for retrieving location data. However, in some cases developers may wish to write their own custom location data sources.

The LogFilePositionSource class in examples/logfilepositionsource shows how to subclass QGeoPositionInfoSource to create a custom location data source.

This example class reads location data from a text file, log.txt. The file specifies location data using a simple text format: it contains one location update per line, where each line contains a date/time, a latitude and a longitude, separated by spaces. The date/time is in ISO 8601 format and the latitude and longitude are in degrees decimal format. Here is an excerpt from log.txt:

     2009-08-24T22:25:01 -27.576082 153.092415
     2009-08-24T22:25:02 -27.576223 153.092530
     2009-08-24T22:25:03 -27.576364 153.092648

The class reads this data and distributes it via the positionUpdated() signal.

Here is the definition of the LogFilePositionSource class:

 class LogFilePositionSource : public QGeoPositionInfoSource
     LogFilePositionSource(QObject *parent = 0);

     QGeoPositionInfo lastKnownPosition(bool fromSatellitePositioningMethodsOnly = false) const;

     PositioningMethods supportedPositioningMethods() const;
     int minimumUpdateInterval() const;

 public slots:
     virtual void startUpdates();
     virtual void stopUpdates();

     virtual void requestUpdate(int timeout = 5000);

 private slots:
     void readNextPosition();

     QFile *logFile;
     QTimer *timer;
     QGeoPositionInfo lastPosition;

The main methods overrided by the subclass are:

  • startUpdates(): called by client applications to start regular position updates
  • stopUpdates(): called by client applications to stop regular position updates
  • requestUpdate(): called by client applications to request a single update, with a specified timeout

When a position update is available, the subclass emits the positionUpdated() signal.

Here are the key methods in the class implementation:

 LogFilePositionSource::LogFilePositionSource(QObject *parent)
     : QGeoPositionInfoSource(parent),
       logFile(new QFile(this)),
       timer(new QTimer(this))
     connect(timer, SIGNAL(timeout()), this, SLOT(readNextPosition()));

             + QDir::separator() + "simplelog.txt");
     if (!logFile->open(QIODevice::ReadOnly))
         qWarning() << "Error: cannot open source file" << logFile->fileName();

 void LogFilePositionSource::startUpdates()
     int interval = updateInterval();
     if (interval < minimumUpdateInterval())
         interval = minimumUpdateInterval();


 void LogFilePositionSource::stopUpdates()

 void LogFilePositionSource::requestUpdate(int /*timeout*/)
     // For simplicity, ignore timeout - assume that if data is not available
     // now, no data will be added to the file later
     if (logFile->canReadLine())
         emit updateTimeout();

 void LogFilePositionSource::readNextPosition()
     QByteArray line = logFile->readLine().trimmed();
     if (!line.isEmpty()) {
         QList<QByteArray> data = line.split(' ');
         double latitude;
         double longitude;
         bool hasLatitude = false;
         bool hasLongitude = false;
         QDateTime timestamp = QDateTime::fromString(QString(data.value(0)), Qt::ISODate);
         latitude = data.value(1).toDouble(&hasLatitude);
         longitude = data.value(2).toDouble(&hasLongitude);

         if (hasLatitude && hasLongitude && timestamp.isValid()) {
             QGeoCoordinate coordinate(latitude, longitude);
             QGeoPositionInfo info(coordinate, timestamp);
             if (info.isValid()) {
                 lastPosition = info;
                 emit positionUpdated(info);

The example includes a ClientApplication class that requests updates from the LogFilePositionSource class. Run the example to see the data that is received by ClientApplication.

Before running the example, make sure you have done both make and make install.

QML Elements

For details on the QML support provided for the Location API see the documentation for the Location QML Plugin.


Flickr Demo

The Flickr Demo uses the Location to download thumbnail images from Flickr relevant to the current location.

Weather Info Demo

The Weather Info demo uses Location display data about the weather for the current location.

Light Maps Demo

The Light Maps demo uses Location display a street map for the current location.

QML Example

Examples using the Location QML Plugin demonstrate how to use the QML/C++ bindings to easily access the Location API features.

Flickr QML Example

The Flickr example now in the form of a QML application. This also displays in the form of a mobile application.

Location classes


Represents an address


Enables the detection of proximity changes for a specified set of coordinates


Defines a geographical position on the surface of the Earth


Represents basic information about a place


Contains information gathered on a global position, direction and velocity at a particular point in time


Abstract base class for the distribution of positional updates


Factory class used as the plugin interface for external providers of positioning data


Contains basic information about a satellite


Abstract base class for the distribution of satellite information updates


Positional information using a NMEA data source


The Landmarks portion of the Location API facilitates the creation, retrieval, updating and deletion of landmarks from arbitrary data stores.

A landmark is a location of some significance, also known as a point of interest and are represented as QLandmark objects. Related landmarks may be grouped into categories(QLandmarkCategory) such as restaurants or accommodation and each landmark can belong to more than one category.

A landmark datastore is represented by a QLandmarkManager. The QLandmarkManager may be used to save, fetch and remove both landmarks and categories. When fetching landmarks we can provide various filters and sort orders to define the searching criteria and the order in which landmarks are returned. The QLandmarkManager also provides functionality to import and export landmarks as well as provide notifications whenever changes are detected. It should be noted that the Landmarks API provides both synchronous and asynchronous mechanisms to perform the above operations. Synchronous operations are provided the QLandmarkManager itself while the asynchronous operations are provided by various request classes. It is generally recommended that the asynchronous request classes classes be used as they are not subject to blocking which can be an issue if a datastore contains a significantly large number of landmarks or if the datastore is being accessed over a network.

Landmark operation examples

For more details see the Landmark Examples page for:

Managers and plugins

Landmark managers are identified by their manager name. Each manager name corresponds to a specific plugin/backend that implements the manager functionality. The manager name is typically a reverse domain string such as "". Typically a developer does not need to deal with the manager name as the default manager will be used when instantiating a QLandmarkManager without construction parameters.

To implement your own plugin, you need to subclass QLandmarkManagerEngine and provide the implmementations for the virtual functions, and then create a QLandmarkMangerEngineFactory subclass that will instantiate your particular engine implementation.

The following table shows names of the default managers for each platform and where the landmarks are stored.

Manager name Platform Landmark storage S60 3.1,3.2,5.0, Symbian Uses the S60 Platform Landmarks API to store data into the default/global landmark database. Maemo5, Windows Xp/Vista,Linux, Mac OS X Landmarks are stored in an SQLite database. Harmattan,Meego Landmarks are stored in Tracker using SPARQL queries.

These managers only store and retrieve landmark data locally. This landmark data is available to any application which accesses the manager and is thus shared between all applications. At present there are no managers which retrieve landmark data from online sources.

For convenience, this documentations refers to the manager corresponding to as the symbian manager, the manager corresponding to as the sqlite manager, and the manager corresponding to as the sparql manager.

Variations between platforms/managers

The behaviour of some parts of the Landmarks API varies between platforms. A few of the major ones are mentioned below

  • The symbian manager does not support the MatchContains flag in the attribute filters. The symbian manager also does not support multiple attributes with an AND operation type in an attribute filter. Some versions of s60 do not support the MatchContains flag in name filters. See the documentation on the attribute and name filters for more details.
  • The sparql manager does not support the countryCode field of QGeoAddress. This field is ignored when a landmark is saved. As of QtMobility 1.2.1 support for district and county fields were added to the sparql manager, note that a tracker version of 0.9.35 or greater is required.

Importing and Exporting Landmarks

The landmarks API supports import and exporting of landmarks. The file formats that are supported depends on the particular manager. The following table outline the formats that may be used for the default manager on each platform. You may also query the supported formats through the QLandmarkManager::supportedFormats() function.

Platform Import formats Export formats
S60 3.1,3.2 Lmx Lmx
S60 5.0 Gpx, Lmx Lmx
Symbian Gpx, Lmx, Kml, Kmz Lmx
Maemo 5, windows, linux Lmx, Gpx(version 1.1 only) Lmx, Gpx(vesion 1.1 only)

During an import operation, every landmark from the import source will result in the creation of a new landmark, however any categories defined in the import source will be mapped to existing categories if possible. If a mappping cannot be found then a new category is created.

During an import or export operation,the QLandmarkManager::TransferOption can be used to decide what to do with category data, provided the given format supports them. (For formats such as gpx which do not support categories, the transfer option is ignored). Typically, any categories are included as is with QLandmarkManager::IncludeCategoryData being the default option. You may choose to ignore any categories by providing using QLandmarkManager::ExcludeCategoryData. For an import operation, you can use QLandmarkManager::AttachSingleCategory in conjunction with a QLandmarkCategoryId, to have all imported landmarks be assigned to that category(any exisiting category associations defined in the import source are ignored).

The export operation by default exports all landmarks within the manager. If you wish to export only a subset you can provide a list of landmark ids to do so. One caveat with exporting landmarks to gpx format is that the gpx does not support landmarks which have NaN latitude and longitude values. If you try to export all landmarks, then those landmarks with NaN values are skipped over. However if you provide a list of ids of landmarks to export, the export operation will fail if any one of those landmarks have NaN latitude or longitude values.

Also note that when exporting landmarks in lmx format, the url of the landmark should be a valid absolute URI as specified in the Landmark Exchange Format Specification 1.0. If the URI is relative, then the url of that landmark is not exported.

Landmark classes

Main Landmark Classes


Represents a point of interest


Designates a grouping of landmarks of similar type


Unique identifier for a category


Unique identifier for a landmark


Interface for storage and retrieval of landmarks from a landmark store

Landmark Selection classes

Landmark selection is facilitated by filter and sort order classes. The filter classes define what criteria that landmarks must match and the sort order classes specify how the returned landmarks are sorted. Please note that sorting by distance is facilitated by the QLandmarkProximity class. Providing a QLandmarkProximity filter in an intersection filter will sort results in order of ascending distance (on the condition only a default sort order class is used in conjunction). The filter and sort order classes are used with either the QLandmarkManager class (for synchronous landmark selection) or the request classes for (asynchronous landmark selection)



Filtering on various landmark attributes


Used to search for landmarks within a given bounding box


Used to search for landmarks that belong to a certain category


Serves as the base class for all filter classes. Also serves as the default filter which retrieves all landmarks


Used to search for landmarks based on a list of landmark identifiers


Filter which intersects the results of its constituent filters


Used to search for landmarks by name


Used to search for landmarks based on the radius around a given coordinate and perform sorting by distance


Filter which unions the results of its constituent filters



Used to sort landmarks by name


Serves as a base class for the different sort order types and by itself represents no sorting

Asynchronous Requests

Asynchronous operations are facilitates by the request classes listed below:


The interface from which all asynchronous request classes inherit


Allows a client to asynchronously request a list of categories by ID from a landmark manager


Allows a client to asynchronously request a list of categories from a landmark manager


Allows a client to asynchronously request a list of category identifiers from a landmark manager


Allows a client to asynchronously request that certain categories be removed from a landmark manager


Allows a client to asynchronously request that certain categories be saved by a landmark manager


Allows a client to asynchronously request that a landmark manager export a set of landmarks


Allows a client to asynchronously request a list of landmarks by id from a landmark manager


Allows a client to asynchronously request a list of landmarks from a landmark manager


Allows a client to asynchronously request a list of landmark identifiers from a landmark manager


Allows a client to asynchronously request that a landmark manager import a set of landmarks


Allows a client to asynchronously request that certain landmarks be removed from a landmark manager


Allows a client to asynchronously request that certain landmarks be saved by a landmark manager

Implementing backends

A manager backend may be implemented by subclassing QLandmarkManagerEngine, and providing a QLandmarkManagerEngineFactory which can instantiate it when required.


The interface for all implementations of the landmark manager backend functionality


The interface for plugins that implement QLandmarkManagerEngine functionality

Maps and Navigation

The Maps and Navigation API is based on plugins.

Since most providers of mapping, geocoding and routing information offer no guarantees that their data is interoperable with the data provided by other services, the plugins are used to group the functionality per service provider.

The plugins are accessed via QGeoServiceProvider, and a Nokia based plugin is part of QtMobility. See the section The Nokia plugin for more details.

     QGeoMappingManager *mappingManager = 0;
     QGeoRoutingManager *routingManager = 0;
     QGeoSearchManager *searchManager = 0;

     QGeoServiceProvider serviceProvider("plugin name");

     if (serviceProvider.error() == QGeoServiceProvider::NoError) {
         mappingManager = serviceProvider.mappingManager();
         routingManager = serviceProvider.routingManager();
         searchManager = serviceProvider.searchManager();

Important notice: The map data provided by the offline plug-in is place-shifted for the area of the People's Republic of China. To provide un-shifted maps of China in an application, the application developer must first obtain permission from Chinese officials. The Qt Mobility Location API cannot offer this on the API level.

Common classes


Defines a geographic area


Defines a rectangular geographic area


Defines a circular geographic area


Aggregates access to services which provide geographical information


The QGraphicsGeoMap class is the main class used for displaying and interacting with maps. It is designed for use within the Graphics View Framework, and is a subclass of QGraphicsWidget.

The QGeoMappingManager provides most of the functionality required by QGraphicsGeoMap. The details of QGeoMappingManager are mostly only important to plugin implementers, as regular users should not need to make use of QGeoMappingManager outside of the QGraphicsGeoMap constructor:

     QGraphicsGeoMap *map = new QGraphicsGeoMap(mappingManager);


Used to draw overlays on the map


Support for displaying and interacting with maps


Used to display a map and manager the interactions between the user and the map

Map objects

QGeoMapObject and its subclasses provide the ability to add graphics to the map specified in terms of coordinates and distances. QGeoMapObject instances can also be grouped into heirarchies in order to simplify the process of creating compound objects and managing groups of objects.


QGeoMapObject used to draw the region within a given distance of a coordinate


QGeoMapObject used to draw a QGraphicsItem on a map


QGeoMapObject used to manager a group of other map objects


Graphical item to be displayed on a map


QGeoMapObject used to draw a pixmap on a map


QGeoMapObject used to draw a polygon on a map


QGeoMapObject used to draw a segmented line on a map


QGeoMapObject used to draw a rectangular region on a map


QGeoMapObject used to draw a route on a map


QGeoMapObject used to draw text on a map


QGeoRoutingManager handles requests for routing information.

The requests are created as QGeoRouteRequest instances, which are passed to QGeoRoutingManager::calculateRoute(). The returned QGeoRouteReply instance will contain the result of the request when it is completed.

The QGeoRoute class describes the resulting route. Each route is broken up into a number of QGeoRouteSegment instances, with the division usually occurring at either user specified waypoints or at changes in the mode of transport, like when changing from a train to a bus.

Each QGeoRouteSegment has a QGeoNavigationInstruction instance which describes the instructions that would be issued to a user attempting to follow a route. These instructions a location, which is typically somewhere near the end of the associated QGeoRouteSegment, and instruction text describing how the next QGeoRouteSegment should be reached.


Represents the information relevant to the point at which two QGeoRouteSegments meet


Represents a route between two points


Manages an operation started by an instance of QGeoRoutingManager


Represents the parameters and restrictions which define a request for routing information


Represents a segment of a route


Support for geographic routing operations

Geocoding and searching for places

QGeoSearchManager handles geocoding, reverse geocoding and free-text search for places.

The free-text search will attempt to geocode text that looks like an address while simultaneously searching any landmark databases that the service provides. It is even possibly to add additional QLandmarkManager instances to the soures of data, so that users can search online databases alongside their personal offline landmarks store.


Support for searching operations related to geographic information


Manages an operation started by an instance of QGeoSearchManager

The Nokia plugin

QtMobility ships with a Maps and Navigation API plugin which accesses the relevant Ovi services provided Nokia. The use of these services is governed by the terms and conditions available inedi.ntcn the file plugins/geoservices/nokia/OVI_SERVICES_TERMS_AND_CONDITIONS.txt.

The Ovi services plugin can be loaded by using the plugin key "nokia".

Note that accepting the terms and conditions only applies those terms and conditions to the use of the Ovi Maps Services plugin and does not limit the use of the other maps and navigation API plugins that may be included with the QtMobility package.

On Symbian platforms the applications using the Nokia plugin will need NetworkServices capability to access the online services.

The routing feature of the Nokia plugin is not available for the People's Republic of China.

The online plugin uses the tiled map classes, which cache tile data in heap memory (currently up to 10 MB on Symbian and Maemo5 and Harmattan platforms). Because default heap size for Qt application on Symbian is 4 MB, it may be good idea to increase the application's heap size using EPOCHEAPSIZE.

The following table lists optional parameters that can be passed to the Nokia plugin.

Parameter Description
mapping.proxy Proxy server URL used by mapping manager. Map tile service URL used by mapping manager.
mapping.referer Referer for the mapping token used for authentication by mapping manager.
mapping.token Client token for the service used for authentication by mapping manager.
mapping.app_id Client application id for the serviced used for authentication by mapping manager. Can be obtained from here. Map tile cache directory used as network disk cache.

Default place for the cache is "maptiles" directory in system temp.

On Symbian platform by default the cache is placed into internal mass memory drive directory "/data/nokia/maptiles".

If no internal mass memory is present on Symbian device caching is not used by default.

Changing the cache directory on Symbian may cause additional capability needs depending on where the new directory is placed.

Map tile caching is disabled on Maemo, Meego and Windows CE platforms. Using the parameter on these platforms will have no effect.

Map tiles will expire and are refetched 14 days after download.

mapping.cache.size Map tile cache size. Maximum size of the cache is 50MB.
routing.proxy Proxy server URL used by routing manager. Routing service URL used by routing manager.
routing.referer Referer for the routing token used for authentication by routing manager.
routing.token Client token for the service used for authentication by routing manager.
routing.app_id Client application id for the serviced used for authentication by routing manager. Can be obtained from here.
places.proxy Proxy server URL used by search manager. Search service URL used by search manager.
places.referer Referer for the places token used for authentication by search manager.
places.token Client token for the service used for authentication by search manager.
places.app_id Client application id for the serviced used for authentication by search manager. Can be obtained from here.
logo.position Optional parameter for changing logo position. Valid values are: top.left or top.right or bottom.left or left.bottom bottom.right or right.bottom

Implementing plugins

A plugin implementer needs to subclass QGeoServiceProviderFactory and as many of the ManagerEngine classes as they want to provide implementations for.

Subclassing QGeoServiceProviderFactory will only involve exposing a name and a version by overriding QGeoServiceProviderFactory::providerName() and QGeoServiceProviderFactory::providerVersion(), and overriding QGeoServiceProviderFactory::createSearchManagerEngine(), QGeoServiceProviderFactory::createMappingManagerEngine() and QGeoServiceProviderFactory::createRoutingManagerEngine() as appropriate.


Are used as a bridge between QGraphicsGeoMap and QGeoMappingManager


The base class used to define the parts of QGeoMapObject and its subclasses that are specific to a particular QGeoMapData subclass


Interface and convenience methods to implementors of QGeoServiceProvider plugins who want to provides support for displaying and interacting with maps


Interface and convenience methods to implementers of QGeoServiceProvider plugins who want to provide access to geographic routing information


Interface and convenience methods to implementers of QGeoServiceProvider plugins who want to provide support for searching operations related to geographic data


Factory class used as the plugin interface for services related to geographical information

Tile-based map convenience classes

Most of the current tile based mapping APIs are very similar, and so we provide a number of classes intended to make writing tile based mapping plugins much simpler.

If the Mercator projection and the most common tile addressing scheme is used this will mainly involve subclassing QGeoTiledMappingManagerEngine and providing an implementation of QGeoTiledMappingManagerEngine::getTileImage().


Subclass of QGeoMapData provided to make working with tile based mapping services more convenient


Manages a tile fetch operation started by an instance of QGeoTiledManagerEngine


Represents a request for a map tile from a tile-based mapping service


Provided to make writing Qt Maps and Navigation API plugins for tiled based mapping services easier

QML Elements

For details on the QML support provided for the Location API see the documentation for the Location QML Plugin.