You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

79 lines
3.2 KiB

5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
  1. # Compass
  2. Compass is a GPS tracking server that stores data in [flat files](https://github.com/aaronpk/QuartzDB).
  3. ![mapview](screenshot-mapview.jpg)
  4. ## Setup
  5. In the `compass` directory, copy `.env.example` to `.env` and fill in the details. Install the dependencies with composer.
  6. ## API
  7. After you create a tracking database, you can visit the database's settings page to get a read or write token. These tokens are used with the API to update or retrieve data.
  8. ### Writing
  9. To write to a database, make a POST request in JSON format with the following keys:
  10. `POST /api/input`
  11. * locations - a list of GeoJSON objects
  12. * token - the write token for the database
  13. The GeoJSON objects must have at least one property, "timestamp", which is can be any value that can be interpreted as a date. The object can have any additional properties you wish.
  14. The open source iOS [GPS Logger](https://github.com/esripdx/GPS-Logger-iOS) will send data in this format by default.
  15. ### Reading
  16. To read a database, make a GET request as follows:
  17. #### Get all data for a calendar day
  18. `GET /api/query`
  19. * token - (required) the read token for the database
  20. * tz - (optional, default UTC) timezone string (e.g. America/Los_Angeles) which will be used to determine the absolute start/end times for the day
  21. * format - (optional, default "full") either "full" or "linestring"
  22. * full - return one JSON record for each result in the database
  23. * linestring - combine all the returned results into a GeoJSON linestring
  24. * date - specify a date to return all data on that day (YYYY-mm-dd format)
  25. #### Get the last location before a given timestamp
  26. `GET /api/last`
  27. * token - (required) the read token for the database
  28. * tz - (optional, default UTC) timezone string (e.g. America/Los_Angeles) which will be used to determine the absolute start/end times for the day
  29. * before - (optional, default to now) specify a full timestamp to return a single record before this date (the point returned will be no more than 24 hours before the given date)
  30. * geocode - (optional) if "true", then the location found will be reverse geocoded using [Atlas](https://atlas.p3k.io) to find the city and timezone at the location
  31. #### Find the last location matching a clock time
  32. `GET /api/find-from-localtime`
  33. This API method can help you answer the question "Where was I when my watch read 9:30am on July 15th?".
  34. Timestamps in Exif data do not include the timezone offset, and there is no standard mechanism for including the timezone offset in Exif. Some Canon cameras put the offset in a field, but not all of them do. You can use this method to find your location given an Exif date.
  35. * token - (required) the read token for the database
  36. * input - specify a clock time in the format `YYYY-mm-dd HH:MM:SS`
  37. This will query the database and find the closest matching location for when your clock read that time.
  38. ## Credits
  39. Compass icon by Ryan Spiering from the Noun Project.
  40. Screenshot of the map view by Sebastiaan Andeweg.
  41. ## License
  42. Copyright 2015 by Aaron Parecki
  43. Compass is licensed under the [Apache 2.0 license](http://opensource.org/licenses/Apache-2.0)
  44. Compass is built using the Lumen framework, which is licensed under the [MIT license](http://opensource.org/licenses/MIT)