From 84a434268f1bfe46ac6e66a0d239e5ad160e417b Mon Sep 17 00:00:00 2001
From: Paul van Tilburg <paul@luon.net>
Date: Mon, 21 Feb 2022 17:46:23 +0100
Subject: [PATCH] Add README.md and LICENSE file (closes: #6)

Also link the files from the crate and include `README.md` as main crate
documentation.
---
 Cargo.toml  |  3 ++
 LICENSE     | 19 ++++++++++++
 README.md   | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/main.rs |  6 +---
 4 files changed, 107 insertions(+), 5 deletions(-)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/Cargo.toml b/Cargo.toml
index c4e96d8..a04bfb2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,9 @@
 [package]
 name = "sinoptik"
+description = "Service that provides an API for today's weather forecast"
 version = "0.1.0"
+readme = "README.md"
+license = "MIT"
 edition = "2021"
 
 [dependencies]
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..e3e706f
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+The MIT License (MIT)
+Copyright (c) 2018 Paul van Tilburg
+
+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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..86a5f11
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Sinoptik
+
+Sinoptik is a (REST) API service that provides an API for today's weather
+forecast.  It can provide you with a specific set or all available metrics
+that it supports.
+
+Currently supported metrics are:
+
+* Air quality index (per hour, from [Luchtmeetnet])
+* NO₂ concentration (per hour, from [Luchtmeetnet])
+* O₃ concentration (per hour, from [Luchtmeetnet])
+* Particulate matter (PM10) concentration (per hour, from [Luchtmeetnet])
+* Pollen (per hour, from [Buienradar])
+* Pollen/air quality index (per hour, from [Buienradar])
+* Precipitation (per 5 minutes, from [Buienradar])
+* UV index (per day, from [Buienradar])
+
+[Buienradar]: https://buienradar.nl
+[Luchtmeetnet]: https://luchtmeetnet.nl
+
+Because of the currently supported data providers, only data for
+The Netherlands can be queried.
+
+## Building & running
+
+Using Cargo, it is easy to build and run Sinoptik, just run:
+
+```shell
+$ cargo run --release
+```
+
+(Note that Rocket listens on 127.0.0.1:3000 by default for debug builds, i.e. if you don't
+add `--release`.)
+
+You can provide Rocket with configuration to use a different address and/or port.
+Just create a `Rocket.toml` file that contains:
+
+```toml
+[default]
+address = 0.0.0.0
+port = 4321
+```
+
+## Forecast API
+
+The `/forcast` endpoint provides forecasts per requested metric a list of
+forecast item which are each comprised of a value and its (UNIX) timestamp.
+It does so for a requested location.
+
+### Locations
+
+To select a location, you can either provide an address, or a geocoded position
+by providing a latitude and longitude.
+For example to get forecasts for all metrics for the Stationsplein in Utrecht,
+use:
+
+```
+GET /forecast?address=Stationsplein,Utrecht&metrics[]=all
+```
+
+or directly by using its geocoded position:
+
+
+```
+GET /forecast?lat=52.0902&lon=5.1114&metrics[]=all
+```
+
+### Metrics
+
+When querying, the metrics need to be selected. It can be one of: `AQI`, `NO2`,
+`O3`, `PAQI`, `PM10`, `pollen`, `precipitation` or `UVI`. If you use metric `all`, or
+`all` is part of the selected metrics, all metrics will be retrieved.
+Note that the parameter "array" as well as the repeated parameter notations are supported. For example:
+
+```
+GET /address=Stationsplein,Utrecht&metrics[]=AQI&metrics[]=pollen
+GET /address=Stationsplein,Utrecht&metrics=AQI&metrics=pollen
+GET /address=Stationsplein,Utrecht&metrics=all
+```
+
+## License
+
+Sinoptik is licensed under the MIT license (see the `LICENSE` file or
+<http://opensource.org/licenses/MIT>).
diff --git a/src/main.rs b/src/main.rs
index e179e64..3c4a214 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,8 +1,4 @@
-//! Service that provides today's weather forecast for air quality, rain and UV metrics.
-//!
-//! This is useful if you want to prepare for going outside and need to know what happens in the
-//! near future or later today.
-
+#![doc = include_str!("../README.md")]
 #![warn(
     clippy::all,
     missing_debug_implementations,