OsmAnd GPX

Introduction

GPX (GPS Exchange Format) is a widely-used XML-based standard for storing GPS data, including tracks, routes, and waypoints. OsmAnd supports the GPX format for importing, exporting, and customizing GPS data for navigation, enabling both beginner and advanced users to optimize their experience.

What Makes OsmAnd GPX Unique?

OsmAnd extends the standard GPX 1.1 format by introducing its own custom osmand: XML namespace. This namespace enables storing additional data such as:

• Track visual settings (color, width, arrows).
• Waypoint grouping and icons.
• Detailed route attributes, including calculated routes and activity types.

What Will You Learn in This Guide?

This article provides a comprehensive overview of GPX file structure and features in OsmAnd. You will learn:

1. How to customize tracks and waypoints using GPX tags.
2. Advanced features such as HTML descriptions, sensor data, and activity types.
3. How to export calculated routes and preserve their full functionality.
4. Converting GPX files into OBF format for optimized storage and advanced search capabilities.

GPX Structure Overview

GPX files in OsmAnd organize data hierarchically into the following elements:

• <gpx> - the root element of the file.
• <trk> - represents tracks, which contain:
  • <trkseg> - segments of the track, which are further divided into <trkpt> (track points).
• <rte> - represents routes, including waypoints and key points.
• <wpt> - represents individual waypoints.

Track Customization

Track Appearance Parameters

This section describes how OsmAnd displays tracks on the map and the customization options available to adjust their appearance. The parameters described below are applied within the <gpx> tag and affect all tracks included in a GPX file.

Tag Name	Description / Values
<color>	- Defines the color of the track line on the map. - String: HEX color code #RRGGBB or #AARRGGBB
<width>	- Specifies the width of the track line. - String: “thin”, “medium", “bold” (defined by the “currentTrackWidth” attribute), or integer (1-24)
<show_arrows>	- Enables or disables direction arrows along the track. - Bool: "true" / "false"
<show_start_finish>	- Shows or hides markers for the start and end of the track. - Bool: "true" / "false"
<split_type>	- Specifies the type of segmentation for the track. - String: "no_split", "distance", "time"
<split_interval>	- Sets the interval for track segmentation based on the selected type. - Double: Integer (meters for "distance", seconds for "time")
<line_3d_visualization_by_type>	- Specifies the type of 3D visualization for the track. - String: "none", "altitude", "shared_string_speed", "map_widget_ant_heart_rate", "map_widget_ant_bicycle_cadence", "map_widget_ant_bicycle_power", "shared_string_temperature", "shared_string_speed", "fixed_height"
<line_3d_visualization_wall_color_type>	- Defines the wall color type for 3D visualization. - String: "none", "solid", "downward_gradient", "upward_gradient", "altitude", "slope", "speed"
<line_3d_visualization_position_type>	- Sets the position of the 3D visualization relative to the track. - String: "top", "bottom", "top_bottom"
<vertical_exaggeration_scale>	- Multiplier to scale the value of the line_3d_visualization_by_type attribute. - Float: Default: 1.0
<elevation_meters>	- Specifies a fixed elevation in meters for "fixed_height" in <line_3d_visualization_by_type>. - Float: Default: 1000
<coloring_type>	- Determines the coloring method for the track. - String: "solid", "speed", "altitude", "slope", "routeInfo_roadClass, "routeInfo_surface", "routeInfo_smoothness"
<color_palette>	- Specifies the color scheme for the track. - String: "default" / user-defined schemes

Example:

<gpx version="1.1" creator="OsmAnd~ 5.0.0" xmlns="https://www.topografix.com/GPX/1/1" xmlns:osmand="https://osmand.net/docs/technical/osmand-file-formats/osmand-gpx" xmlns:gpxtpx="https://www8.garmin.com/xmlschemas/TrackPointExtensionv1.xsd" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.topografix.com/GPX/1/1 https://www.topografix.com/GPX/1/1/gpx.xsd">
...
  <extensions>
    <osmand:color>#4e4eff</osmand:color>
    <osmand:width>bold</osmand:width>
    <osmand:show_arrows>true</osmand:show_arrows>
    <osmand:split_type>distance</osmand:split_type>
    <osmand:split_interval>2000.0</osmand:split_interval>
  </extensions>
