What Is the .avenzamaps file and how does it work?

What is the .avenzamaps file?

In addition to having access to more than 750,000 maps in the Avenza Maps Store, you can also import your own geospatial PDF and GeoTIFF files into the Avenza Maps app. If you have a large collection of maps and data, you may already know that loading all these files can be cumbersome and time-consuming. Luckily, there's a better solution to do this. The .avenzamaps (formerly known as .pdfmaps) file was devised as a solution for people or organizations who wish to load large collections of maps and data without having to import them one at a time.

The .avenzamaps file is a specially formatted JSON (JavaScript Object Notation) file, a lightweight data-interchange format, that links to where your maps and data are stored. They can be created using a text editor by replacing the .txt file extension with a .pdfmaps or .avenzamaps file extension (e.g. the filename would look something like yourfile.avenzamaps).  Please note that while the app has been re-branded to Avenza Maps, the .pdfmaps file extension will still be valid.

There are two ways map files can be referenced in a JSON file: as a URL or as a relative path to where both the .avenzamaps file and the download file are located. Importing a single JSON file will import all map files referenced within it. Here are what the two ways look like:

URL

  {

  "Version":"PDFMaps Maplist 1.1",

  "Map":{"URL":"https://www.yourserver.com/yourmap.pdf"}

  }

When using "URL" you require the full path to the file and it can either be publicly accessible or accessed on an FTP site with a password. If it is behind a password you will format the import line like so:

  {"URL":"ftp://USER:PASSWORD@SERVERIP/yourmap.pdf"}

The SERVERIP can also be the SERVERNAME.

Relative path

  {

  "Version":"PDFMaps Maplist 1.1",

  "Map":{"Path":"yourmap.pdf"}

  }

When using "Path" only the filename is needed. The .avenzamaps file will import referenced maps from the same location as it is stored in. The reference type, "URL" or "Path" are interchangeable depending on where your map files are stored.

The first line will always remain the same as it defines the version of the .avenzamaps file.

  "Version":"PDFMaps Maplist 1.1",

The second line defines the file type, which in this case is "Map".

You can reference many different maps in a file. A URL .avenzamaps file with multiple maps may look like this:

  {

  "Version":"PDFMaps Maplist 1.1",

  "Name":"Your Folder",

  

  "Folder": [

{"Map":{"URL":"https://www.yourserverlocation.com/yourmap.pdf"}},

{"Map":{"URL":"https://www.yourserverlocation.com/yourmap2.pdf"}},

{"Map":{"URL":"https://www.yourserverlocation.com/yourmap3.pdf"}},

{"Map":{"URL":"https://www.yourserverlocation.com/yourmap4.pdf"}}

]

  }

Additional parameters

In addition to being able to load maps, you can also load KML files to accompany them. Here is what the formatting of a relative .avenzamaps file with a map and KML would look like:

{

  "Version":"PDFMaps Maplist 1.1",

  

  "Map":{"Path":"yourmap.pdf","KML":{"Path":"yourdata.kml"}}

}

Note that the data type is defined as "KML" and is contained within the brackets of the "Map" data type. When the map is imported, the KML data will be visible on the map.  Please note that only one KML can be loaded on a map per .avenzamaps file.  In addition to this one KML limitation, the KML that gets attached will be attached on the last map imported.  If you are importing a collection, the KML will be applied to all the maps imported within that collection.

Finally, you can choose whether or not you want your maps to import into a folder or a collection on your Maps list. Here is what the formatting of a relative .avenzamaps file importing into a folder would look like:

{

  "Version":"PDFMaps Maplist 1.1",

  "Name":"Your Folder",

  

  "Folder": [

 

            {"Map":{"Path":"yourmap.pdf"}}

  ]

}

The first line defines the "Name" of the folder or collection, in this case, "Your Folder". The second line selects the type as a "Folder", which can be swapped with "Collection" if you choose. The final line is the previously mentioned data type line that tells the .avenzamaps file to import a "Map" called "yourmap.pdf" using the "Path" reference method.

This final example combines all the different types and formats:

Example 1

  {

  "Version":"PDFMaps Maplist 1.1",

  "Name":"Your Folder from Path",

  "Folder": [

            {"Map":{"Path":"yourmap.pdf"}},

            {"Map":{"Path":"yourmap2.pdf"}}

  ]

  }

Example 2

  {

  "Version":"PDFMaps Maplist 1.1",

  "Name":"Your Collection from URL",

  "Collection": [ 

        {"Map":{"URL":"https://www.yourserverlocation.com/yourmap3.pdf"}},

            {"Map":{"URL":"ftp://username:password@servername/yourmap4.pdf"}}

  ]

  }

Example 3

  {

  "Version":"PDFMaps Maplist 1.1",

  "Name":"Your Map from Path",

  "Map":{"Path":"yourmap5.pdf,"KML":{"Path":"yourdata.kml"}}

  }

You can download a set of template files for editing your own .avenzamaps files HERE. When editing text files in programs like TextEdit, the ASCII quotation marks are sometimes substituted with "Smart Quotes". These non-ASCII quotation marks will cause the import to fail. You can tell if this has occurred as Smart Quotes appear italicized or curled. When typing quotation marks in these programs, make sure this setting is disabled or hold down "control" while typing a quotation mark.

Note: An .avenzamaps file can not directly reference folders/directories where your maps are stored.  For example, you could not simply reference the Example_Maps folder and all maps within that folder will be imported.  Also, a .avenzamaps file will not allow the use of any wildcards or external batch files, etc.