A simple tool that uses GPS waypoint data to generate GPX.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples/nikeplus
src
test
.babelrc
.editorconfig
.eslintignore
.eslintrc
.gitattributes
.gitignore
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md
package.json
webpack.config.js

README.md

GPS to GPX

A simple tool that uses GPS waypoint data to generate GPX.

This is a minimal JavaScript library that formats GPS waypoint data from an activity (a run, bike ride, hike, etc.) as GPX. Although the use cases are a bit limited, it can be helpful in specific situations.

Build Status Code Coverage npm Version License PRs Welcome

The Hook

Let's say you use a service like Nike+ for tracking your runs. Being a curious person, you're interested in trying out some other services to see what they're like, or maybe you've decided to start doing some cycling and now want to track all your different activities in one place, like Strava, and you want to take your data with you. A common way of doing this is to download your data as a GPX file and import it into other services. Nike+ (inexplicably) doesn't let you export data from your runs, but it does have an API that lets you grab JSON data for each activity. So, you're kind of stuck; you have some JSON data but you want GPX files. That's where this library comes in handy!

You might have JSON data that looks like this:

{
  "activityType": "RUN",
  "startTime": "2016-07-06T12:36:00Z",
  "waypoints": [
    {
      "latitude": 26.852324,
      "longitude": -80.08045,
      "elevation": 0,
      "time": "2016-07-06T12:36:00Z"
    }
  ]
}

Let's assume the JSON data above has been saved to a data variable and you're using ES2015 (if you're using another environment, you can find the appropriate steps in the installation instructions). Now you can import the default top-level createGpx function and call it like so :

import createGpx from 'gps-to-gpx';

const gpx = createGpx(data.waypoints, {
  activityName: data.activityType,
  startTime: data.startTime,
});

console.log(gpx);

For all your hard work, you'll be rewarded with GPX output in your console that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<gpx creator="Patrick Hooper" version="1.1" xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd http://www.garmin.com/xmlschemas/GpxExtensions/v3 http://www.garmin.com/xmlschemas/GpxExtensionsv3.xsd http://www.garmin.com/xmlschemas/TrackPointExtension/v1 http://www.garmin.com/xmlschemas/TrackPointExtensionv1.xsd">
  <metadata>
    <name>Activity</name>
    <time>2016-07-06T12:36:00Z</time>
  </metadata>
  <trk>
    <name>RUN</name>
    <trkseg>
      <trkpt lat="26.852324" lon="-80.08045">
        <ele>0</ele>
        <time>2016-07-06T12:36:00Z</time>
      </trkpt>
    </trkseg>
  </trk>
</gpx>

See how easy that was? Just send in your GPS waypoints, and you'll get back nicely formatted GPX created from your data! You can now do whatever you want with this, like save it to a file.

Keep in mind, this isn't the only use case, but it does a good job illustrating the purpose and intent of this tool. By itself, this might not seem entirely useful. If you're not into web development, things like APIs, data manipulation, and JavaScript libraries probably don't rev your engine. That's totally fair. There are a lot of great, user-friendly options out there for making transitions like the one described in the example; just check out this Strava support forum. However, if you happen to be a tech-savvy developer looking to create some GPX files or try your hand at building the next great API-to-GPX tool for people to use, then read on because this library might just fit your pipeline nicely.

Installation

If you're using npm as your package manager, you can install the most recent, stable version like so:

npm install --save gps-to-gpx

In an ES2015 environment, you can import the library like this:

import createGpx from 'gps-to-gpx';

In a CommonJS environment, you can import the library like this:

const createGpx = require('gps-to-gpx').default;

If you're not using modules via something like webpack, Browserify, or Node.js, then the UMD build might interest you. The gps-to-gpx library comes with a dist folder containing development and (minified) production UMD builds that can be used without a module bundler. In a UMD environment, GPS to GPX will be available as the window.GpsToGpx variable.

The source code is written in ES2015 but is compiled to ES5 ahead of time in both CommonJS (lib folder) and UMD (dist folder) builds.

API Documentation

This is a minimal library, so it only exports one function with a few options for GPX file customization:

createGpx(waypoints[, options])

Parameters

  1. waypoints (array): Required. An array of GPS waypoint data. Each point should be an object containing, at the very least, keys representing a coordinate's latitude and longitude values. These keys are assumed to be "latitude" and "longitude" by default, but can be customized (see options).

  2. options (object): Optional. An object literal of options that customize/override the default library settings. If any options are omitted, the settings will use the default values listed below:

  • activityName: "Everyday I'm hustlin'"
  • creator: 'Patrick Hooper'
  • eleKey: 'elevation'
  • extKey: 'extensions'
  • latKey: 'latitude'
  • lonKey: 'longitude'
  • startTime: null
  • timeKey: 'time'

Returns

(string): A GPX (a form of XML) string composed of the given waypoints and options.

Examples

If you're not sure where to start with the GPS to GPX library, maybe the example(s) below can help:

Roadmap

This project was created primarily as a hobby project to help familiarize myself with the process of creating a JavaScript library. For that reason, and because it has pretty targeted use cases, it probably won't get a ton of attention. Hopefully, someone somewhere finds it useful and does something super cool with it. If that person is you, I'd love to hear from you!

Contributing

Contributions from the community are welcome and encouraged! If you have any ideas, feature requests, bugs, etc., please use the contributing guidelines to determine your next move. Also note that this project follows a code of conduct. Thank you!

Releases

This project uses Semantic Versioning. All releases are documented on the GitHub releases page and in the change log.

License

GPS to GPX is released under the MIT License.