What is a KMZ File?
A KMZ file consists of a main KML file and zero or more supporting files that are packaged using a Zip utility into one unit, called an archive. The KMZ file can then be stored and emailed as a single entity. A NetworkLink can fetch a KMZ file from a web server. When the KMZ file is unzipped, the main .kml file and its supporting files are separated into their original formats and directory structure, with their original filenames and extensions. In addition to being an archive format, the Zip format is also compressed, so an archive can include only a single large KML file. Depending on the content of the KML file, this process typically results in 10:1 compression. Your 10 Kbyte KML file can be served with a 1 Kbyte KMZ file.
Google Earth and Google Maps can read KML and KMZ files directly, and they can save files as KMZ files. By default, the main KML file is named doc.kml.
Note: For clarity, this page refers to the main KML file within a KMZ archive as doc.kml. This main KML file can have any name, as long as it ends in .kml, and as long as there is only one .kml file.
You should create a KMZ file if your doc.kml file is larger than 10 Kbytes, or if the doc.kml files references other files (images, sound files, models, textures).
Recommended Directory Structure
This section provides a few simple recommendations for the creators of KML/KMZ files. The example used in this section is from the Jimmy Buffett website, which uses the KML format to show planned concert tours and related highlights on Google Earth.
Download the KMZ file that contains this tour. (Used by permission.)
Note: Google Earth 6.0 strictly enforces the following set of guidelines when resolving relative references in a KMZ file (especially see item 4 in the following list). Earlier versions of Google Earth were less rigorous in how they resolved such relative references. As a result, some relative references that worked in Google Earth 5.2 and earlier releases may now need to be edited in order to work with versions 6.0 and later.
Follow these guidelines when creating KMZ files:
- Create a folder that will contain the contents of your KMZ file. Give it a descriptive name (for example, buffetthawaiitour).
- Put the default KML file (doc.kml, or whatever name you want to give it) at the top level within this folder. Include only one .kml file. (When Google Earth opens a KMZ file, it scans the file, looking for the first .kml file in this list. It ignores all subsequent .kml files, if any, in the archive. If the archive contains multiple .kml files, you cannot be sure which one will be found first, so you need to include only one.)
- Include one or more subfolders within the main folder to collect images, models, textures, sound files, or other resources referenced in the doc.kml file. The complexity of this directory structure depends on the number of supporting files and your preferences for organization.
- Use relative references. See References to External Files for more details. All relative paths begin inside the base folder described above in item 1. For example, if a KMZ file vacationJournal.kmz is on the desktop, and its doc.kml file refers to a file myFavoritePlace.jpg, which is also on the desktop, the <href> in the doc.kml file is
../myFavoritePlace.jpg. - Do not use the .kmz extension for any of the subfolders within a KMZ file. The .kmz extension is reserved for the name of the archive itself.
For example, here is the file structure of the KMZ file for the Jimmy Buffett tour:
Since there are only five supporting files, they are all collected into a files subfolder within the main folder. If you load the file into Google Earth and then copy and paste it into a text browser, you'll see that all of the <href> elements use relative references to these supporting files (which represent icons, a screen overlay, and the sound file for the tour).
Here is the KML code for one of the icon references:
<IconStyle> <scale>1.1</scale> <Icon> <href>files/icon_surfing.png</href> </Icon></IconStyle>
Here is the KML code for the reference to the sound file:
<gx:SoundCue> <href>files/Margaritaville.mp3</href></gx:SoundCue>
References to External Files
The doc.kml file usually contains a number of links to other files—images, icons, models, textures, and sound files. The references to these files are contained in the href attribute (or sometimes, the <href> element), which can be found in the following KML elements:
- the <a href> element of a <description> (and also <img src> in a <description>)
- <Icon> (as a child of <IconStyle>, <GroundOverlay>, <ScreenOverlay>, <PhotoOverlay>)
- <ItemIcon>
- <Link>
- <gx:SoundCue>
- <targetHref> and <sourceHref> in <Alias>
These external links can be either absolute or relative references, as described in the following section. They can refer to files within the same KMZ file, or to files contained in other KMZ files or stored elsewhere on the web. With the exception of the <sourceHref> element in <Model>, relative references are always resolved in relation to the doc.kml file, as explained in the section Resolving Relative References.
Absolute vs. Relative References
Absolute references contain the full URL for the linked file. They are useful for files posted on a central server and are unambiguous. However, if you use absolute references to local files, the links will break when the files are moved to a new system. Relative references avoid this problem.
Here is an example of an absolute reference to a file stored on a central server:
<Icon> <href>http://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png</href></Icon>
Resolving Relative References
In general, relative references are resolved in relation to the doc.kml file. Any relative URL is resolved against the directory that contains this file, which is considered the root of the KMZ file. In the Hawaiian tour example, the base URL is similar to the following (depending on where you download the KMZ file):
buffetthawaiitour.kmz
If you wanted to refer to a file located in a different KMZ file (for example, to images/jimmyphoto.jpg contained in margaritavillealbum.kmz, you would use the ".." notation to go up one level in the directory structure, which would take you out of the current KMZ file (buffetthawaiitour.kmz):
<href>../margaritavillealbum.kmz/images/jimmyphoto.jpg"</href>
Note: The rules for resolving relative references in a KMZ archive are based on the RFC 3986 Section 5 standard for resolving web URLs. The base URL is determined by the location of the doc.kml file, and all relative URLs are resolved in relation to that base URL.
The Exception: <sourceHref> in <Model>
The <Model> element contains a <Link> element that specifies a COLLADA file to load into Google Earth. COLLADA files specify 3D objects and have a .dae file extension. The <Model> element also contains an <Alias> element, that contains a mapping between the <targetHref> (the texture file to be fetched by Google Earth) and the <sourceHref> (the path specified for the texture file in the COLLADA .dae file). If the <sourceHref> element contains a relative path, Google Earth interprets this path as relative to the .dae file that references it (not relative to the doc.kml file as in all other cases). For example:
<Model>... <Link> <href>MackyBldg.kmz/files/CU Macky.dae</href> </Link> <ResourceMap> <Alias> <sourceHref>../files/StairsnoCulling.jpg</sourceHref> <targetHref>../files/StairsnoCulling.jpg</targetHref> </Alias> <Alias> <sourceHref>../files/sideturretnoCulling.jpg</sourceHref> <targetHref>../files/sideturretnoCulling.jpg</targetHref></Alias>...</Model>
Creating the KMZ Archive
Use Windows Explorer or the Mac Finder to create a Zip archive. Select the contents of the folder that contains the doc.kml file and related resources and choose an option such as "WinZip > Add to Zip file ...." The Java JAR library also has a Zip library for programmatically creating and extracting a Zip archive, and Linux has command line versions of zip and unzip.
Note: When you are creating the Zip archive, be sure to select the contents of the folder containing the doc.kml file, not the folder itself.
After you create the archive, change the .zip file extension to .kmz. To extract the files from the archive, change the .kmz file extension back to .zip and use the Zip utility to unzip the archive.
Google Earth and KMZ Archives
Use of the <iframe> Element
Within KML <description> balloons, most HTML elements are treated in Google Earth just as they're treated in standard web browsers. An <iframe> within a description balloon, however, is treated as straight HTML, which means that special KML features are not recognized. For example, an <iframe> cannot display KMZ resources, and local anchor links, such as <a href="#my feature;flyto">, are not recognized. The <src> element within an <iframe> element cannot point to a local file on disk, nor can it point to a file inside a KMZ file; it must point to a URL on the Internet that a browser can visit.