</gpx>

Tag 'coloring_type'

The <coloring_type> tag in OsmAnd allows users to customize track coloring based on specific data attributes, providing a visual way to interpret key information along the track.

Type	Description	Use Case
<solid>	The entire track is displayed with a single, solid color specified by the color tag.	Use when a uniform color is needed for clear visibility.
<speed>	The track is colored in a gradient based on the speed values at each track point (<trkpt>). Higher speeds are represented by distinct colors.	Ideal for activities such as cycling or driving to visualize changes in speed.
<altitude>	The track is colored according to the elevation data at each <trkpt>. A gradient is applied, indicating different altitude ranges.	Useful for hiking or mountain routes to highlight altitude changes.
<slope>	The track is colored based on the incline/decline between consecutive track points. Positive gradients indicate uphill slopes, while negative gradients indicate downhill.	Suitable for cyclists or hikers analyzing track difficulty.
<routeInfo_roadClass>	Colors the track segments based on the OpenStreetMap (OSM) road classification (e.g., highway, residential street).	Helps distinguish between different road types when following a route.
<routeInfo_surface>	Colors the track segments based on the OSM surface type (e.g., paved, gravel, dirt).	Useful for determining track conditions during activities like off-roading.
<routeInfo_smoothness>	Colors the track according to OSM smoothness ratings, indicating the roughness or smoothness of the path (e.g., excellent, bad).	Helpful for evaluating track navigability for specific vehicles.

Waypoints Customization

This section explains how OsmAnd allows customization of waypoints in GPX files by using icons, colors, and grouping.

Waypoint Icons

The following tags control the appearance of waypoint icons in OsmAnd:

