Qt Location Complemento OpenStreetMap
Descripción general
Este complemento de servicios geográficos permite a las aplicaciones acceder a los servicios basados en la ubicación de OpenStreetMap mediante la API « Qt Location ».
Los datos, las imágenes y la información cartográfica son proporcionados por ThunderForest, OpenStreetMap y sus colaboradores. Los datos están disponibles bajo la licencia Open Database License.
El complemento de servicios geográficos de OpenStreetMap se puede cargar utilizando la clave de complemento «osm».
Nota: Los tipos de mapas estándar dependen (parcialmente) de proveedores de datos gratuitos. Intentamos que la selección resulte útil con fines de evaluación y desarrollo, pero es tu responsabilidad seleccionar un proveedor de datos que se adapte a tus necesidades en entorno de producción. Se recomienda encarecidamente leer atentamente y cumplir las condiciones de servicio de los respectivos proveedores. En la wiki de OpenStreetMap hay disponible una lista de proveedores de datos alternativos. Los tipos de mapas disponibles que ofrece este complemento pueden cambiar (o eliminarse) sin previo aviso, dependiendo de la disponibilidad real de un proveedor viable y de acceso abierto para cada tipo. Esto también implica que pueden utilizarse proveedores que sirvan mosaicos a través de HTTPS. Esto cobra relevancia al utilizar el complemento OSM en plataformas, como Android, en las que el soporte SSL no está integrado en Qt de forma predeterminada. Para evitar estos cambios, se debe utilizar un complemento de servicios geográficos diferente o bien configurar el parámetro del complemento `osm.mapping.providersrepository.address ` con un repositorio especificado por el usuario, con el fin de tener control total sobre la selección del proveedor que se utiliza para cada tipo de mapa. Desde Qt 5.9.6, el punto final predeterminado de Nominatim, utilizado para la geocodificación y los lugares, también ha pasado a funcionar exclusivamente a través de HTTPS.
Parámetros
Parámetros opcionales
La siguiente tabla enumera los parámetros opcionales que se pueden pasar al complemento de OpenStreetMap.
Nota: A partir de Qt 5.5, todos los parámetros que se indican a continuación deben ir precedidos del prefijo « osm ». Las versiones anteriores no requerían ningún prefijo.
| Parámetro | Descripción |
|---|---|
| osm.geocoding.host | Cadena de URL que se establece al realizar solicitudes de red al servidor de geocodificación. Este parámetro debe establecerse en una URL de servidor válida con la API de OSM correcta. Si no se especifica, se utilizará la URL por defecto. Nota: La documentación de la API está disponible en Project OSM Nominatim. |
| osm.geocoding.debug_query | Indica al complemento que incluya la URL de la consulta a Nominatim en la respuesta de geocodificación, con fines de depuración. |
| osm.geocoding.include_extended_data | Indica al complemento que incluya información específica de Nominatim (como geometría y clase) en los objetos Location devueltos, expuesta como extendedAttributes. |
| osm.mapping.cache.directory | Ruta absoluta al directorio de caché de mosaicos de mapa utilizado como caché de disco en red. La ubicación predeterminada de la caché es el subdirectorio « |
| osm.mapping.cache.disk.cost_strategy | Estrategia de coste que se utilizará para almacenar en caché los mosaicos del mapa en disco. Los valores válidos son «bytesize» y «unitary». Si se utiliza «bytesize», el parámetro de tamaño relacionado (osm.mapping.cache.disk.size) se interpretará en bytes. Si se utiliza «unitary», se interpretará como número de mosaicos. El valor por defecto de este parámetro es «bytesize». |
| osm.mapping.cache.disk.size | Tamaño de la caché en disco para los mosaicos del mapa. El tamaño predeterminado de la caché es de 50 MiB cuando la estrategia de coste para esta caché es «bytesize», o de 1000 mosaicos, cuando la estrategia de coste es «unitary ». |
| osm.mapping.cache.memory.cost_strategy | Estrategia de coste que se utilizará para almacenar en caché los mosaicos del mapa en memoria. Los valores válidos son «bytesize» y «unitary». Si se utiliza «bytesize», el parámetro de tamaño relacionado (osm.mapping.cache.memory.size) se interpretará como bytes. Si se utiliza «unitary», se interpretará como número de mosaicos. El valor por defecto de este parámetro es «bytesize». |
| osm.mapping.cache.memory.size | Tamaño de la caché de memoria para los mosaicos del mapa. El tamaño predeterminado de la caché es de 3 MiB cuando «bytesize» es la estrategia de coste para esta caché, o de 100 mosaicos, cuando «unitary» es la estrategia de coste. |
| osm.mapping.cache.texture.cost_strategy | Estrategia de coste que se utilizará para almacenar en caché los mosaicos de mapa descomprimidos en memoria. Los valores válidos son «bytesize» y «unitary». Si se utiliza «bytesize», el parámetro de tamaño relacionado (osm.mapping.cache.texture.size) se interpretará como bytes. Si se utiliza «unitary», se interpretará como número de mosaicos. El valor por defecto de este parámetro es «bytesize». |
| osm.mapping.cache.texture.size | Tamaño de la caché de texturas para los mosaicos del mapa. El tamaño predeterminado de la caché es de 6 MiB cuando se utiliza «bytesize» como estrategia de coste para esta caché, o de 30 mosaicos cuando se utiliza «unitary ». Ten en cuenta que la caché de texturas tiene un tamaño mínimo fijo que depende del tamaño de la ventana de visualización del mapa (debe contener datos suficientes para mostrar los mosaicos visibles actualmente en la pantalla). Este valor es la cantidad de caché que se utilizará además del mínimo imprescindible. |
| osm.mapping.custom.datacopyright | La cadena de derechos de autor de los datos personalizados se utiliza al configurar el « Map::activeMapType » en « MapType.CustomMap » mediante el parámetro «urlprefix». Estos derechos de autor solo se utilizarán al emplear el «CustomMap» mencionado anteriormente. Si se deja vacío, no se mostrarán los derechos de autor de los datos para el mapa personalizado. |
| osm.mapping.custom.host | La cadena de URL de un servidor de mosaicos personalizado. Este parámetro debe establecerse en una URL de servidor válida que ofrezca la API de OSM correcta. Se añadirá el sufijo «%z/%x/%y.png» a la URL. A partir de la versión 6.5, el sufijo no se añadirá si la URL termina en «.png». Si el servidor requiere una clave API, esta debe añadirse a la cadena de la URL. Para utilizar este servidor, el parámetro ` Map::activeMapType ` de ` Map ` debe configurarse en el tipo de mapa compatible cuyo tipo sea ` MapType.CustomMap`. Este tipo de mapa solo estará disponible si se configura este parámetro del complemento, en cuyo caso siempre será ` Map::supportedMapTypes[supportedMapTypes.length - 1]`. Nota: Al configurar el parámetro «mapping.custom.host» con un nuevo servidor, la caché de mosaicos del mapa deja de ser válida para el antiguo estilo de mapa personalizado. |
| osm.mapping.custom.mapcopyright | La cadena de copyright del mapa personalizado se utiliza cuando se establece Map::activeMapType en MapType.CustomMap mediante el parámetro urlprefix. Este copyright solo se utilizará al emplear el CustomMap mencionado anteriormente. Si se deja vacío, no se mostrará ningún copyright del mapa para el mapa personalizado. |
| osm.mapping.highdpi_tiles | Indica si se deben solicitar mosaicos de alta resolución (high dpi). Los valores válidos son «true » y «false». El valor por defecto es «false». Ten en cuenta que no todos los tipos de mapa están disponibles en alta resolución. Establecer este parámetro en «true» podría incluso no tener ningún efecto si en ese momento no hay ningún tipo de mapa disponible en alta resolución. Los archivos de información del proveedor para los mosaicos de alta resolución se denominan street-hires, satellite-hires, cycle-hires, transit-hires, night-transit-hires, terrain-hires y hiking-hires. Estos se obtienen de la misma ubicación que se utiliza para sus homólogos de baja resolución. |
| osm.mapping.offline.directory | Ruta absoluta a un directorio que contiene mosaicos de mapa utilizados como almacenamiento sin conexión. Si se especifica, funcionará junto con la caché del disco de red, pero los mosaicos no se insertarán, eliminarán ni actualizarán automáticamente. El formato de los mosaicos es el mismo que el utilizado por la caché del disco de red. No hay ningún valor predeterminado y, si no se configura esta propiedad, no se indexará ningún directorio y solo se utilizará la caché del disco de red para reducir el uso de la red o para actuar como almacenamiento sin conexión de los mosaicos actualmente almacenados en caché. |
| osm.mapping.prefetching_style | Este parámetro permite indicar al motor cómo debe realizarse la precarga de mosaicos. El valor por defecto, TwoNeighbourLayers, hace que el motor precargue los mosaicos de la capa situada justo por encima y por debajo de la capa de mosaicos actual, proporcionando mosaicos listos al ampliar o reducir el nivel de zoom actual. OneNeighbourLayer solo precarga la capa más cercana al nivel de zoom actual. Por último, « NoPrefetching » permite desactivar la precarga, de modo que solo se cargarán los mosaicos que estén visibles. Ten en cuenta que, dependiendo del tipo de mapa activo, esta indicación podría ignorarse. |
| osm.mapping.providersrepository.address | El complemento de OpenStreetMap recupera la información del proveedor desde un repositorio remoto. Esto se hace para evitar el uso por defecto de servidores codificados de forma fija, que podrían dejar de estar disponibles. Por defecto, esta información se obtiene de maps-redirect.qt.io. Al configurar este parámetro, la dirección del repositorio del proveedor cambia a la especificada por el usuario, que debe contener los archivos street, satellite, cycle, transit, night-transit, terrain y hiking, cada uno de los cuales debe contener información válida sobre el proveedor. |
| osm.mapping.providersrepository.disabled | Por defecto, el complemento de OpenStreetMap recupera la información del proveedor desde un repositorio remoto para evitar una interrupción del servicio debida a la indisponibilidad de los servicios codificados de forma fija. Sin embargo, el complemento sigue conteniendo datos de reserva del proveedor codificados de forma fija, por si el repositorio del proveedor quedara inaccesible. Al establecer este parámetro en «true», el complemento utiliza únicamente las URL codificadas de forma fija y, por lo tanto, se impide que el complemento recupere datos del proveedor desde el repositorio remoto. |
| osm.places.debug_query | Establece este parámetro en «true» para que cada resultado incluya un atributo adicional denominado «requestUrl», que contenga la URL utilizada para la consulta. El valor por defecto es «false». |
| osm.places.host | Cadena de URL que se establece al realizar solicitudes de red al servidor de lugares. Este parámetro debe establecerse en una URL de servidor válida con la API de OSM correcta. Si no se especifica, se utilizará la URL por defecto. Nota: La documentación de la API está disponible en Project OSM Nominatim. |
| osm.places.page_size | El número de resultados por página. Ten en cuenta que este valor puede verse limitado por el servidor. El máximo habitual en instancias estándar de Nominatim es 50. |
| osm.routing.apiversion | Cadena que define la versión de la API del servidor OSRM (personalizado). Los valores válidos son v4 y v5. El valor por defecto es v5. Este parámetro solo debe configurarse si se ha establecido osm.routing.host y se trata de un servidor OSRM v4. |
| osm.routing.host | Cadena de URL que se utiliza al realizar solicitudes de red al servidor de enrutamiento. Este parámetro debe establecerse en una URL de servidor válida con la API OSRM correcta. Si no se especifica, se utilizará la URL por defecto. Nota: La documentación y los códigos fuente de la API están disponibles en Project OSRM. |
| osm.useragent | Cadena de agente de usuario que se establece al realizar solicitudes de red. Este parámetro debe configurarse con un valor que identifique de forma única a la aplicación. Ten en cuenta que los proveedores podrían bloquear las aplicaciones que no configuren este parámetro, dejando el agente de usuario predeterminado del complemento (por ejemplo, Nominatim para la geocodificación). |
Ejemplo de uso del parámetro
El siguiente ejemplo muestra cómo crear una instancia del complemento OSM con los parámetros proporcionados para el agente de usuario y, si es necesario, una URL de servidor personalizada, además de la información de derechos de autor correspondiente al proveedor de mosaicos. Además, es posible elegir un servidor de rutas distinto del servidor público de OSRM.
QML
Plugin {
name: "osm"
PluginParameter { name: "osm.useragent"; value: "My great Qt OSM application" }
PluginParameter { name: "osm.mapping.host"; value: "http://osm.tile.server.address/" }
PluginParameter { name: "osm.mapping.copyright"; value: "All mine" }
PluginParameter { name: "osm.routing.host"; value: "http://osrm.server.address/viaroute" }
PluginParameter { name: "osm.geocoding.host"; value: "http://geocoding.server.address" }
}Otra información específica del complemento
Caché de mosaicos
Los mosaicos se almacenan en caché en el directorio QtLocation/osm de QStandardPaths::writableLocation (QStandardPaths::GenericCacheLocation). En sistemas que no cuentan con un concepto de caché compartida, se utiliza en su lugar el directorio específico de la aplicación QStandardPaths::CacheLocation.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.