Note: This page describes the development version of GPSBabel. It may substantially differ from the latest released GPSBabel.

Google Earth (Keyhole) Markup Language (kml)

This format can...

  • read and write waypoints

  • read and write tracks

  • read and write routes

This format has the following options: deficon, lines, points, line_width, line_color, floating, extrude, track, trackdata, trackdirection, units, labels, max_position_points, rotate_colors, prec .

KML, the Keyhole Markup Language format, was used by Keyhole and is used by Google Earth.

There are concepts in KML that GPSBabel can't support very well on read because they don't map well into other programs. For example, KML has ideas of camera views and names and descriptions can have arbitrarily complicated HTML in them. KML files may have tiered "Styles" which can identify sizing info and URLs of associated icons. Reading such files with GPSBabel - even if your goal is to write it back out as KML - can often have surprising results. Simple files with waypoints and paths (which GPSBabel represents internally as tracks) work fine.

Google Earth also uses GPSBabel internally for receiver communications and several file format imports and exports.

In general, GPSBabel's KML writer is relatively strong. GPSBabel handles simple KML on read fairly well, but if you're dealing with handcrafted KML that uses extensive features that have no analog in other formats like nested folders, ringgeometry, camera angles, and such, don't expect GPSBabel to do well with them on read.

Google Earth 4.0 and later have a feature that can surprise users of this format. Earth's "time slider" feature controls what timestamped data gets displayed. If you're using data that has timestamps (e.g. GPX points that contain time or almost any track data) this will be important to you. The time slider defaults to the far left position and fully closed. This means that only the first data point will be displayed. You can tweak Earth's settings to "view->show time->never" or you can widen the time slider to show the range of data of interest.

See Google Earth's documentation on timelines for more info.

deficon option

Default icon name.

This option specifies the default name for waypoint icons

lines option

Export linestrings for tracks and routes.

When this option is nonzero, GPSBabel draws lines between points in tracks and routes. The default value for this option is 1, which causes lines to be drawn by default. To disable line-drawing, specify lines=0.

points option

Export placemarks for tracks and routes.

When this option is nonzero, GPSBabel draws placemarks for tracks and routes. The default value for this option is 1, which causes placemarks to be drawn. To disable drawing of placemarks, specify points=0.

line_width option

Width of lines, in pixels.

This option specifies the width of the drawn lines in pixels. The default value is six pixels.

line_color option

Line color, specified in hex AABBGGRR.

This option specifies the line color as a hexadecimal number in AABBGGRR format, where A is alpha, B is blue, G is green, and R is red.

floating option

Altitudes are absolute and not clamped to ground.

When this option is nonzero, altitudes are allowed to float above or below the ground surface. By default, this option is zero so that altitudes are clamped to the ground. Specify floating=1 to allow them to float.

This option is more useful to pilots than to hikers.

extrude option

Draw extrusion line from trackpoint to ground.

This option is a boolean flag to specify whether Google Earth should draw lines from trackpoints to the ground. It defaults to '0', which means no extrusion lines are drawn. The option of '1' is, of course, most useful for points that aren't actually on the ground such as those be captured from planes.

track option

Write KML track (default = 0).

This is a boolean flag, defaulting to '0', that controls whether GPSBabel writes the <Track> tag that Google introduced in Earth 5.2 for tracks. You may need to turn this off if you have a KML reader that's confused by new tags or if size is critical.

Routes and tracks without sufficient time data are always drawn as Linestrings and never Tracks.

trackdata option

Include extended data for trackpoints (default = 1).

This is a boolean flag that controls whether GPSBabel writes extensive data for each trackpoint generated. By default computed speed, timestamps, and so on are written with the default of '1' for this option. If you are writing large tracks and do not value this information, you can reduce the size of the generated file substantially by turning this flag off by setting it to '0'.

trackdirection option

Indicate direction of travel in track icons (default = 0).

If set, this options creates directional icons for trackpoints. Arrows will show the direction of travel on drawn tracks and routes.

units option

Units used when writing comments ('s'tatute, 'm'etric,' 'n'autical, 'a'viation).

Units is a simple option. Specify 's' for "statute" (miles, feet, and other things that don't sensibly convert to each other, but are craved by Americans), 'm' for "metric", 'n' for "nautical" or 'a' for "aviation". Default is 's'.

labels option

Display labels on track and routepoints (default = 1).

When this option is zero, no labels are added for track and route points. This option defaults to one, so labels are added by default.

max_position_points option

Retain at most this number of position points (0 = unlimited).

This option allows you to specify the number of points kept in the 'snail trail' generated in the realtime tracking mode.

rotate_colors option

Rotate colors for tracks and routes (default automatic).

With this option GPSBabel uses different colors for each track or route. If this option is used without a value then the colors are automatically selected such that the spectrum will be rotated through once for all the tracks and once for all the routes. If this option is used with a positive value then the value is interpreted as the number of degrees in the color circle between adjacent tracks or routes. This option takes precedence over line_color.

prec option

Precision of coordinates, number of decimals.

This option specifies the number of digits to be used when writing geographic coordinates, .i.e., latitude and longitude. Precision is the number of digits after the decimal point. The default precision is 6. We limit the number of places we write to improve the fidelity when round-tripping geographic coordinates, reduce file size, and reduce silliness in files caused by repeating decimals in insignificant digits.

As a guideline, at the equator, five decimal places is about 1.1 m, placing it below the accuracy of commodity consumer GPS gear. Six places is 0.11 m, achievable via surveyor grade and differential corrected GPS. Seven is 11 millimeters.

This value is ignored on read and has no impact on the internal representation of data.