From 2faf6d2061f2de2d7e8f1ff8692cf903db7dd7a2 Mon Sep 17 00:00:00 2001 From: Aaron Parecki Date: Wed, 23 Sep 2015 09:01:54 -0700 Subject: [PATCH] add readme and contributing.md --- CONTRIBUTING.md | 1 + README.md | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 43 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2eebfde --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +By submitting code to this project, you agree to irrevocably release it under the same license as this project. See README.md for more details. \ No newline at end of file diff --git a/README.md b/README.md index baa94ac..44195f3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,50 @@ # Compass +Compass is a GPS tracking server that stores data in [flat files](https://github.com/aaronpk/QuartzDB). -### Credits +## Setup + +In the `compass` directory, copy `.env.example` to `.env` and fill in the details. Install the dependencies with composer. + + +## API + +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. + +### Writing + +To write to a database, make a POST request in JSON format with the following keys: + +`POST /api/input` + +* locations - a list of GeoJSON objects +* token - the write token for the database + +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. + +The open source iOS [GPS Logger](https://github.com/esripdx/GPS-Logger-iOS) will send data in this format by default. + +### Reading + +To read a database, make a GET request with the following keys: + +`GET /api/query` + +* token - the read token for the database +* date - specify a date to return all data on that day +* tz - timezone string (e.g. America/Los_Angeles) which will be used to determine the absolute start/end times for the day + + + +## Credits Compass icon by Ryan Spiering from the Noun Project. -### License +## License + +Copyright 2015 by Aaron Parecki + +Compass is licensed under the [Apache 2.0 license](http://opensource.org/licenses/Apache-2.0) -The Lumen framework is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT) +Compass is built using the Lumen framework, which is licensed under the [MIT license](http://opensource.org/licenses/MIT)