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 “mapdetails.json“. You can download a sample package here or install it here.
Map packages can be easily installed from your server by linking to them as follows: “cartograph://www.myserver.com/mymappackage.cpkg”.
Packages can include:
- Metadata
- Elevation data
- Folders
- Maps
- Styles
- Overlays
- Routing audio files
- Commands
- Creating packages directly in the Cartograph app
Creating the “mapdetails.json” file
The “mapdetails.json” file is a JSON file which contains instructions for the Cartograph app describing what files to install. We recommend to use Visual Studio Code (free, macOS, Windows) or Notepad++ (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: “http://json.parser.online.fr/“.
The following code shows a full sample file. We will describe all elements later.
{
"version": 3,
"extracted_size_mb": 116,
"elevationdata": [
"*.hgt"
],
"maps": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"name": "Sample A",
"file": "sampleA.map",
"load_in_layer": -1,
"uniqueId": "mapA",
"folder_key":"folder_abc"
}
],
"styles": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"file": "samplestyle.zip",
"load_in_layer": 0,
"uniqueId": "abc",
"folder_key":"folder_abc"
}
],
"overlays": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"file": "sampleA.poi",
"load": true,
"uniqueId": "abc1",
"folder_key":"folder_abc"
}
],
"routingaudio": [
{
"name": "Test audio package 1",
"folder": "testaudio"
}
],
"commands": [
{
"command": "mapposition",
"lat": 28.61,
"lon": -15.5,
"zoom": 10
},
{
"command": "preimportmessage",
"title": {
"default": "Information"
},
"message": {
"default": "The Sample Map package will now be installed. This can take several minutes.",
"de": "Das Sample Kartenpaket wird jetzt installiert."
}
},
{
"command": "postimportmessage",
"title": {
"default": "Success",
"de": "Erfolg"
},
"message": {
"default": "The Sample Map package has been installed.",
"de": "Das Sample Kartenpaket wurde installiert."
}
},
{
"command": "openwebsiteafterinstallation",
"url": "http://www.cartograph.eu"
}
]
}
Metadata
"version": 3, "extracted_size_mb": 116
The metadata describes general information about the package. The “version” should always be “3”. The “extracted_size_mb” should approximately match the total size of all files included in the map package.
Elevation data
"elevationdata": [ "*.hgt", "N12W13.hgt" ]
“elevationdata” contains a list of elevation data files. This can either be a concrete file (e.g. “N12W13.hgt”) or all files of a certain type in the map package (e.g. “*.hgt”).
Folders
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
}
Maps, Styles, and Overlays can be grouped by folders. A folder is defined by the “type_hint”: “folder” entry. The “uniqueId” 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 “com.myserver.some_unique_id”. The “folder_key” 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.
Maps
"maps": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"name": "Sample A",
"file": "sampleA.map",
"load_in_layer": -1,
"uniqueId": "mapA",
"folder_key":"folder_abc"
}
]
The “maps” element contains a list of folders and maps. The “type_hint” field contains a hint describing the map type:
- “mapsforge”: a Mapsforge map.
- “mapsforge_raster”: a Mapsforge raster map.
- “mbtiles_raster”: a MBTiles sqlite raster map.
- “mbtiles_mvt_vector”: a MBTiles sqlite vector map.
- “locus_sqlite”: a Locus sqlite map.
- “rmap”: a TwoWays RMAP raster map.
- “map”: all other map types.
- “garmin_img”: a Garmin IMG map.
- “garmin_gmap” a (zip-compressed) Gamin GMAP.
The “load_in_layer” field indicates if the map should be automatically loaded after installation of the map package. A value greater than “-1” will load the map.
Styles
"styles": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"file": "samplestyle.zip",
"load_in_layer": 0,
"uniqueId": "abc",
"folder_key":"folder_abc"
}
]
The “styles” element contains a list of folders and styles. The “type_hint” field contains a hint describing the style type:
- “mapsforge”: a Mapsforge style (render theme).
The “load_in_layer” field indicates if the style should be automatically loaded as default style after installation of the map package. A value greater than “-1” will load the style as default style.
Overlays
"overlays": [
{
"type_hint": "folder",
"name": "Sample folder",
"uniqueId": "folder_abc",
"folder_key":""
},
{
"type_hint": "mapsforge",
"file": "sampleA.poi",
"load": true,
"uniqueId": "abc1",
"folder_key":"folder_abc"
}
]
The “overlays” element contains a list of folders and overlays. The “type_hint” field contains a hint describing the overlay type:
- “mapsforge”: a Mapsforge POI overlay.
The “load” field indicates if the overlay should be automatically loaded after installation of the map package. The value “true” means that the overlay will be automatically loaded.
Routing audio files
"routingaudio": [
{
"name": "Test audio package 1",
"folder": "testaudio"
}
]
The “routingaudio” element contains information about routing audio files. Please refer to the Audio Packages page for details.
Commands
"commands": [
{
"command": "mapposition",
"lat": 28.61,
"lon": -15.5,
"zoom": 10
},
{
"command": "preimportmessage",
"title": {
"default": "Information"
},
"message": {
"default": "The Sample Map package will now be installed. This can take several minutes.",
"de": "Das Sample Kartenpaket wird jetzt installiert."
}
},
{
"command": "postimportmessage",
"title": {
"default": "Success",
"de": "Erfolg"
},
"message": {
"default": "The Sample Map package has been installed.",
"de": "Das Sample Kartenpaket wurde installiert."
}
},
{
"command": "openwebsiteafterinstallation",
"url": "http://www.cartograph.eu"
}
]
The “commands” element allows you to perform specific actions before and after the map package installation. The next sections describe each command in detail.
Map position
{
"command": "mapposition",
"lat": 28.61,
"lon": -15.5,
"zoom": 10
}
The “mapposition” element sets the map to this position after installation.
Message before installation
{
"command": "preimportmessage",
"title": {
"default": "Information"
},
"message": {
"default": "The Sample Map package will now be installed. This can take several minutes.",
"de": "Das Sample Kartenpaket wird jetzt installiert."
}
}
The “preimportmessage” shows a Ok/Cancel message dialog before map package installation. If “Cancel” is selected then the map package is not installed.
Message after installation
{
"command": "postimportmessage",
"title": {
"default": "Success",
"de": "Erfolg"
},
"message": {
"default": "The Sample Map package has been installed.",
"de": "Das Sample Kartenpaket wurde installiert."
}
}
The “postimportmessage” shows a message dialog after map package installation.
Open website url
{
"command": "openwebsiteafterinstallation",
"url": "http://www.cartograph.eu"
}
The “openwebsiteafterinstallation” opens a website after map package installation.
Create map packages directly in the Cartograph app
Map packages from existing maps, overlays, styles, elevation data, and routing audio files can be directly created in the Cartograph app in the main menu – “Tools” pane.