1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\page location-plugin-here.html
7\title Qt Location HERE Plugin
8\ingroup QtLocation-plugins
10\brief Uses the relevant services provided by HERE.
14Included with Qt Location is a geo services plugin which accesses the relevant HERE services
15provided by HERE/Nokia. The use of these services is governed by the terms and conditions
16available at \l {https://developer.here.com/terms-conditions}.
18Note that accepting the terms and conditions only applies those terms and conditions to the use of
19the HERE geo services plugin and does not limit the use of the other geo services plugins that may
22The HERE geo services plugin can be loaded by using the plugin key "here".
24The online plugin uses the tiled map classes, which caches tile data in heap memory and texture
29\section2 Mandatory parameters
30The following table lists mandatory parameters that \e must be passed to the HERE plugin.
37 \li Client \e app_id part of the app_id/token pair used for authentication by all managers.
40 \li Client \e token part of the app_id/token pair for the service used for authentication by all managers.
43The HERE geo services plugin requires an application id and token pair to authenticate the
44application with the HERE services. To obtain an application id and token pair visit
45\l{https://developer.here.com/}
47\section2 Optional parameters
48The following table lists optional parameters that can be passed to the HERE plugin.
50\note Since Qt 5.5 all parameters below must be prefixed with \c here. Previous versions did not require
59 \li Proxy server URL used by all managers. For usage of the system proxy just pass "system" as value.
61 \note See the notes in \l{QNetworkProxyFactory::systemProxyForQuery()} for further information.
64 \li Base map tile service URL used by mapping manager.
66 \li here.mapping.host.aerial
67 \li Aerial map tile service URL used by mapping manager. For all satellite, hybrid and terrain schemes.
69 \li here.mapping.cache.directory
70 \li Absolute path to map tile cache directory used as network disk cache.
72 The default place for the cache is the \c{QtLocation/here} subdirectory in the location returned by
73 QStandardPaths::writableLocation(), called with QStandardPaths::GenericCacheLocation as a parameter.
74 On systems that have no concept of a shared cache, the application-specific \l{QStandardPaths::CacheLocation} is used instead.
77 \li here.mapping.cache.disk.cost_strategy
78 \li The cost strategy to use to cache map tiles on disk.
79 Valid values are \b bytesize and \b unitary.
80 Using \b bytesize, the related size parameter (\b here.mapping.cache.disk.size) will
81 be interpreted as bytes.
82 Using \b unitary, they will be interpreted as number of tiles.
83 The default value for this parameter is \b bytesize.
85 \li here.mapping.cache.disk.size
86 \li Disk cache size for map tiles. The default size of the cache is 50 MiB when \b bytesize is the cost
87 strategy for this cache, or 1000 tiles, when \b unitary is the cost strategy.
89 \li here.mapping.cache.memory.cost_strategy
90 \li The cost strategy to use to cache map tiles in memory.
91 Valid values are \b bytesize and \b unitary.
92 Using \b bytesize, the related size parameter (\b here.mapping.cache.memory.size) will
93 be interpreted as bytes.
94 Using \b unitary, they will be interpreted as number of tiles.
95 The default value for this parameter is \b bytesize.
97 \li here.mapping.cache.memory.size
98 \li Memory cache size for map tiles. The default size of the cache is 3 MiB when \b bytesize is the cost
99 strategy for this cache, or 100 tiles, when \b unitary is the cost strategy.
101 \li here.mapping.cache.texture.cost_strategy
102 \li The cost strategy to use to cache decompressed map tiles in memory.
103 Valid values are \b bytesize and \b unitary.
104 Using \b bytesize, the related size parameter (\b here.mapping.cache.texture.size) will
105 be interpreted as bytes.
106 Using \b unitary, they will be interpreted as number of tiles.
107 The default value for this parameter is \b bytesize.
109 \li here.mapping.cache.texture.size
110 \li Texture cache size for map tiles. The default size of the cache is 6 MiB when \b bytesize is the cost
111 strategy for this cache, or 30 tiles, when \b unitary is the cost strategy.
112 Note that the texture cache has a hard minimum size which depends on the size of the map viewport
113 (it must contain enough data to display the tiles currently visible on the display).
114 This value is the amount of cache to be used in addition to the bare minimum.
116 \li here.mapping.prefetching_style
117 \li This parameter allows to provide a hint how tile prefetching is to be performed by the engine. The default value,
118 \tt{TwoNeighbourLayers}, makes the engine prefetch tiles for the layer above and the one below the current tile
119 layer, providing ready tiles when zooming in or out from the current zoom level.
120 \tt{OneNeighbourLayer} only prefetches the one layer closest to the current zoom level.
121 Finally, \tt{NoPrefetching} allows to disable the prefetching, so only tiles that are visible will be fetched.
122 Note that, depending on the active map type, this hint might be ignored.
124 \li here.mapping.highdpi_tiles
125 \li Whether or not to request high dpi tiles. Valid values are \b true and \b false. The default value is \b false.
127 \li here.geocoding.host
128 \li Geocoding service URL used by geocoding manager.
130 \li here.routing.host
131 \li Routing service URL used by routing manager.
134 \li Search service URL used by search manager.
136 \li here.places.api_version
137 \li Version of the REST API used by the places manager. Currently versions 1 and 2 are
138 supported. The version 1 is deprecated and will not be part of the final Qt release. The default is version 2.
141\section1 Parameter Usage Example
143The following two examples show how to create a HERE plugin instance with
144parameters supplied for an application id and token, which is required for
152 PluginParameter { name: "here.app_id"; value: "myapp" }
153 PluginParameter { name: "here.token"; value: "abcdefg12345" }
160QMap<QString,QVariant> params;
161params["here.app_id"] = "myapp";
162params["here.token"] = "abcdefg12345";
164QGeoServiceProvider *gsp = new QGeoServiceProvider("here", params);
168The HERE provider remotely accesses places (read-only) from a REST based server. The specific capabilities
169and behaviours are outlined below:
171\section2 Capabilities
183 \li Search term suggestions
189 \li Category structure
192 \li (Rich) Content images
195 \li (Rich) Content reviews
198 \li (Rich) Content editorials
201 \li All details fetched during search
204 \li Paging offset index
210 \li Distance relevance hint
213 \li Lexical name relevance hint
216 \li Extended Attributes
219 \li Notifications for added/removed places/categories
222 \li visibility scopes
225 \li favorites matching/(usable as favoritesPlugin)
229\section2 Plugin Specific Behaviors and Limitations.
231The following list shows what core place data is returned during a place search:
235\li contact information
242The following list shows further details that may be retrieved
243via QPlaceManager::getDetails()
246\li extended attributes
249\section3 Searching for Places
250\section4 Search Term and Categories
251The HERE plugin supports searching with a \e {search term} and \e {category or categories}, however
252both are not supported simultaneously.
255 \li Valid usage: \e {search term} + \e {search center}
256 \li Valid usage: \e {category} + \e {search center}
257 \li Invalid usage: \e {search term} + \e {category} + \e {search center}
260This limitation applies when using the HERE plugin with \l PlaceSearchModel and QPlaceManager::search().
263The HERE plugin only supports provision of a \e {search center} when searching for places via \l PlaceSearchModel
264and QPlaceManager::search(). A search center can be provided via a bounding circle, however the
265radius should be kept at the default value of -1. Typically a developer should not have to set the radius at all.
266If a developer sets a radius, it is ignored by the plugin and the boundaries are not honored.
268In a similar manner only the center of a bounding box is taken into consideration when searching. The boundaries
269of the box are not honored.
271A search center \e {must} be provided for all searches.
273\section4 Relevancy Hints
274The HERE plugin does not support relevancy hints. Any relevancy hints supplied to
275a search request are consequently ignored.
277\section3 Search Term suggestions
278Only a partial \e {search term} and \e {search center} is supported when retrieving suggestions.
279This limitation applies when using the HERE plugin with the \l PlaceSearchSuggestionModel and QPlaceManager::searchSuggestions().
281Both search term and search center \e {must} be provided when retrieving search term suggestions.
283\section3 Recommendations
284Only a given \e {place identifier} is supported as a parameter for a recommendations. No other parameters
285such as limit, offset, and search area are supported. This limitation applies when using the
286HERE plugin with \l PlaceSearchModel and QPlaceManager::search().
288\section3 Extended Attributes
289The supported set of attributes provided by the HERE plugin are not fixed and
290may grow over time. Also the attributes provided may vary according to a place
291by place basis, e.g one place may provide opening hours while another does not.
292At the time of writing, it is known that some places provide \c openingHours
293(QPlaceAttribute::OpeningHours) and \c payment (QPlaceAttribute::Payment)
294methods but other attributes may be made available by the backend server. All
295places provided by the plugin will have the \c x_provider
296(QPlaceAttribute::Provider) attribute set to \c here.
298\section3 Restrictions of Usage - ExtendedAttributes and Content
299The extended attributes and rich content of places are not permitted
300to be saved. For QML this is related to \l Place::extendedAttributes, \l ImageModel,
301\l ReviewModel, and \l EditorialModel. For C++ this relates to QPlace::extendedAttribute(),
302QPlace::content() and QPlaceManager::getPlaceContent().
304(Note that the HERE plugin is a read-only source of places and
305does not support saving functionality at all.)