GPX tag	Default	Purpose
<icon>	(none)	Specifies the icon for the waypoint (e.g., historic_castle).
<color>	"red"	Sets the icon’s color using a HEX code (e.g., #FF0000) or color name (e.g., "blue").
<background>	"circle"	Defines the icon's background shape. Possible values: "circle", "square", "octagon".

Example:

<wpt lat="52.5163" lon="13.3779">
  <name>Brandenburg Gate</name>
  <icon>landmark_arch</icon>
  <color>#FFD700</color>
  <background>square</background>
</wpt>

Waypoint Groups

Waypoints in OsmAnd can be sorted into groups based on their type. This grouping allows the user to organize multiple waypoints under specific categories, improving clarity and map readability.

• Point group definition. The <type> tag inside the <wpt> element specifies the point's group (e.g., "castle", "aqueduct").
• Group configuration. The <osmand:points_groups> extension in the <gpx> element defines the settings for each group, including the name, color, icon, and background for all waypoints in that group.

Example:

<gpx>
  <wpt lat="1.234" lon="5.678">
    <type>aqueduct</type>
    <name>Look up to see the water</name>
  </wpt>
  <wpt lat="5.678" lon="1.234">
    <type>castle</type>
    <name>Beware of ghosts</name>
  </wpt>
  <wpt lat="66.666" lon="66.666">
    <type>castle</type>
    <name>The house of Beetlejuice</name>
  </wpt>
  <extensions>
    <osmand:points_groups>
      <group name="castle" color="#FF0000" icon="historic_castle" background="circle"/>
      <group name="aqueduct" color="#0000FF" icon="bridge_structure_arch" background="circle"/>
    </osmand:points_groups>
  </extensions>
</gpx>

Advanced GPX Features

Activity Type

Starting with OsmAnd version 4.9, you can classify your tracks by activity type for further analysis and organization in folders.

The list of supported activity types is available in the activities.json file. Each activity is identified by its unique ID and stored within the <metadata> extensions of the GPX file.

Example:

  <metadata>
    <extensions>
      <osmand:activity>off_road_motorcycling_dirt_biking</osmand:activity>
    </extensions>
  </metadata>

HTML in Descriptions

HTML tags can be used within the <desc> tags in the <metadata> or <wpt> elements to provide formatted descriptions for tracks or waypoints.

To avoid conflicts with XML syntax, replace special characters as follows:

• < → <
• > → >
• & → &

Example:

<metadata>
  <desc>
    &lt;p&gt;This is a &lt;b&gt;bold&lt;/b&gt; example.&lt;/p&gt;
    &lt;p&gt;
      &lt;h3&gt;Waypoint Information&lt;/h3&gt;
      &lt;a href="https://osmand.net"&gt;Visit OsmAnd&lt;/a&gt;&lt;br/&gt;
      &lt;img src="https://osmand.net/img/logo.png" /&gt;
    &lt;/p&gt;
  </desc>
</metadata>

Important notes:

• OsmAnd removes all HTML tags when generating brief descriptions, leaving plain text.
• You can use tags like <b>, <i>, <p>, <br/>, <a>, <img>, and more for customization.

Link Tag

Use <link> tag to associate URLs with metadata, author information, or waypoints in OsmAnd GPX files. This tag can also display an image when the URL points to an image file.

Examples (Metadata link with image):

<metadata>
  <link href="https://osmand.net/img/logo.png">
    <text>OsmAnd Logo</text>
  </link>
</metadata>

Examples (Waypoint link with image):

<wpt lat="52.5163" lon="13.3779">
  <link href="https://osmand.net/img/landmark.png" />
</wpt>

Sensor Data Tags

You can enrich your tracks with data from fitness sensors, such as heart rate monitors or temperature sensors. OsmAnd uses Garmin’s TrackPointExtension schema to store this data, making it compatible with platforms like Strava and Garmin Basecamp.

Supported Sensor Data Tags:

• hr - heart rate (in beats per minute).
• cad - bicycle cadence (in revolutions per minute).
• atemp - ambient temperature (in degrees Celsius).
• power - bicycle power output (in watts).

Example:

<extensions>
  <gpxtpx:TrackPointExtension>
    <gpxtpx:hr>145</gpxtpx:hr>
    <gpxtpx:cad>80</gpxtpx:cad>
    <gpxtpx:atemp>22</gpxtpx:atemp>
    <gpxtpx:power>250</gpxtpx:power>
  </gpxtpx:TrackPointExtension>
</extensions>

Track Point Details

Each <trkpt> (track point) in the GPX file can include additional attributes to capture data such as speed, heading, and elevation.

Supported attributes:

• speed - speed at the track point (in meters per second).
• heading - direction of movement (0-359 degrees).
• ele - elevation above sea level (in meters).
• time - timestamp for the track point.

Example:

  <trkpt lat="52.397799" lon="4.575998">
    <ele>203</ele>
    <time>2019-05-08T10:36:43Z</time>
    <hdop>3</hdop>
    <extensions>
      <heading>273</heading>
      <speed>5.02</speed>
    </extensions>
  </trkpt>

Calculated Routes

Calculated Route Structure

With OsmAnd, you can export detailed calculated routes, including all essential data such as route segments, turns, road names, road types, and restrictions. This functionality ensures the route can be fully restored as if it were freshly built, even without access to the respective offline maps.

GPX file structure for calculated routes

A GPX file may contain multiple calculated routes. Each route is divided into segments within the <trkseg> tags. These segments include detailed metadata under the <extensions> tag, enabling full reconstruction of the route. Additionally, the <rte> block stores key points of the route, which are used for visualization and analysis.

The GPX file is saved in this form when you export a built route or when you save a track consisting of several individual segments using the Plan a route feature.

GPX structure explanation

1. Track segment.

   • The <trk> element is the root for a track. It contains the overall track data.
   • The <trkseg> element represents a segment of the track, which consists of a series of track points. Each track point contains geographical coordinates and may have additional metadata, like elevation or time. The order of these track points indicates the sequence and the length of the route segments.

2. Extensions. Within the <trkseg>, the <extensions> element provides additional information not covered by the standard GPX schema. This includes:

   • Route segments. Defined within the <route> element, which lists individual segments summarized in the overall route.
   • Types of Segments. The <types> section specifies the characteristics of each segment in the route. This data is taken from offline maps during the initial route creation.

3. Route Points.

   • The <rte> element encapsulates the entire route, which may include multiple route points.
   • The <rtept> element represents individual route points. Like track points, these are linked to the route and can include parameters for key points. If a route point is not the first or last, it shares the same data as the corresponding track point that has the same index.

4. Route Point Extensions. Each route point has an <extensions> section that contains:

   • Profile. Indicates the type of activity associated with the next segment (such as car, bicycle, or pedestrian).
   • Track Point Index. This index refers to the corresponding track point in the GPX segment, which relates to the first calculated point of the route segment.

Segments Properties

This section explains key properties of segments in OsmAnd GPX files, focusing on how track points (<trkpt>) and route points (<rtept>) are structured and interconnected.

1. Track point indexing (<trkpt_idx>).

   • The first <trkpt> in a track segment (<trkseg>) always has an index trkpt_idx = 0.
     Example:
     For two <trkseg> segments, each will have a starting <rtept> with trkpt_idx = 0.

   • The last <trkpt> in a track segment has an index equal to the total number of <trkpt> elements in the segment minus 1.
     Example:
     If a <trkseg> contains 12 <trkpt> elements, the last <rtept> will have trkpt_idx = 11.

2. Segment overlap.

   • Overlapping segments. Neighboring route segments <segment> share the same <trkpt> at their boundary.
     Example:
     The end of one <segment> and the start of the next are represented by the same <trkpt>.

   • Non-Overlapping segments. If a route point <rtept> exists between two segments, the boundary <trkpt> values will not overlap. However, these points will share identical latitude, longitude, and other parameters.

3. Detecting overlaps. You can identify whether segments overlap using the length and startTrkptIdx attributes:

   • Non-Overlapping. The sum of startTrkptIdx and length of the previous <segment> equals the startTrkptIdx of the next <segment>.

   • Overlapping. The sum is less by 1, indicating overlap.

4. Straight route segments. Straight route segments are represented with id="-1" and occur in two scenarios:

   • When creating a multiprofile route, where the user selects a straight-line segment.

   • When a waypoint <rtept> is placed too far from the nearest road, causing OsmAnd to connect the point to the road with a straight line.

5. Calculating track points (<trkpt>) in a segment. The total number of <trkpt> in a <trkseg> can be calculated as:

   trkpts = length - (segments - 1) + (rtepts - 2)

   Where:

   • trkpts - total number of <trkpt> elements in the segment.
   • length - sum of all length values of the route <segment> elements inside the <trkseg>.
   • segments - number of route <segment> elements in the <trkseg>.
   • rtepts - number of <rtept> elements associated with the <trkseg>.

Summary table of key properties:

Property	Description
First <trkpt> index	Always trkpt_idx = 0.
Last <trkpt> index	Total number of <trkpt> elements in <trkseg> minus 1.
Overlapping segments	End of one <segment> shares the same <trkpt> as the start of the next.
Non-Overlapping segments	Boundary <trkpt> values differ but share identical lat/lon values.
Straight segments	Marked with id="-1" for multiprofile routes or distant waypoints.
Track point formula	Use the provided formula to calculate the total number of <trkpt> in a segment.

Example:

<gpx version="1.1" creator="OsmAndRouterV2" xmlns="http://www.topografix.com/GPX/1/1">
  <trk>
    <name>Sample Route</name>
    <trkseg>
      <trkpt lat="52.3639849" lon="4.8900533">
        <ele>0.801</ele>
      </trkpt>
      <trkpt lat="52.3636917" lon="4.8922849">
        <ele>0.998</ele>
      </trkpt>

      ....

      <extensions>
        <route>
          <segment id="7372058" length="3" segmentTime="178.44" speed="1.11" turnType="C" types="0,1,2,3,4,5,6" names="57" />
          <segment id="334164679" length="5" segmentTime="86.11" speed="1.11" turnType="TR" turnAngle="91.88" types="7,8,0,9,10,11,12,13,6" pointTypes=";;14,15;16,17,18;" names="58" />
        </route>
        <types>
          <type t="lit" v="yes" />
          <type t="oneway" v="yes" />
          <type t="highway" v="unclassified" />
          <type t="surface" v="paving_stones" />
        </types>
      </extensions>
    </trkseg>
  </trk>

  ....

  <rte>
    <rtept lat="52.3639945" lon="4.8900532">
      <extensions>
        <profile>pedestrian</profile>
        <trkpt_idx>0</trkpt_idx>
      </extensions>
    </rtept>
    <rtept lat="52.3542374" lon="4.8947024">
      <extensions>
        <profile>pedestrian</profile>
        <trkpt_idx>121</trkpt_idx>
      </extensions>
    </rtept>
  </rte>
</gpx>

GPX to OBF Conversion

OsmAnd allows you to convert multiple GPX files into a single OBF file. This enables the storage of thousands of GPX tracks in a compact, optimized format while maintaining features like special map icons, track appearance customization, and search functionality.

Steps to convert GPX to OBF:

• Log in to OsmAnd Web Map → Tracks → Select a folder → Menu (⋮) → Download as OBF collection*

• The resulting <.obf> file can be imported into OsmAnd (requires OsmAnd Android 5.0+).

OBF Track Customization

OsmAnd offers several ways to customize the visual appearance of tracks when converting GPX to OBF. This includes options for line colors, widths, shields, and waypoint icons.

Track Line Style

Customize track lines with the following tags:

GPX tag	Default	Purpose
<name>	(none)	Name displayed over the track line.
color	red	Primary color (HEX or text).
colour, displaycolor	(none)	Alternative ways to override color.
shield_waycolor	(none)	Override for shield track line color.
translucent_line_colors	no	Set to yes for semi-transparent colors.
width	thin	Line width: "thin", "medium", "bold", "1-24", or "roadstyle"

Supported colors: black, blue, brown, darkyellow, gray, green, lightblue, lightgreen, orange, purple, red, white, yellow.

Example:

<gpx>
  <metadata>
    <name>
      Track name located in Metadata
    </name>
  </metadata>
  <trk>
    ...
  </trk>
  <extensions>
    <osmand:color>yellow</osmand:color>
    <osmand:width>roadstyle</osmand:width>
    <osmand:translucent_line_colors>yes</osmand:translucent_line_colors>
  </extensions>
</gpx>

Line Shields

Shields are icons or symbols displayed along the track line. OsmAnd supports OSMC-symbol-style shields, which may include:

• Background icon - the main shape (e.g., circle or square).
• Foreground icons - up to two smaller symbols layered over the background.
• Text - short descriptions or identifiers, derived from the shield_text or ref tags.

If no shield properties are defined, OsmAnd uses an auto-sized yellow shield for the track.

Tags for shields:

GPX tag	Purpose
shield_bg	Defines the background icon for the shield.
shield_fg	Specifies the first foreground icon (e.g., an arrow or dot).
shield_fg_2	Specifies the second foreground icon (optional).
shield_text	Sets the text to be displayed over the shield (e.g., route name or ID).
shield_textcolor	Determines the color of the shield text (optional).
shield_waycolor	Overrides the standard track color for the shield’s line (optional).
ref	Used as fallback text if shield_text is not provided.

Example:

<gpx>
  <trk>
    <name>Sample Route</name>
  </trk>
  <extensions>
    <osmand:shield_text>Trail A</osmand:shield_text>
    <osmand:shield_fg>osmc_red_dot</osmand:shield_fg>
    <osmand:shield_bg>osmc_white_bg</osmand:shield_bg>
    <osmand:shield_waycolor>red</osmand:shield_waycolor>
    <osmand:shield_textcolor>black</osmand:shield_textcolor>
  </extensions>
</gpx>

Waypoint Display

Waypoint icons can be customized with the following tags:

GPX tag	Default	Purpose
icon	(none)	Specifies the icon for the waypoint (uses standard OsmAnd waypoint editor icons).
color	red	Sets the icon color using a HEX code (e.g., #ffaa00) or a supported color name (limited options).
background	circle	Defines the shape of the icon. Supported values: circle, square, octagon.

Behavior of background shapes:

• circle - displays the icon with a circular background.
• square - displays the icon with a square background, defaulting to red if no color is specified.
• octagon - treated as a circular background in OsmAnd.

Supported colors forbackground=circle: blue, gray, green, lightblue, lightgreen, orange, purple, yellow.

Enhancements with additional elements:

• You can add formatted descriptions to waypoints using HTML-code. This allows you to include styled text, links, or even images.
• Waypoints can display linked images using Link-as-Image.

Example:

<wpt lat="3.1415926" lon="42">
  <name>PI</name>
  <extensions>
    <osmand:icon>historic_archaeological_site</osmand:icon>
    <osmand:background>circle</osmand:background>
    <osmand:color>#ffaa00</osmand:color>
  </extensions>
</wpt>

OBF Search and Analytics

Converted OBF files provide reliable search capabilities, allowing you to find tracks and waypoints by metadata and extensions.

Name and Reference Search

Tracks and waypoints can be located using a variety of GPX tags.

GPX tag	Location	Purpose
<name>	<metadata>	The primary name of the GPX track.
ref	GPX <extensions>	A short identifier, often derived from the OSM ref tag.
shield_text	GPX <extensions>	Text displayed on shields (can also be used with ref).
name_-_lang	GPX/WPT <extensions>	Localized name using lang (e.g., name_-_en for English).
<name>	<wpt>	The name of the waypoint.

Example:

<gpx>
  <metadata>
    <name>Xemxija Heritage Trail</name>
  </metadata>
  <extensions>
    <osmand:ref>XHT</osmand:ref>
  </extensions>
  <wpt lat="35.948477" lon="14.3806796">
    <name>Il-Mighba Rumana</name>
    <extensions>
      <osmand:name_-_en>The Roman Apiary</osmand:name_-_en>
    </extensions>
  </wpt>
</gpx>

Activity Search

OsmAnd organizes tracks in OBF files into Activity Groups and Activity Types. These classifications help you filter tracks as POIs or create activity-based search filters.

How activity types work:

• Activity types and groups are determined using the "id" and "tags" from the activities.json file.
• OsmAnd uses osmand:activity or osmand:route tags to classify activities in GPX files.

GPX tag	Location	Purpose
osmand:activity	<metadata>	Main OsmAnd tag to store the activity type (by ID)
osmand:route	GPX <extensions>	Alternative method to define the activity type (by OSM conventions).

Examples of organizing tracks by activity type:

1. This will classify the track under the Motorcycling group with the type Off-Road Motorcycling (Dirt Biking).

   <metadata>
     <extensions>
       <osmand:activity>off_road_motorcycling_dirt_biking</osmand:activity>
     </extensions>
   </metadata>

2. This will organize the track under the Cycling group with the type Mountain Biking.

   <gpx>
     <extensions>
       <osmand:route>mtb</osmand:route>
     </extensions>
   </gpx>

OBF Analytics Tags

OBF files automatically generate and store critical track statistics and analytics.

OBF tag	Purpose
distance	Total distance covered by all track segments.
start_ele, ele_graph	Elevation data from GPX, wrapped in a compact binary array.
min_ele, avg_ele, max_ele	Minimum, average, and maximum elevation analytics.
diff_ele_up, diff_ele_down	Total elevation gain and loss across the track.
max_speed, avg_speed, min_speed	Track speed analytics, including maximum, average, and minimum speed.
time_span, time_span_no_gaps	Total time for the track, with and without accounting for gaps.
time_moving, time_moving_no_gaps	Total moving time, with and without accounting for gaps.

OBF Internal Tags

OBF files also use internal tags to manage metadata, provide additional search capabilities, and connect tracks to other map features. Some tags are directly derived from GPX extensions, while others store supplemental or preprocessed data.

OBF tag	Purpose
route_id	A unique identifier for the GPX file, linking track and POI data (e.g., OSM12345).
track_color	Generated track color derived from shield_waycolor, color, or displaycolor.
route_radius	Specifies the default radius for searching parts of the track within the POI section.
filename	Stores arbitrary extra tags from <gpx><extension> in JSON format.
extensions_extra_tags	Extra arbitrary tags for <gpx><extension> in JSON format
metadata_extra_tags	Stores arbitrary extra tags from <metadata><extension> in JSON format.
wpt_extra_tags	Stores arbitrary extra tags for each <wpt><extension> in JSON format.
name, ref, description	Localizable and searchable attributes marked with lang="true" for multilingual support.
route_name	The route name, used for internal searches (searchPoiByName).
route_type	Activity group identifier (id) to categorize the track.
route_activity_type	Specific activity type identifier (id) for the track.
route_track_point	Waypoint POI-type, linking track points to points of interest.

Implementation note:

Some tags are processed internally within the OsmAnd framework and may not directly appear in GPX files. For details about their implementation, refer to the OsmGpxWriteContext.java.

This article was last updated in January 2025