{"id":26633728,"url":"https://github.com/blacklight/gpstracker","last_synced_at":"2026-01-05T07:50:41.136Z","repository":{"id":279881259,"uuid":"940286359","full_name":"blacklight/gpstracker","owner":"blacklight","description":"Read-only mirror of https://git.platypush.tech/blacklight/gpstracker","archived":false,"fork":false,"pushed_at":"2025-03-10T01:33:43.000Z","size":352,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-19T05:14:21.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blacklight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-27T23:15:33.000Z","updated_at":"2025-03-10T01:33:46.000Z","dependencies_parsed_at":"2025-03-01T07:01:51.891Z","dependency_job_id":null,"html_url":"https://github.com/blacklight/gpstracker","commit_stats":null,"previous_names":["blacklight/gpstracker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fgpstracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fgpstracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fgpstracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fgpstracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blacklight","download_url":"https://codeload.github.com/blacklight/gpstracker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245294718,"owners_count":20591909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-24T15:16:13.879Z","updated_at":"2026-01-05T07:50:41.131Z","avatar_url":"https://github.com/blacklight.png","language":"Vue","funding_links":[],"categories":["Vue"],"sub_categories":[],"readme":"# GPSTracker\n\n[![Build Status](https://ci-cd.platypush.tech/api/badges/blacklight/gpstracker/status.svg)](https://ci-cd.platypush.tech/blacklight/gpstracker)\n\n##### Track your GPS data, from any data source\n\n\u003c!-- toc --\u003e\n\n- [Features](#features)\n  * [History navigation](#history-navigation)\n  * [Select location points by area](#select-location-points-by-area)\n  * [Advanced statistics](#advanced-statistics)\n- [Configuration](#configuration)\n- [Docker installation](#docker-installation)\n- [Local installation](#local-installation)\n  * [Build](#build)\n  * [Run](#run)\n- [Usage](#usage)\n  * [Initial setup](#initial-setup)\n  * [Ingestion](#ingestion)\n    + [Enriching location data](#enriching-location-data)\n  * [External data sources](#external-data-sources)\n- [Development](#development)\n  * [Compile and Hot-Reload for Development](#compile-and-hot-reload-for-development)\n    + [Backend](#backend)\n    + [Frontend](#frontend)\n\n\u003c!-- tocstop --\u003e\n\nGPSTracker is a simple Webapp that consists of:\n\n- A backend that:\n  - Can manage GPS data stored on a local db or on any compatible data source\n    (supported: `postgres`, `mysql`, `mariadb`, `mongodb`, `sqlite`,\n    `snowflake`), with arbitrary complex filtering, and expose them over a\n    simple Web API.\n  - Can ingest GPS location updates from HTTP.\n- A frontend to display GPS data points and provides advanced filtering.\n\nIt is meant as a self-hosted and privacy-aware alternative to services like Google Maps Timeline.\n\n![Screenshot of GPSTracker](https://static.platypush.tech/screenshots/gpstracker_screenshot.jpg)\n\n## Features\n\n### History navigation\n\nAt its core GPSTracker allows you to easily navigate through your stored\nlocation data, offering pagination, advanced filtering and sorting.\n\nThe timeline allows an easy time-based navigation, and it also reports\ninformation such as the total distance traveled, the altitude, the speed and the\nbattery level at the time of the location point.\n\n![GPSTracker history\nnavigation](https://static.platypush.tech/screenshots/gpstracker-history-navigation.gif)\n\n![GPSTracker map\nfilter](https://static.platypush.tech/screenshots/gpstracker-map-filter.jpg)\n\n### Select location points by area\n\nYou can select a specific area on the map and filter the location points by it,\nproviding easy answers to questions such as \"where have I been in this specific\nlocation in the last year?\".\n\n![GPSTracker history\nnavigation](https://static.platypush.tech/screenshots/gpstracker-select-location-by-area.gif)\n\n### Advanced statistics\n\nMore advanced statistics are available in the _Stats_ page, which allows you to\naggregate your location data by any combinations of the available metrics and\nexplore specific location points in a certain group.\n\n![GPSTracker stats\npanel](https://static.platypush.tech/screenshots/gpstracker-stats.gif)\n\n## Configuration\n\n```\ncp .env.example .env\n```\n\nSee [the provided `.env.example`](./.env.example) for a reference.\n\n## Docker installation\n\n```sh\ndocker compose up\n```\n\n## Local installation\n\n\n### Build\n\nRequirements:\n\n- `node`\n- `typescript`\n- `make`\n\n```sh\nmake\n```\n\nOr, if you want to build the backend and the frontend separately:\n\n```sh\n# Backend\nmake backend\n\n# Frontend\nmake frontend\n```\n\n### Run\n\n```sh\nnpm run start\n```\n\n## Usage\n\n### Initial setup\n\nOnce the application is running, you can access the frontend at\n`http://localhost:3000` - or on whatever port you configured in the `.env`\nfile.\n\nUse the `ADMIN_EMAIL` and `ADMIN_PASSWORD` values from the `.env` file to log\nin.\n\nYou can then create a new device for your GPS data under the `Devices` menu, or\nat `http://localhost:3000/devices`. Take note of the `deviceId`, you will need\nit to ingest data.\n\nThen create a new API token from the `API` menu, or at\n`http://localhost:3000/api`.\n\n### Ingestion\n\nThe application exposes a POST endpoint at `/gpsdata` that accepts a JSON\npayload containing the GPS data to ingest. Example:\n\n```bash\ncurl -XPOST \\\n  -H \"Authorization: Bearer your-api-token\" \\\n  -H \"Content-Type: application/json\"\n  -d '[{\n      \"deviceId\": \"your-device-id\",\n      \"latitude\": 40.7128,\n      \"longitude\": -74.0060,\n      \"address\": \"260 Broadway\",\n      \"locality\": \"New York, NY\",\n      \"country\": \"us\",\n      \"postalCode\": \"10007\",\n      \"description\": \"New York City Hall\",\n      \"timestamp\": \"2021-01-01T00:00:00Z\"\n    }]' http://localhost:3000/api/v1/gpsdata\n```\n\nYou can wrap this in a script to ingest data from a file, or from a GPS tracker.\n\nYou can also configure a mobile app like [GPSLogger](https://gpslogger.app/) to\nperiodically send data to the endpoint - select _Custom URL_ and use the\n`/gpsdata` endpoint with the API token as the `Authorization` header under the\n_HTTP Headers_ section.\n\nOr, for more advanced use cases, you can use a general-purpose application like\n[Tasker](https://tasker.joaoapps.com/) in combination with\n[AutoLocation](https://play.google.com/store/apps/details?id=com.joaomgcd.autolocation)\nto send data to the endpoint, or decouple the ingestion from the frontend by\nusing an intermediate MQTT or Kafka broker.\n\n#### Enriching location data\n\nIf the ingested location data does not contain the `address`, `locality`,\n`country` or `postalCode` fields, and you have set the `GEOCODE_PROVIDER`\nenvironment variable, then the application will try to geocode the location\nupon ingestion using the configured geocoding provider. Supported providers:\n\n- [`nominatim`](https://nominatim.org/)\n  - It uses OpenStreetMap data ([usage\n    policy](https://operations.osmfoundation.org/policies/nominatim/)).\n  - It doesn't require an API key, but it is rate-limited to 1 request per\n    second (not advised if you are ingesting bulk data if you use the\n    default `NOMINATIM_URL` instance).\n  - It supports a custom `NOMINATIM_URL` environment variable to use a custom\n    Nominatim instance.\n- [`google`](https://developers.google.com/maps/documentation/geocoding/start)\n  - It requires a Google Maps API key, set in the `GOOGLE_API_KEY` environment\n    variable.\n  - See [additional usage\n    limits](https://developers.google.com/maps/documentation/geocoding/usage-and-billing)\n    for details. You can set your own usage limits in the Google Cloud\n    console, but keep in mind that above a certain threshold you will be\n    charged.\n\nIf `GEOCODE_PROVIDER` is not set, the application will not attempt to geocode\nthe location data upon ingestion.\n\n### External data sources\n\nBy default, the application will store the GPS data under the configured\n`DB_URL` database.\n\nIf you have an existing database with GPS data, you can configure it in the\n`.env` file through the `DB_LOCATION_URL` variable. The application will then\nread the data from the external source and expose it through the API.\n\nConsult the `.env.example` file if the column names in your database differ from\nthe default ones.\n\nNote however that:\n\n- The external data source must have a `deviceId` column (or whatever column\n  name you configured in the `.env` file) that uniquely identifies the device\n  that generated the data, and it must point to a valid device in the\n  application database.\n\n- Changes to the ownership of the devices or deletion of devices in the\n  application database will not be reflected in the external data source.\n\n## Development\n\n### Compile and Hot-Reload for Development\n\n#### Backend\n\n```sh\nnpm run dev\n```\n\n#### Frontend\n\n```sh\ncd frontend\nnpm run dev\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacklight%2Fgpstracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblacklight%2Fgpstracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacklight%2Fgpstracker/lists"}