Qt Location 오픈 스트리트 맵 플러그인
개요
이 지오서비스 플러그인을 사용하면 애플리케이션이 Qt Location API를 통해 OpenStreetMap의 위치 기반 서비스에 접근할 수 있습니다.
데이터, 이미지 및 지도 정보는 ThunderForest, OpenStreetMap 및 기여자들이 제공합니다. 이 데이터는 오픈 데이터베이스 라이선스(Open Database License)에 따라 이용 가능합니다.
OpenStreetMap 지오서비스 플러그인은 플러그인 키 "osm"을 사용하여 불러올 수 있습니다.
참고: 표준 지도 유형은 (부분적으로) 무료 데이터 제공업체에 의존합니다. 평가 및 개발 목적으로 유용한 선택지를 제공하기 위해 노력하고 있으나, 실제 운영 환경에서 필요에 맞는 데이터 제공업체를 선정하는 것은 사용자의 책임입니다. 각 제공업체의 서비스 약관을 주의 깊게 읽고 준수할 것을 강력히 권장합니다. 대체 데이터 제공업체 목록은 OpenStreetMap 위키에서 확인할 수 있습니다. 이 플러그인이 제공하는 사용 가능한 지도 유형은 각 유형에 대해 실제로 이용 가능한 공개 제공자의 가용성에 따라 사전 공지 없이 변경되거나 제거될 수 있습니다. 이는 또한 HTTPS를 통해 타일을 제공하는 제공자가 사용될 수 있음을 의미합니다. 이는 Android와 같이 Qt에 SSL 지원이 기본적으로 내장되어 있지 않은 플랫폼에서 OSM 플러그인을 사용할 때 특히 중요합니다. 이러한 변경을 방지하려면 다른 지리 서비스 플러그인을 사용하거나, 플러그인 매개변수 `osm.mapping.providersrepository.address `를 사용자가 지정한 저장소로 설정하여 각 지도 유형에 사용될 제공자를 완전히 제어해야 합니다. Qt 5.9.6부터는 지오코딩 및 장소 정보에 사용되는 기본 nominatim 엔드포인트도 HTTPS 전용으로 변경되었습니다.
매개 변수
선택적 매개변수
다음 표에는 Open Street Map 플러그인에 전달할 수 있는 선택적 매개변수가 나열되어 있습니다.
참고: Qt 5.5부터 아래의 모든 매개 변수 앞에는 osm 를 접두사로 붙여야 합니다. 이전 버전에서는 접두사가 필요하지 않았습니다.
| 매개 변수 | 설명 |
|---|---|
| osm.geocoding.host | 지오코딩 서버에 네트워크 요청을 보낼 때 설정하는 URL 문자열입니다. 이 매개변수는 올바른 OSM API를 사용하는 유효한 서버 URL로 설정해야 합니다. 지정하지 않으면 기본 URL이 사용됩니다. 참고: API문서는 Project OSM Nominatim에서 확인할 수 있습니다. |
| osm.geocoding.debug_query | 디버깅을 위해 플러그인이 Nominatim에 대한 쿼리 URL을 지오코딩 응답에 포함하도록 지시합니다. |
| osm.geocoding.include_extended_data | 플러그인이 반환된 Location 객체에 Nominatim 고유 정보(지오메트리, 클래스 등)를 extendedAttributes로 포함하도록 지시합니다. |
| osm.mapping.cache.directory | 네트워크 디스크 캐시로 사용되는 지도 타일 캐시 디렉터리의 절대 경로입니다. 캐시의 기본 위치는 QStandardPaths::GenericCacheLocation 를 매개변수로 지정하여 QStandardPaths::writableLocation()를 호출했을 때 반환된 위치의 |
| osm.mapping.cache.disk.cost_strategy | 디스크에 지도 타일을 캐시하는 데 사용할 비용 전략입니다. 유효한 값은 bytesize와 unitary입니다. bytesize를 사용하는 경우, 관련 크기 매개변수(osm.mapping.cache.disk.size)는 바이트 단위로 해석됩니다. unitary를 사용하는 경우, 해당 매개변수는 타일 수로 해석됩니다. 이 매개변수의 기본값은 bytesize입니다. |
| osm.mapping.cache.disk.size | 지도 타일을 위한 디스크 캐시 크기입니다. 이 캐시의 비용 전략이 bytesize인 경우 캐시의 기본 크기는 50 MiB이며, 비용 전략이 unitary인 경우 1000 타일입니다. |
| osm.mapping.cache.memory.cost_strategy | 메모리에 지도 타일을 캐시할 때 사용할 비용 전략입니다. 유효한 값은 bytesize와 unitary입니다. bytesize를 사용할 경우, 관련 크기 매개변수(osm.mapping.cache.memory.size)는 바이트 단위로 해석됩니다. unitary를 사용할 경우, 타일 수로 해석됩니다. 이 매개변수의 기본값은 bytesize입니다. |
| osm.mapping.cache.memory.size | 지도 타일을 위한 메모리 캐시 크기입니다. 이 캐시의 비용 전략이 bytesize인 경우 캐시의 기본 크기는 3 MiB이며, 비용 전략이 unitary인 경우 100 타일입니다. |
| osm.mapping.cache.texture.cost_strategy | 압축이 해제된 지도 타일을 메모리에 캐시할 때 사용할 비용 전략입니다. 유효한 값은 bytesize와 unitary입니다. bytesize를 사용할 경우, 관련 크기 매개변수(osm.mapping.cache.texture.size)는 바이트 단위로 해석됩니다. unitary를 사용할 경우, 타일 수로 해석됩니다. 이 매개변수의 기본값은 bytesize입니다. |
| osm.mapping.cache.texture.size | 지도 타일을 위한 텍스처 캐시 크기입니다. 이 캐시의 비용 전략이 bytesize인 경우 캐시의 기본 크기는 6 MiB이며, 비용 전략이 unitary인 경우 30타일입니다. 텍스처 캐시에는 지도 뷰포트의 크기에 따라 결정되는 엄격한 최소 크기가 있다는 점에 유의하십시오(화면에 현재 표시된 타일을 렌더링하기에 충분한 데이터를 포함해야 함). 이 값은 해당 최소 크기 외에도 추가로 사용될 캐시 용량을 나타냅니다. |
| osm.mapping.custom.datacopyright | urlprefix 매개변수를 통해 Map::activeMapType 를 MapType.CustomMap 로 설정할 때 사용자 정의 데이터 저작권 문자열이 사용됩니다. 이 저작권은 위에서 언급한 CustomMap을 사용할 때만 적용됩니다. 이 값이 비어 있으면 사용자 정의 지도에 데이터 저작권이 표시되지 않습니다. |
| osm.mapping.custom.host | 사용자 정의 타일 서버의 URL 문자열입니다. 이 매개변수는 올바른 OSM API를 제공하는 유효한 서버 URL로 설정해야 합니다. URL에는 "%z/%x/%y.png" 접미사가 추가됩니다. 6.5 버전부터는 URL이 ".png"로 끝나는 경우 이 접미사가 추가되지 않습니다. 서버에서 API 키가 필요한 경우, 해당 키를 URL 문자열에 추가해야 합니다. 이 서버를 사용하려면 Map 의 Map::activeMapType 매개변수를 MapType.CustomMap 유형의 지원되는 지도 유형으로 설정해야 합니다. 이 지도 유형은 해당 플러그인 매개변수가 설정된 경우에만 사용할 수 있으며, 이 경우 항상 Map::supportedMapTypes[supportedMapTypes.length - 1]이 됩니다. 참고: mapping.custom.host 매개변수를 새 서버로설정하면 기존 커스텀 맵 스타일에 대한 맵 타일 캐시가 더 이상 사용될 수 없게 됩니다. |
| osm.mapping.custom.mapcopyright | Map::activeMapType 를 urlprefix 매개변수를 통해 MapType.CustomMap 로 설정할 때 사용자 정의 지도 저작권 문자열이 사용됩니다. 이 저작권은 위에서 언급한 CustomMap을 사용할 때만 적용됩니다. 값이 비어 있으면 사용자 정의 지도에 저작권이 표시되지 않습니다. |
| osm.mapping.highdpi_tiles | 고해상도(high dpi) 타일을 요청할지 여부를 지정합니다. 유효한 값은 true와 false입니다. 기본값은 false입니다. 모든 지도 유형이 고해상도(high dpi)로 제공되는 것은 아니라는 점에 유의하십시오. 현재 고해상도 지도 유형이 없는 경우, 이 매개변수를 true로 설정해도 아무런 효과가 없을 수 있습니다. 고해상도 타일에 대한 제공자 정보 파일의 이름은 street-hires, satellite-hires, cycle-hires, transit-hires, night-transit-hires, terrain-hires 및 hiking-hires 입니다. 이 파일들은 저해상도 타일에 사용되는 것과 동일한 위치에서 가져옵니다. |
| osm.mapping.offline.directory | 오프라인 저장소로 사용되는 지도 타일이 포함된 디렉터리의 절대 경로입니다. 이 속성을 지정하면 네트워크 디스크 캐시와 함께 작동하지만, 타일이 자동으로 삽입, 제거 또는 업데이트되지는 않습니다. 타일의 형식은 네트워크 디스크 캐시에서 사용하는 것과 동일합니다. 기본값은 없으며, 이 속성이 설정되지 않은 경우 어떤 디렉토리도 인덱싱되지 않고, 네트워크 사용량을 줄이거나 현재 캐시된 타일의 오프라인 저장소 역할을 하기 위해 네트워크 디스크 캐시만 사용됩니다. |
| osm.mapping.prefetching_style | 이 매개변수를 통해 엔진에서 타일 프리페칭을 수행하는 방식에 대한 지침을 제공할 수 있습니다. 기본값인 ` TwoNeighbourLayers`은 엔진이 현재 타일 레이어의 바로 위와 아래에 있는 레이어에 대한 타일을 미리 가져오도록 하여, 현재 확대/축소 수준에서 확대하거나 축소할 때 준비된 타일을 제공합니다. ` OneNeighbourLayer `은 현재 확대/축소 수준에 가장 가까운 레이어 하나만 미리 가져옵니다. 마지막으로, ` NoPrefetching `을 사용하면 사전 로딩을 비활성화할 수 있으므로, 화면에 표시되는 타일만 로딩됩니다. 활성화된 지도 유형에 따라 이 힌트가 무시될 수 있다는 점에 유의하십시오. |
| osm.mapping.providersrepository.address | OpenStreetMap 플러그인은 원격 저장소에서 제공자 정보를 가져옵니다. 이는 기본적으로 하드코딩된 서버를 사용하는 것을 방지하기 위한 것으로, 하드코딩된 서버는 향후 사용할 수 없게 될 가능성이 있습니다. 기본적으로 이 정보는 maps-redirect.qt.io에서 가져옵니다. 이 매개변수를 설정하면 제공자 저장소 주소가 사용자가 지정한 주소로 변경되며, 해당 저장소에는 street, satellite, cycle, transit, night-transit, terrain 및 hiking 파일이 포함되어 있어야 합니다. 각 파일에는 유효한 제공자 정보가 포함되어 있어야 합니다. |
| osm.mapping.providersrepository.disabled | 기본적으로 OpenStreetMap 플러그인은 하드코딩된 서비스의 이용 불가로 인한 서비스 중단을 방지하기 위해 원격 저장소에서 제공자 정보를 가져옵니다. 그러나 제공자 저장소에 접속할 수 없게 될 경우를 대비하여, 플러그인에는 여전히 대체용 하드코딩된 제공자 데이터가 포함되어 있습니다. 이 매개변수를 true로 설정하면 플러그인이 하드코딩된 URL만 사용하게 되므로, 플러그인이 원격 저장소에서 제공자 데이터를 가져오는 것을 방지합니다. |
| osm.places.debug_query | 이 매개변수를 true로 설정하면 각 결과에 "requestUrl"이라는 확장 속성이 추가되며, 여기에는 쿼리에 사용된 URL이 포함됩니다. 기본값은 false입니다. |
| osm.places.host | places 서버에 네트워크 요청을 보낼 때 설정되는 URL 문자열입니다. 이 매개변수는 올바른 OSM API를 사용하는 유효한 서버 URL로 설정되어야 합니다. 지정되지 않으면 기본 URL이 사용됩니다. 참고: API문서는 Project OSM Nominatim에서 확인할 수 있습니다. |
| osm.places.page_size | 한 페이지에 표시되는 결과의 수입니다. 이 값은 서버 측에서 제한될 수 있습니다. 표준 Nominatim 인스턴스의 일반적인 최대값은 50입니다. |
| osm.routing.apiversion | (사용자 정의) OSRM 서버의 API 버전을 정의하는 문자열입니다. 유효한 값은 v4 및 v5입니다. 기본값은 v5입니다. 이 매개변수는 osm.routing.host 이 설정되어 있고, 해당 서버가 OSRM v4 서버인 경우에만 설정해야 합니다. |
| osm.routing.host | 라우팅 서버에 네트워크 요청을 보낼 때 설정되는 URL 문자열입니다. 이 매개변수는 올바른 OSRM API를 사용하는 유효한 서버 URL로 설정되어야 합니다. 지정되지 않은 경우 기본 URL이 사용됩니다. 참고: API 문서와 소스코드는 Project OSRM에서 확인할 수 있습니다. |
| osm.useragent | 네트워크 요청을 수행할 때 설정되는 사용자 에이전트 문자열입니다. 이 매개변수는 애플리케이션을 고유하게 식별할 수 있는 값으로 설정해야 합니다. 제공업체는 이 매개변수를 설정하지 않고 기본 플러그인 사용자 에이전트(예: 지오코딩용 Nominatim )를 사용하는 애플리케이션을 차단할 수 있다는 점에 유의하십시오. |
매개변수 사용 예시
다음 예제는 useragent 매개변수를 지정하고, 필요한 경우 사용자 정의 서버 URL 및 타일 제공업체에 대한 해당 저작권 정보를 함께 제공하여 OSM 플러그인 인스턴스를 생성하는 방법을 보여줍니다. 또한, 공개 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" }
}기타 플러그인별 정보
타일 캐시
타일은 QStandardPaths::writableLocation (QStandardPaths::GenericCacheLocation)의 QtLocation/osm 디렉터리에 캐시됩니다. 공유 캐시 개념이 없는 시스템에서는 대신 애플리케이션 전용 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.
