Add README.md
This commit is contained in:
Tabledevil
125
README.md
Normal file
125
README.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# timeline2gpx
|
||||
|
||||
Convert your Google Timeline JSON data to GPX track files, organized by date.
|
||||
|
||||
## Introduction
|
||||
|
||||
timeline2gpx is a Python tool that transforms Google Timeline data (exported as JSON) into GPS Exchange Format (GPX) files. These GPX files can be imported into various mapping, fitness, and GPS applications for analysis or visualization of your location history.
|
||||
|
||||
Google Timeline records your location history with timestamps. This tool processes that data and converts it into standard GPX tracks, organizing the output by date so you can easily navigate through your movement history.
|
||||
|
||||
## Features
|
||||
|
||||
- Extracts location data from Google Timeline JSON export
|
||||
- Processes both `rawSignals` and `semanticSegments.timelinePath` data sources
|
||||
- Creates GPX tracks with proper time, latitude, longitude, and elevation data
|
||||
- Organizes GPX files by date (year/month/day)
|
||||
- Handles both continuous tracks and individual location points
|
||||
- Cleans and filters data to ensure quality outputs
|
||||
- Maintains proper GPX formatting for maximum compatibility
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.6 or higher
|
||||
- Google Timeline data export (`Timeline.json`) from your Android device
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone this repository:
|
||||
```bash
|
||||
git clone https://git.ktf.ninja/irt/timeline2gpx.git
|
||||
cd timeline2gpx
|
||||
```
|
||||
|
||||
2. No additional Python packages are required as the script uses only standard library modules.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Export your Google Timeline data directly from your Android phone:
|
||||
- Go to your Android phone's settings
|
||||
- Navigate to location services > timeline > export
|
||||
- Follow the prompts to export the Timeline data
|
||||
2. Place the exported `Timeline.json` file in the same directory as the script.
|
||||
3. Run the script:
|
||||
|
||||
```bash
|
||||
python create_gpx_tracks.py
|
||||
```
|
||||
|
||||
The script will automatically read the `Timeline.json` file from the current directory and create output files in year/month folders also in the current directory.
|
||||
|
||||
## Output Structure
|
||||
|
||||
The tool generates a directory structure organized by date in the current directory:
|
||||
|
||||
```
|
||||
./
|
||||
├── 2019/
|
||||
│ ├── 01/
|
||||
│ │ ├── track_2019-01-01.gpx
|
||||
│ │ ├── track_2019-01-02.gpx
|
||||
│ │ └── ...
|
||||
│ ├── 02/
|
||||
│ │ └── ...
|
||||
│ └── ...
|
||||
├── 2020/
|
||||
│ └── ...
|
||||
└── ...
|
||||
```
|
||||
|
||||
Each GPX file contains a track with points representing your location data for that specific day. The files follow the standard GPX 1.1 format and can be imported into applications like:
|
||||
|
||||
- Google Earth
|
||||
- Garmin Connect
|
||||
- Strava
|
||||
- OsmAnd
|
||||
- And many other GPS and mapping applications
|
||||
|
||||
## Privacy Note
|
||||
|
||||
This tool processes your location data locally on your machine. No data is sent to any external servers or services. Your privacy is maintained as the tool only reads from your exported Google data and writes to your local file system.
|
||||
|
||||
When working with location data, please be aware:
|
||||
- Location data contains sensitive personal information
|
||||
- Be cautious when sharing generated GPX files, as they reveal your movement patterns
|
||||
- Consider removing sensitive locations (like home, work) before sharing tracks with others
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions to improve timeline2gpx are welcome:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Submit a pull request
|
||||
|
||||
Please ensure your code follows the existing style and includes appropriate comments.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see below for details:
|
||||
|
||||
```
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2023 The timeline2gpx Authors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user