{"id":226,"date":"2021-10-31T18:39:25","date_gmt":"2021-10-31T18:39:25","guid":{"rendered":"https:\/\/www.cartograph.eu\/v3\/?page_id=226"},"modified":"2025-07-28T18:41:00","modified_gmt":"2025-07-28T18:41:00","slug":"map-packages","status":"publish","type":"page","link":"https:\/\/www.cartograph.eu\/v3\/add-ons\/map-packages\/","title":{"rendered":"Map packages"},"content":{"rendered":"<div>\n\t\t\t\t<div class=\"addthis_toolbox addthis_default_style text-right\">\n\t\t\t\t<a class=\"addthis_button_facebook_like\" fb:like:layout=\"button_count\"><\/a>\n\t\t\t\t<a class=\"addthis_button_tweet\"><\/a>\n\t\t\t\t<a class=\"addthis_button_pinterest_pinit\" pi:pinit:layout=\"horizontal\"><\/a>\n\t\t\t\t<a class=\"addthis_counter addthis_pill_style\"><\/a>\n\t\t\t\t<\/div>\n\t\t\t\t<script async type=\"text\/javascript\">\n\t\t\t\tvar addthis_config = addthis_config||{};\n\t\t\t\taddthis_config.data_track_clickback = false;\n\t\t\t\taddthis_config.data_track_addressbar = false;\n\t\t\t\tvar addthis_share = {url: \"https:\/\/www.cartograph.eu\/v3\/add-ons\/map-packages\/\"};\n\t\t\t\t<\/script>\n\t\t\t\t<script async type=\"text\/javascript\" src=\"\/\/s7.addthis.com\/js\/300\/addthis_widget.js#pubid=ra-528087a8560a6838\"><\/script>\n\t\t\t\t<\/div>\n\n\n\n<p>Map packages are zip files which allow easy installation of custom maps, styles, elevation data, and other data. A map package consists of a set of files and an instruction file named &#8220;<strong>mapdetails.json<\/strong>&#8220;. You can download a sample package <a href=\"https:\/\/www.cartograph.eu\/v3\/downloads\/mappackages\/samplepackage.zip\">here<\/a> or install it <a href=\"cartograph-s:\/\/www.cartograph.eu\/v3\/downloads\/mappackages\/samplepackage.cpkg\">here<\/a>.<\/p>\n\n\n\n<p>Map packages can be easily installed from your server by linking to them as follows: \u201ccartograph:\/\/www.myserver.com\/mymappackage.cpkg\u201d.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>Packages can include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"#metadata\">Metadata<\/a><\/li>\n\n\n\n<li><a href=\"#elevation\">Elevation data<\/a><\/li>\n\n\n\n<li><a href=\"#folders\">Folders<\/a><\/li>\n\n\n\n<li><a href=\"#maps\">Maps<\/a><\/li>\n\n\n\n<li><a href=\"#styles\">Styles<\/a><\/li>\n\n\n\n<li><a href=\"#overlays\">Overlays<\/a><\/li>\n\n\n\n<li><a href=\"#routingaudio\">Routing audio files<\/a><\/li>\n\n\n\n<li><a href=\"#commands\">Commands<\/a><\/li>\n\n\n\n<li><a href=\"#app\">Creating packages directly in the Cartograph app<\/a><\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h2 class=\"wp-block-heading\">Creating the &#8220;mapdetails.json&#8221; file<\/h2>\n\n\n\n<p>The &#8220;mapdetails.json&#8221; file is a JSON file which contains instructions for the Cartograph app describing what files to install. We recommend to use <a rel=\"noreferrer noopener\" href=\"https:\/\/code.visualstudio.com\/\" data-type=\"URL\" data-id=\"https:\/\/code.visualstudio.com\/\" target=\"_blank\">Visual Studio Code <\/a>(free, macOS, Windows) or <a rel=\"noreferrer noopener\" href=\"https:\/\/notepad-plus-plus.org\/downloads\/\" target=\"_blank\">Notepad++ <\/a>(free, Windows only) for creating and editing the file. Before packaging the file we recommend to check it for error, e.g. by copying the contents to this website: &#8220;<a rel=\"noreferrer noopener\" href=\"http:\/\/json.parser.online.fr\/\" target=\"_blank\">http:\/\/json.parser.online.fr\/<\/a>&#8220;.<\/p>\n\n\n\n<p>The following code shows a full sample file. We will describe all elements later.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"version\": 3,\n  \"extracted_size_mb\": 116,  \n  \"elevationdata\": [\n    \"*.hgt\"\n  ],\n  \"maps\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"name\": \"Sample A\",\n      \"file\": \"sampleA.map\",\n      \"load_in_layer\": -1,\n      \"uniqueId\": \"mapA\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ],\n  \"styles\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"file\": \"samplestyle.zip\",\n      \"load_in_layer\": 0,\n      \"uniqueId\": \"abc\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ],\n  \"overlays\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"file\": \"sampleA.poi\",\n      \"load\": true,\n      \"uniqueId\": \"abc1\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ],\n  \"routingaudio\": [\n    {\n      \"name\": \"Test audio package 1\",\n      \"folder\": \"testaudio\"\n    }\n  ],\n  \"commands\": [\n    {\n      \"command\": \"mapposition\",\n      \"lat\": 28.61,\n      \"lon\": -15.5,\n      \"zoom\": 10\n    },\n    {\n      \"command\": \"preimportmessage\",\n      \"title\": {\n        \"default\": \"Information\"\n      },\n      \"message\": {\n        \"default\": \"The Sample Map package will now be installed. This can take several minutes.\",\n        \"de\": \"Das Sample Kartenpaket wird jetzt installiert.\"\n      }\n    },\n    {\n      \"command\": \"postimportmessage\",\n      \"title\": {\n        \"default\": \"Success\",\n        \"de\": \"Erfolg\"\n      },\n      \"message\": {\n        \"default\": \"The Sample Map package has been installed.\",\n        \"de\": \"Das Sample Kartenpaket wurde installiert.\"\n      }\n    },\n    {\n      \"command\": \"openwebsiteafterinstallation\",\n      \"url\": \"http:\/\/www.cartograph.eu\"\n    }\n  ]\n}<\/pre>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"metadata\">Metadata<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">\"version\": 3,\n\"extracted_size_mb\": 116<\/pre>\n\n\n\n<p>The metadata describes general information about the package. The &#8220;<strong>version<\/strong>&#8221; should always be &#8220;3&#8221;. The &#8220;<strong>extracted_size_mb<\/strong>&#8221; should approximately match the total size of all files included in the map package.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"elevation\">Elevation data<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">\"elevationdata\": [\n  \"*.hgt\",\n  \"N12W13.hgt\"\n]<\/pre>\n\n\n\n<p>&#8220;<strong>elevationdata<\/strong>&#8221; contains a list of elevation data files. This can either be a concrete file (e.g. &#8220;N12W13.hgt&#8221;) or all files of a certain type in the map package (e.g. &#8220;*.hgt&#8221;).<\/p>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"folders\">Folders<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"type_hint\": \"folder\",\n  \"name\": \"Sample folder\",\n  \"uniqueId\": \"folder_abc\",\n  \"folder_key\":\"\"\n}<\/pre>\n\n\n\n<p><a href=\"#maps\">Maps<\/a>, <a href=\"#styles\">Styles<\/a>, and <a href=\"#overlays\">Overlays <\/a>can be grouped by folders. A folder is defined by the <em><strong>&#8220;type_hint&#8221;: &#8220;folder&#8221;<\/strong><\/em> entry. The &#8220;<strong>uniqueId<\/strong>&#8221; must be a unique id for the folder. Using the uniqueId multiple times can lead to unexpected behavior. A recommended pattern for the uniqueId is &#8220;com.myserver.some_unique_id&#8221;. The &#8220;<strong>folder_key<\/strong>&#8221; contains the uniqueId of the parent folder and can be used for creating hierarchies of folders. If the folder_key is left empty then the folder is created in the root folder.<\/p>\n<\/div><\/div>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"maps\">Maps<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">  \"maps\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"name\": \"Sample A\",\n      \"file\": \"sampleA.map\",\n      \"load_in_layer\": -1,\n      \"uniqueId\": \"mapA\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ]<\/pre>\n\n\n\n<p>The &#8220;<strong>maps<\/strong>&#8221; element contains a list of <a href=\"#folders\">folders <\/a>and maps. The &#8220;<strong>type_hint<\/strong>&#8221; field contains a hint describing the map type:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>&#8220;mapsforge&#8221;: a Mapsforge map.<\/li>\n\n\n\n<li>&#8220;mapsforge_raster&#8221;: a Mapsforge raster map.<\/li>\n\n\n\n<li>&#8220;mbtiles_raster&#8221;: a MBTiles sqlite raster map.<\/li>\n\n\n\n<li>&#8220;mbtiles_mvt_vector&#8221;: a MBTiles sqlite vector map.<\/li>\n\n\n\n<li>&#8220;locus_sqlite&#8221;: a Locus sqlite map.<\/li>\n\n\n\n<li>&#8220;rmap&#8221;: a TwoWays RMAP raster map.<\/li>\n\n\n\n<li>&#8220;map&#8221;: all other map types.<\/li>\n\n\n\n<li>&#8220;garmin_img&#8221;: a Garmin IMG map.<\/li>\n\n\n\n<li>&#8220;garmin_gmap&#8221; a (zip-compressed) Gamin GMAP.<\/li>\n<\/ul>\n\n\n\n<p>The &#8220;<strong>load_in_layer<\/strong>&#8221; field indicates if the map should be automatically loaded after installation of the map package. A value greater than &#8220;-1&#8221; will load the map.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"styles\">Styles<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">  \"styles\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"file\": \"samplestyle.zip\",\n      \"load_in_layer\": 0,\n      \"uniqueId\": \"abc\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ]<\/pre>\n\n\n\n<p>The &#8220;<strong>styles<\/strong>&#8221; element contains a list of <a href=\"#folders\">folders <\/a>and styles. The &#8220;<strong>type_hint<\/strong>&#8221; field contains a hint describing the style type:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>&#8220;mapsforge&#8221;: a Mapsforge style (render theme).<\/li>\n<\/ul>\n\n\n\n<p>The &#8220;<strong>load_in_layer<\/strong>&#8221; field indicates if the style should be automatically loaded as default style after installation of the map package. A value greater than &#8220;-1&#8221; will load the style as default style.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"overlays\">Overlays<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">  \"overlays\": [\n    {\n      \"type_hint\": \"folder\",\n      \"name\": \"Sample folder\",\n      \"uniqueId\": \"folder_abc\",\n      \"folder_key\":\"\"\n    },\n    {\n      \"type_hint\": \"mapsforge\",\n      \"file\": \"sampleA.poi\",\n      \"load\": true,\n      \"uniqueId\": \"abc1\",\n      \"folder_key\":\"folder_abc\"\n    }\n  ]<\/pre>\n\n\n\n<p>The &#8220;<strong>overlays<\/strong>&#8221; element contains a list of <a href=\"#folders\">folders <\/a>and overlays. The &#8220;<strong>type_hint<\/strong>&#8221; field contains a hint describing the overlay type:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>&#8220;mapsforge&#8221;: a Mapsforge POI overlay.<\/li>\n<\/ul>\n\n\n\n<p>The &#8220;<strong>load<\/strong>&#8221; field indicates if the overlay should be automatically loaded after installation of the map package. The value &#8220;true&#8221; means that the overlay will be automatically loaded.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"routingaudio\">Routing audio files<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">  \"routingaudio\": [\n    {\n      \"name\": \"Test audio package 1\",\n      \"folder\": \"testaudio\"\n    }\n  ]<\/pre>\n\n\n\n<p>The &#8220;<strong>routingaudio<\/strong>&#8221; element contains information about routing audio files. Please refer to the <a href=\"https:\/\/www.cartograph.eu\/v3\/add-ons\/audio-packages\/#custom\">Audio Packages page<\/a> for details.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"commands\">Commands<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">  \"commands\": [\n    {\n      \"command\": \"mapposition\",\n      \"lat\": 28.61,\n      \"lon\": -15.5,\n      \"zoom\": 10\n    },\n    {\n      \"command\": \"preimportmessage\",\n      \"title\": {\n        \"default\": \"Information\"\n      },\n      \"message\": {\n        \"default\": \"The Sample Map package will now be installed. This can take several minutes.\",\n        \"de\": \"Das Sample Kartenpaket wird jetzt installiert.\"\n      }\n    },\n    {\n      \"command\": \"postimportmessage\",\n      \"title\": {\n        \"default\": \"Success\",\n        \"de\": \"Erfolg\"\n      },\n      \"message\": {\n        \"default\": \"The Sample Map package has been installed.\",\n        \"de\": \"Das Sample Kartenpaket wurde installiert.\"\n      }\n    },\n    {\n      \"command\": \"openwebsiteafterinstallation\",\n      \"url\": \"http:\/\/www.cartograph.eu\"\n    }\n  ]<\/pre>\n\n\n\n<p>The &#8220;<strong>commands<\/strong>&#8221; element allows you to perform specific actions before and after the map package installation. The next sections describe each command in detail.<\/p>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">Map position<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"command\": \"mapposition\",\n  \"lat\": 28.61,\n  \"lon\": -15.5,\n  \"zoom\": 10\n}<\/pre>\n\n\n\n<p>The &#8220;<strong>mapposition<\/strong>&#8221; element sets the map to this position after installation.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">Message before installation<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"command\": \"preimportmessage\",\n  \"title\": {\n    \"default\": \"Information\"\n  },\n  \"message\": {\n    \"default\": \"The Sample Map package will now be installed. This can take several minutes.\",\n    \"de\": \"Das Sample Kartenpaket wird jetzt installiert.\"\n  }\n}<\/pre>\n\n\n\n<p>The &#8220;<strong>preimportmessage<\/strong>&#8221; shows a Ok\/Cancel message dialog before map package installation. If &#8220;Cancel&#8221; is selected then the map package is not installed.<\/p>\n<\/div><\/div>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">Message after installation<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"command\": \"postimportmessage\",\n  \"title\": {\n    \"default\": \"Success\",\n    \"de\": \"Erfolg\"\n  },\n  \"message\": {\n    \"default\": \"The Sample Map package has been installed.\",\n    \"de\": \"Das Sample Kartenpaket wurde installiert.\"\n  }\n}<\/pre>\n\n\n\n<p>The &#8220;<strong>postimportmessage<\/strong>&#8221; shows a message dialog after map package installation.<\/p>\n<\/div><\/div>\n\n\n\n<div class=\"wp-block-group\"><div class=\"wp-block-group__inner-container is-layout-flow wp-block-group-is-layout-flow\">\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">Open website url<\/h3>\n\n\n\n<pre class=\"wp-block-preformatted\">{\n  \"command\": \"openwebsiteafterinstallation\",\n  \"url\": \"http:\/\/www.cartograph.eu\"\n}<\/pre>\n\n\n\n<p>The &#8220;<strong>openwebsiteafterinstallation<\/strong>&#8221; opens a website after map package installation.<\/p>\n<\/div><\/div>\n\n\n\n<hr class=\"wp-block-separator has-css-opacity\"\/>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"app\">Create map packages directly in the Cartograph app<\/h2>\n\n\n\n<p>Map packages from existing maps, overlays, styles, elevation data, and routing audio files can be directly created in the Cartograph app in the <strong>main menu <\/strong>&#8211; &#8220;<strong>Tools<\/strong>&#8221; pane.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Map packages are zip files which allow easy installation of custom maps, styles, elevation data, and other data. A map<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":79,"menu_order":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-226","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/pages\/226","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/comments?post=226"}],"version-history":[{"count":54,"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/pages\/226\/revisions"}],"predecessor-version":[{"id":1418,"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/pages\/226\/revisions\/1418"}],"up":[{"embeddable":true,"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/pages\/79"}],"wp:attachment":[{"href":"https:\/\/www.cartograph.eu\/v3\/wp-json\/wp\/v2\/media?parent=226"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}