A complete GPX document containing waypoints, routes, tracks, and metadata.

This is the main type representing a complete GPX file. GPX documents must have a creator string (identifying the creating application) and follow the GPX 1.1 specification format.

Comprehensive error type covering all possible GPX operation failures.

Errors can occur during:

• XML parsing (malformed XML, invalid structure)
• Coordinate validation (out of range values)
• Missing required GPX elements or attributes
• File I/O operations

GPX exception raised for unrecoverable errors.

Most functions return Result.t for error handling, but this exception may be raised in exceptional circumstances.

Parse GPX from XML input source.

Reads GPX data from an Xmlm.input source, which can be created from files, strings, or other input sources using the Xmlm library.

• parameter validate

  If true (default false), validates the parsed document against GPX specification rules. Validation checks coordinate ranges, required elements, and data consistency.

• parameter input

  XMLm input source created with Xmlm.make_input

• returns

  Ok gpx with parsed document, or Error e if parsing fails

Example:

  let input = Xmlm.make_input (`String (0, gpx_xml_string)) in
  match parse ~validate:true input with
  | Ok gpx -> Printf.printf "Parsed %d waypoints\n" (List.length (Doc.waypoints gpx))
  | Error e -> Printf.eprintf "Parse error: %s\n" (Error.to_string e)

Parse GPX from XML string.

Convenience function for parsing GPX data from a string. Equivalent to creating an Xmlm.input from the string and calling parse.

• parameter validate

  If true (default false), validates the parsed document

• parameter s

  Complete GPX XML document as a string

• returns

  Ok gpx with parsed document, or Error e if parsing fails

Example:

  let gpx_xml = {|<?xml version="1.0"?>
  <gpx version="1.1" creator="my-app">
    <wpt lat="37.7749" lon="-122.4194">
      <name>San Francisco</name>
    </wpt>
  </gpx>|} in
  match parse_string ~validate:true gpx_xml with
  | Ok gpx -> print_endline "Successfully parsed GPX"
  | Error e -> Printf.eprintf "Error: %s\n" (Error.to_string e)

Write GPX to XML output destination.

Generates standard GPX 1.1 XML and writes it to an Xmlm.dest destination. The output destination can target files, buffers, or other sinks.

• parameter validate

  If true (default false), validates the document before writing to ensure GPX specification compliance

• parameter dest

  XMLm output destination created with Xmlm.make_output

• parameter gpx

  GPX document to write

• returns

  Ok () on success, or Error e if writing fails

Example:

  let output = Buffer.create 1024 in
  let dest = Xmlm.make_output (`Buffer output) in
  match write ~validate:true dest gpx with
  | Ok () -> Buffer.contents output
  | Error e -> failwith (Error.to_string e)

Write GPX to XML string.

Convenience function that generates a complete GPX XML document as a string. The output includes XML declaration and proper namespace declarations.

• parameter validate

  If true (default false), validates before writing

• parameter gpx

  GPX document to serialize

• returns

  Ok xml_string with complete GPX XML, or Error e if generation fails

Example:

  match write_string ~validate:true gpx with
  | Ok xml -> 
      print_endline "Generated GPX:";
      print_endline xml
  | Error e -> 
      Printf.eprintf "Failed to generate GPX: %s\n" (Error.to_string e)

A validation issue found during GPX document checking.

Issues are classified as either errors (specification violations that make the GPX invalid) or warnings (best practice violations or suspicious data).

Complete validation result with all issues and validity status.

The is_valid field indicates whether the document contains any errors. Documents with only warnings are considered valid.

Perform comprehensive validation of a GPX document.

Checks all aspects of the GPX document against the specification:

• Coordinate ranges (latitude -90 to +90, longitude -180 to +180)
• Required elements and attributes
• Data consistency (e.g., time ordering in tracks)
• Reasonable value ranges for GPS quality metrics
• Proper structure and nesting

• parameter gpx

  The GPX document to validate

• returns

  Complete validation result with all issues found

Example:

  let result = validate_gpx gpx in
  if result.is_valid then
    Printf.printf "Document is valid with %d warnings\n" 
      (List.length (List.filter (fun i -> i.level = `Warning) result.issues))
  else begin
    print_endline "Document has errors:";
    List.iter (fun issue ->
      if issue.level = `Error then
        Printf.printf "  ERROR: %s\n" (format_issue issue)
    ) result.issues
  end

Quick validation check - returns true if document has no errors.

Equivalent to (validate_gpx gpx).is_valid but potentially more efficient as it can stop at the first error found.

• parameter gpx

  The GPX document to validate

• returns

  true if valid (no errors), false if errors found

Get only validation errors (specification violations).

Returns only the issues marked as errors, filtering out warnings. If this list is empty, the document is valid according to the GPX specification.

• parameter gpx

  The GPX document to validate

• returns

  List of error-level validation issues

Get only validation warnings (best practice violations).

Returns only the issues marked as warnings. These don't make the document invalid but may indicate potential problems or areas for improvement.

• parameter gpx

  The GPX document to validate

• returns

  List of warning-level validation issues

Format a validation issue for human-readable display.

Combines the issue message with location context if available.

• parameter issue

  The validation issue to format

• returns

  Formatted string suitable for display to users

Example output: "Error in waypoint 1: Latitude out of range (-95.0)"

Create a new GPX document with the required creator field.

Every GPX document must identify its creating application through the creator attribute. This is required by the GPX specification and helps identify the source of GPS data.

The created document:

• Uses GPX version 1.1 (the current standard)
• Contains no waypoints, routes, or tracks initially
• Has no metadata initially
• Can be extended using Doc module functions

• parameter creator

  Name of the creating application (e.g., "MyGPS App v1.0")

• returns

  Empty GPX document ready for data addition

Example:

  let gpx = make_gpx ~creator:"MyTracker v2.1" in
  let gpx = Doc.add_waypoint gpx some_waypoint in
  let gpx = Doc.add_track gpx some_track in
  (* gpx now contains waypoints and tracks *)

Create an empty GPX document with the required creator field.

Alias for make_gpx provided for consistency with module naming patterns. Creates a document with no GPS data that can be populated using the Doc module functions.

• parameter creator

  Name of the creating application

• returns

  Empty GPX document

Example:

  let gpx = empty ~creator:"GPS Logger" in
  assert (List.length (Doc.waypoints gpx) = 0);
  assert (List.length (Doc.tracks gpx) = 0);
  assert (Doc.creator gpx = "GPS Logger");