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.

169 lines
5.8 KiB

7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 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. ## Requirements
  5. * PHP 5.5 or above
  6. * MySQL (for storing user accounts and lists of databases, not for storing the actual location data)
  7. ### PHP extensions
  8. You'll need to make sure the following PHP extensions are installed. Typically these are installed using the package manager of your operating system.
  9. * curl
  10. * mbstring
  11. * phpunit
  12. * zip
  13. * unzip
  14. ### Optional
  15. * Redis (for the job queue, can use MySQL instead)
  16. ## Setup
  17. Compass is built using the [Lumen framework](https://lumen.laravel.com/). If you have any trouble getting started, you can refer to the [Lumen documentation](https://lumen.laravel.com/docs/5.1) for tips that may have been skipped or assumed in these instructions.
  18. In the `compass` directory, copy `.env.example` to `.env` and fill in the details. Install the dependencies with composer.
  19. ```
  20. $ composer install
  21. ```
  22. ### Web Server
  23. Your web server will need to support URL re-routing to the index.php file of compass. This will vary based on your web server.
  24. - If you're using Apache, this will involve URL re-writing likely using .htaccess
  25. - If you're using Nginx, this will involve incorporating the following code into your server block, you should also add any applicable fastcgi settings inside the location block below:
  26. ```
  27. try_files $uri /index.php?$args;
  28. location /index.php {
  29. fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
  30. }
  31. ```
  32. ### Job Queue
  33. For the job queue you will either need to have one of the supported options by Lumen. The two most likely options are an SQL database or Redis.
  34. You can find other supported options [here](https://lumen.laravel.com/docs/5.1/queues#introduction)
  35. If you're using the database queue driver (`QUEUE_DRIVER=database` defined in `.env`), you'll need to create the migration for that table:
  36. ```
  37. $ php artisan queue:table
  38. ```
  39. If you're using Redis, make sure you've installed the Redis server and set `QUEUE_DRIVER=redis`.
  40. You will need to run the database migrations to create the database schema:
  41. ```
  42. $ php artisan migrate
  43. ```
  44. Make sure the storage folder you've defined in `STORAGE_DIR` is writable by the web server (or by the PHP process if you're using php-fpm).
  45. To process jobs on the queue, run
  46. ```
  47. $ php artisan queue:listen
  48. ```
  49. For more details on how to configure this to run in the background, see https://lumen.laravel.com/docs/5.1/queues#running-the-queue-listener
  50. ## API
  51. 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.
  52. ### Writing
  53. To write to a database, make a POST request in JSON format with the following keys:
  54. `POST /api/input`
  55. * locations - a list of GeoJSON objects
  56. * token - the write token for the database (as a query string parameter or in the post body)
  57. 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.
  58. The open source iOS [GPS Logger](https://github.com/aaronpk/GPS-Logger-iOS) will send data in this format by default.
  59. ```
  60. POST /api/input?token=XXXXXXX HTTP/1.1
  61. Content-type: application/json
  62. {
  63. "locations": [
  64. {
  65. "type": "Feature",
  66. "geometry": {
  67. "type": "Point",
  68. "coordinates": [-122.621, 45.535]
  69. },
  70. "properties": {
  71. "timestamp": "2017-01-01T10:00:00-0700",
  72. "horizontal_accuracy": 65
  73. }
  74. }
  75. ],
  76. "token": "XXXXXXX"
  77. }
  78. ```
  79. ### Reading
  80. To read a database, make a GET request as follows:
  81. #### Get all data for a calendar day
  82. `GET /api/query`
  83. * token - (required) the read token for the database
  84. * 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
  85. * format - (optional, default "full") either "full" or "linestring"
  86. * full - return one JSON record for each result in the database
  87. * linestring - combine all the returned results into a GeoJSON linestring
  88. * date - specify a date to return all data on that day (YYYY-mm-dd format)
  89. #### Get the last location before a given timestamp
  90. `GET /api/last`
  91. * token - (required) the read token for the database
  92. * 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
  93. * 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)
  94. * 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
  95. #### Find the last location matching a clock time
  96. `GET /api/find-from-localtime`
  97. This API method can help you answer the question "Where was I when my watch read 9:30am on July 15th?".
  98. 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.
  99. * token - (required) the read token for the database
  100. * input - specify a clock time in the format `YYYY-mm-dd HH:MM:SS`
  101. This will query the database and find the closest matching location for when your clock read that time.
  102. ## Credits
  103. Compass icon by Ryan Spiering from the Noun Project.
  104. Screenshot of the map view by Sebastiaan Andeweg.
  105. ## License
  106. Copyright 2015 by Aaron Parecki
  107. Compass is licensed under the [Apache 2.0 license](http://opensource.org/licenses/Apache-2.0)
  108. Compass is built using the Lumen framework, which is licensed under the [MIT license](http://opensource.org/licenses/MIT)