weather-scraper/README.md

# Weather Web-Scraper

> **CAUTION**  
> The following utility is in EARLY developement. Many promises made in this
> readme might not actually be true. Hopefully one day we'll be out of beta ~and
> be releasing on time~

An utility to scrape italian weather websites to collect and compare weather
information for Pisa

## Usage

> **WARNING**  
> The script is configured to run on Nix, and because of this is more
> complicated than it needs to be. You can remove unnecessary stuff if you're
> not running this on nix

The script scrapes the weather forecast from the implemented sources (see the
table below) and returns an object with the following fields

-   **today:** an object with elements from the hour after the current one to
    23, of type `hourly` (see below)
-   **tomorrow:** an object with elements from hours 0 to 23, of type `hourly`
    (see below)
-   **dayAfterTomorrow:** an object with elements from hours 0 to 23, of type
    `hourly` (see below)
-   **week:** an object with days 0 to 6, of type `daily`
-   **format:** an object specifying the meaning of `hourly` and `daily` type
    for the objects above

The keys for `today`, `tomorrow` and `dayAfterTomorrow` are intended as hours
where `0` refers to the time from 0:00 to 0:59, and `23` refers to the time from
23:00 to 23:59.

The keys for the `week` entry are intended as an offset from today. That is, the
object at `0` will be the results for today, the object at `1` will be the
results for tomorrow, and the object at `6` will be the results for 6 days from
now

Each source has its own format and they are specified below in the sources
section (as well as in the object returned by the scraper)

### Sources

These are the sources that are currently implemented or will be implemented
eventually, together with the current level of implementation

```
✅ = implemented
🚧 = partially implemented
⛔️ = Not implemented
```

| Source                                         | Status | Comments                                        |
| ---------------------------------------------- | ------ | ----------------------------------------------- |
| [iLMeteo](https://www.ilmeteo.it)              | ✅     |                                                 |
| [3Bmeteo](https://www.3bmeteo.com/)            | 🚧     | Precipitation might not work as intended        |
| [OpenMeteo](https://open-meteo.com/)           | ✅     |                                                 |
| [Aeronautica Militare](http://www.meteoam.it/) | 🚧     | Week only has `[0..4]` instead of `[0..6]` days |

<details>
<summary>iLMeteo</summary>
  
Format:

```json
{
    "hourly": {
        "temperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitation": {
            "type": "number",
            "unit": "mm"
        },
        "apparentTemperature": {
            "type": "number",
            "unit": "°C"
        }
    },
    "daily": {
        "minimumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "minimumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitationSum": {
            "type": "number",
            "unit": "mm"
        }
    }
}
```

</details>

<details>
<summary>3Bmeteo</summary>
  
Format:

```json
{
    "hourly": {
        "temperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitation": {
            "type": "number",
            "unit": "mm"
        },
        "apparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "weatherCode": {
            "type": "string"
        }
    },
    "daily": {
        "minimumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "minimumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitationSum": {
            "type": "number",
            "unit": "mm"
        }
    }
}
```

</details>

<details>
<summary>OpenMeteo</summary>
  
Format:

```json
{
    "hourly": {
        "temperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitation": {
            "type": "number",
            "unit": "mm"
        },
        "precipitationProbability": {
            "type": "number",
            "unit": "%"
        },
        "apparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "weatherCode": {
            "type": "number",
            "unit": "WMO code"
        }
    },
    "daily": {
        "minimumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "minimumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumApparentTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitationSum": {
            "type": "number",
            "unit": "mm"
        },
        "weatherCode": {
            "type": "number",
            "unit": "WMO code"
        }
    }
}
```

</details>

<details>
<summary>Aeronautica Militare</summary>
  
Format:

```json
{
    "hourly": {
        "temperature": {
            "type": "number",
            "unit": "°C"
        },
        "precipitationProbability": {
            "type": "number",
            "unit": "%"
        }
    },
    "daily": {
        "minimumTemperature": {
            "type": "number",
            "unit": "°C"
        },
        "maximumTemperature": {
            "type": "number",
            "unit": "°C"
        }
    }
}
```

</details>