Provisioning OpenStreetMap providers in QtLocation

Published Thursday March 9th, 2017
7 Comments on Provisioning OpenStreetMap providers in QtLocation
Posted in Dev Loop, Qt Location


This post is to provide some clarification on a behavioral change we had to introduce with Qt 5.6.2 to the QtLocation‘s OpenStreetMap plug-in. The related change seems to have generated some confusion, so here’s the full story.

The OSM plug-in used to work with hard-coded tile server URLs for the various map types offered therein. The tiles for the main (street) map type and the satellite map type, which are possibly the two most used maps, were previously sourced from In July 2016, MapQuest discontinued this service. As a result, all deployed QtLocation OSM plug-ins for the Qt versions up to 5.6.1 and 5.7.0 suddenly began to provide tiles without map content. Instead the tiles contained an invitation to visit the MapQuest website and buy some services as shown below.

MapQuest ceasing open access

The dreadful sight from the MapViewer prior to Qt5.6.2


Clearly not being able to afford another such situation, we decided to fix this by adding one level of indirection. Now the OSM plug-in will fetch, for each map type, a provider definition file hosted at The format of this file is fairly similar to what others solutions use (e.g. TileJSON), with small differences needed for our specific use case. The format is documented in this file (starting from line 195). This solution makes it possible to change the tile source for specific map types, if this becomes necessary again, without the need to upgrade Qt or to rebuild the application.

These providers can also be temporarily disabled on the server side, by setting the property Enabled to false. This might happen in cases like the above mentioned where the service delivers bogus tiles and a replacement hasn’t been found yet. The plug-in also ships with a hard-coded backup for connectivity reasons.

Unfortunately, at this stage we haven’t been able to find an open access satellite imagery provider that would provide sufficiently high resolution data. As a result, the OSM plug-ins initially still offers seven map types (the satellite map type is still there) but, at the present, they become six as soon as the map provider definition file for the satellite type is parsed since it currently contains Enabled = false.

The screenshots below demonstrate the difference:

Mapviewer before and after resolution

The MapViewer MapType menu before provider initialization (left) and after (right)

While this approach solves the encountered problem, it might be an undesirable behavior for some. Therefore, we added two options to disable this behavior. The first option is to set the plug-in parameter osm.mapping.providersrepository.disabled to true. This instructs the plug-in to not attempt any remote provider file fetching, but to just use the hard-coded values. Since this alone would bring the initial problem back, there is also another plug-in parameter that may come in handy. The osm.mapping.providersrepository.address can be used to override the default value of, for 5.6.2 and 5.7.1, and for 5.8.0 and later releases. Developers can point the plug-in to an alternative URL containing the provider definition files for street, satellite, cycle, transit, night-transit, terrain and hiking. Even local URLs starting with file:/// or qrc:/ are possible, which means that the provider definition files can be shipped with the application.

As a last note, please bear in mind that this solution is still not 100% fail safe. The mapping service is still offered by third parties with whom The Qt Company has no contractual relationship. If a robust solution is needed, using one of the commercial services that we support through one of the other shipped plug-ins should be considered.

Do you like this? Share it
Share on LinkedInGoogle+Share on FacebookTweet about this on Twitter

Posted in Dev Loop, Qt Location


Viktor says:

Is it planned to add the use of QtLocation to the QtWidgets?

Paolo Angelelli says:

You can already do that through QQuickWidget

Olle says:

Any clues on how to draw polylines, images etc. based on data from the c++ code if using quick widget?

Paolo Angelelli says:

At the moment, the only officially supported options are to either go through javascript (in a slot), and use that to do the actual job, or use one or more models with one or more MapItemViews.

Benoit says:

It would be great if Qt could host the OSM tiles for commercial users 🙂 Also looking forward to using the new MapBox plugin which looks more than promising (with the hope that we will be able to use the same licensing model as for Android/iOS apps).

Bruno de Oliveira Abinader Bruno de Oliveira Abinader says:

The Mapbox GL Native plugin for QtLocation uses the same licensing model as Mapbox Android SDK and Mapbox iOS SDK. Additionally we also provide a generic development token for development usage only (it must not be used in production) – you can find more information in – thank you!

Marco Piccolino Marco Piccolino says:

I’m a fond user of the ArcGIS for Qt library. Luckily, Esri maps now also come with a QtLocation plugin:

Commenting closed.

Get started today with Qt Download now