1// Copyright (C) 2014 Canonical Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\page location-plugin-mapbox.html
7\title Qt Location Mapbox Plugin
8\ingroup QtLocation-plugins
10\brief Uses Mapbox for location services.
14This geo services plugin allows applications to access
15\l {http://mapbox.com}{Mapbox} location based services using the Qt Location API.
16The use of these services is governed by the \l {https://www.mapbox.com/tos}{Mapbox terms of service}.
17An access token is required to use these services.
18Data is provided by \l {https://www.mapbox.com/about/maps}{OpenStreetMap and others}.
20The Mapbox geo services plugin can be loaded by using the plugin key "mapbox".
24\section2 Mandatory parameters
25The following table lists mandatory parameters that \e must be passed to the Mapbox plugin.
31 \li mapbox.access_token
32 \li \l{https://www.mapbox.com/help/define-access-token/}{Access token} provided by Mapbox.
35The Mapbox geo services plugin requires an access token and map ID to use the
36Mapbox services. To create a Mapbox account visit
37\l{https://www.mapbox.com/#signup}.
39\section2 Optional parameters
40The following table lists optional parameters that can be passed to the Mapbox plugin.
47 \li Boolean representing whether the access token comes from a
48 \l{https://www.mapbox.com/enterprise}{Mapbox Enterprise} account.
50 \li mapbox.mapping.map_id, mapbox.map_id (\b deprecated)
51 \li \l{https://www.mapbox.com/help/define-map-id/}{ID} of the Mapbox map to show. An example ID is "examples.map-zr0njcqy".
52 If this parameter is present, the specified map type will be used by default, unless another is selected.
53 If not present, the default Mapbox map ID is "mapbox.streets".
54 \b{Note:} neither in this parameter nor in \b{mapbox.mapping.additional_map_ids} it is allowed to use repeated map_ids.
55 This includes the map_ids bundled in the plugin by default (documented \l{https://www.mapbox.com/api-documentation/#maps}{here} under
56 \b{Mapbox classic map IDs}). Failing to do so will cause tile cache corruption.
58 \li mapbox.mapping.additional_map_ids
59 \li Additional, comma separated, Mapbox map IDs to be added to the available map types.
61 \li mapbox.mapping.format, mapbox.format (\b deprecated)
62 \li Data format to download tiles in, available values are "png", "png32",
63 "png64", "png128", "png256", (PNG with full, 32, 64, 128 and 256 color palette)
64 "jpg70", "jpg80", "jpg90" (JPEG with 70%, 80% and 90% compression).
67 \li mapbox.mapping.highdpi_tiles
68 \li Whether or not to request high dpi tiles. Valid values are \b true and \b false. The default value is \b false.
71 \li User agent string set when making network requests.
73 \li mapbox.mapping.cache.directory
74 \li Absolute path to map tile cache directory used as network disk cache.
76 The default place for the cache is the \c{QtLocation/mapbox} subdirectory in the location returned by
77 QStandardPaths::writableLocation(), called with QStandardPaths::GenericCacheLocation as a parameter.
78 On systems that have no concept of a shared cache, the application-specific \l{QStandardPaths::CacheLocation}
81 \li mapbox.mapping.cache.disk.cost_strategy
82 \li The cost strategy to use to cache map tiles on disk.
83 Valid values are \b bytesize and \b unitary.
84 Using \b bytesize, the related size parameter (\b mapbox.mapping.cache.disk.size) will
85 be interpreted as bytes.
86 Using \b unitary, they will be interpreted as number of tiles.
87 The default value for this parameter is \b unitary.
89 \li mapbox.mapping.cache.disk.size
90 \li Disk cache size for map tiles.
91 The default size of this cache is 6000 if \b unitary is used as cost strategy,
92 or 50 MiB, if \b bytesize is used as cost strategy.
93 Note that 6000 is the maximum amount of tiles that the Mapbox free plan allows to cache.
94 Make sure to comply with Mapbox Terms of Service before increasing this value.
96 \li mapbox.mapping.cache.memory.cost_strategy
97 \li The cost strategy to use to cache map tiles in memory.
98 Valid values are \b bytesize and \b unitary.
99 Using \b bytesize, the related size parameter (\b mapbox.mapping.cache.memory.size) will
100 be interpreted as bytes.
101 Using \b unitary, they will be interpreted as number of tiles.
102 The default value for this parameter is \b bytesize.
104 \li mapbox.mapping.cache.memory.size
105 \li Memory cache size for map tiles.
106 The Default size of this cache is 100 if \b unitary is used as cost strategy, or
107 3 MiB, if \b bytesize is used as cost strategy.
109 \li mapbox.mapping.cache.texture.cost_strategy
110 \li The cost strategy to use to cache decompressed map tiles in memory.
111 Valid values are \b bytesize and \b unitary.
112 Using \b bytesize, the related size parameter (\b mapbox.mapping.cache.texture.size) will
113 be interpreted as bytes.
114 Using \b unitary, they will be interpreted as number of tiles.
115 The default value for this parameter is \b bytesize.
117 \li mapbox.mapping.cache.texture.size
118 \li Texture cache size for map tiles.
119 The Default size of this cache is 30 if \b unitary is used as cost strategy, or
120 6 MiB, if \b bytesize is used as cost strategy.
121 Note that the texture cache has a hard minimum size which depends on the size of the map
122 viewport (it must contain enough data to display the tiles currently visible on the
124 This value is the amount of tiles to be cached in addition to the bare minimum.
126 \li mapbox.mapping.prefetching_style
127 \li This parameter allows to provide a hint how tile prefetching is to be performed by the engine. The default value,
128 \tt{TwoNeighbourLayers}, makes the engine prefetch tiles for the layer above and the one below the current tile
129 layer, providing ready tiles when zooming in or out from the current zoom level.
130 \tt{OneNeighbourLayer} only prefetches the one layer closest to the current zoom level.
131 Finally, \tt{NoPrefetching} allows to disable the prefetching, so only tiles that are visible will be fetched.
132 Note that, depending on the active map type, this hint might be ignored.
134 \li mapbox.routing.use_mapbox_text_instructions
135 \li Whether to use the instruction text that came with the response from the server (true) or the
136 text generated by the plugin. The default value is true.
137 Note that if instructions in a language that is not directly supported by Mapbox are needed (see
138 \l{https://www.mapbox.com/api-documentation/#instructions-languages}{here} for the supported languages),
139 it is possible to use the \l{Qt Linguist} to translate QtLocation to the desired language, and set this parameter to
140 false in order to use the translated built-in instructions.
143\section1 Extra routing attributes
145When using this plugin, the routeManeuver objects in the returned route may contain additional extended attributes (see \l routeManeuver::extendedAttributes),
147These attributes are described in detail in the official \l{https://www.mapbox.com/api-documentation/#stepmaneuver-object}{Mapbox direction API documentation}.