Serval Maps Utils - Map File Index

The purpose of the MapFileIndex application is to create an index file of a series of map data files. The index file contains metadata about each map file in the dataset as well as information about the index itself.

The index file will be used with the Serval Maps Download Service (currently being developed) which will act as a repository of OpenStreetMap data encoded in the mapsforge format.

Using the Application

This application is written in Java and uses a command-line interface. The application supports the following three command line options.

Option Description Allowed Values Required
-input the path to the top level directory of the map file repository a file system path yes
-output the path to the output file a file system path yes
-type the type of index to create json or xml yes

The application will recursively look for map data files, those ending with an extension of .map, starting at the directory specified by the -input parameter.

The index will be written to the file specified by the -output parameter. Importantly the application will not overwrite an existing index file.

The output type is one of either json (for data to be encoded in the JSON format), or alternatively xml (for data to be encoded in the XML format). Both file types contain the same information, the only difference is the way the data is represented.

Using the Index File

The index file contains the following data elements:

Element Name Description
version the version of the index file structure
generated the date / time that the index was generated
author the author of the index
data_source the source of the map data
data_format the format of the map data files
data_format_info a url for more information on the map data format
data_format_version the version of the map data format used
more_info a url for more information
map-info container element for a series of map elements
map an element containing information about each map file

Each map element contains the following attributes:

Attribute Name Description
file_date the date the file was created
file_name the name and path of the file relative to the website root
file_size the size of the file in bytes
min_latitude the minimum latitude of the bounding box of the map
min_longitude the minimum longitude of the bounding box of the map
max_latitude the maximum latitude of the bounding box of the map
max_longitude the maximum longitude of the bounding box of the map

Please note that these names are used in the XML version of the index, the JSON index uses similar names and a slightly more compact structure.

Important Notes

The paths to the map files are relative to the location of the index file. To achieve this, run the application in the parent directory of the map fie repository. For example, assume that repository is available in the following path:


Where each sub directory contains a number of map files, for example:


Generate the index by:

  1. Changing to the parent directory of the repository
    cd /home/servalproject/mapsforge
  2. Invoking the application from this directory
    /path/to/java -jar /path/to/MapFileIndex.jar -input /home/servalproject/mapsforge -output /home/servalproject/mapsforge/index.xml -type xml