(quick-start-01)=

```{raw} html
<style>
  #pst-primary-sidebar {
      display: none;
    }
</style>
```

# Quick Start Guide

**api_24sea** is a Python project designed to provide aid for the interaction
with data from the [24SEA API](https://api.24sea.eu/docs/v1).

## Installation

The package supports Python 3.8 and above. To install it, run the following
command in your terminal:

```shell
pip install api_24sea
```

## DataSignals Usage

:::{note}
The following example shows the classical usage of the datasignals module.

* The first step is package installation, and after that the example code
  cells show how to:
  * Import the package and other useful libraries.
  * Load the environment variables from a `.env` file.
    This step is optional, since if any of the following names for
    user and password in the system, the package will authenticate
    automatically.
  * `API_24SEA_USERNAME`, `24SEA_API_USERNAME`, `TWOFOURSEA_API_USERNAME`,
    `API_TWOFOURSEA_USERNAME` for the username.
  * `API_24SEA_PASSWORD`, `24SEA_API_PASSWORD`, `TWOFOURSEA_API_PASSWORD`,
    `API_TWOFOURSEA_PASSWORD` for the password.
  * After that, API can be instantiated and authenticated.
  * Finally, the user can get data from the API. The API and AsyncAPI classes
    will authenticate lazily if the environment variables are loaded, or the
    user can authenticate manually before performing the data retrieval.
:::

### Importing the package

```python
# %%
# **Package Imports**
# - From the Python Standard Library
import logging
import os

# - From third party libraries
import dotenv  # <-- Not necessary to api_24sea per se, but useful for
               #     loading environment variables. Install it with
               #     `pip install python-dotenv`

# - Local imports
from api_24sea.version import __version__, parse_version
from api_24sea.datasignals.core import API
```

```python
# %%
# **Package Versions**
print("Working Folder: ", os.getcwd())
print(f"Package {parse_version(__version__)}")
# **Notebook Configuration**
# Use logging.WARNING to avoid too much logging output from the package,
# which can be useful for debugging but can be overwhelming in normal usage.
# The user can change the logging level to DEBUG to see more detailed logs,
# or to ERROR to see only error messages.
logging.basicConfig(level=logging.WARNING)
```

### Setting up the environment variables (optional)

This step assumes that you have a file structure similar to the following one:

```shell
.
├── env
│   └── .env
├── notebooks
│   └── example.ipynb
└── requirements.txt
```

The `.env` file should look like this:

```shell
API_24SEA_USERNAME=your_username
API_24SEA_PASSWORD=your_password
```

With this in mind, the following code snippet shows how to load the environment
variables from the `.env` file:

```python
# %%
# **Load Environment Variables from .env File**
_ = dotenv.load_dotenv("../env/.env")
if _:
    print("Environment Variables Loaded Successfully")
    print(os.getenv("API_24SEA_USERNAME"))
    # print(os.getenv("API_24SEA_PASSWORD"))
else:
    raise Exception("Environment Variables Not Loaded")
```

### Initializing the API

Initializing the API is as simple as instantiating the API class.
The API will authenticate automatically if the environment variables are loaded,
otherwise the user can authenticate manually by calling the `authenticate`
method from the API class.

```python
# %%
# **Initialize the API**
api = API()
```

#### Authentication (optional)

The authentication step is performed automatically if the environment variables
`API_24SEA_USERNAME` and `API_24SEA_PASSWORD` are loaded. The user can also
authenticate manually by calling the `authenticate` method from the API class.

```python
# %%
# **Authentication**
api.authenticate("some_other_username", "some_other_password")
```

#### Checking the available metrics

```python
# %%
# **Metrics Overview**
# The metrics overview is a summary of the metrics available in the API and
# can be accessed from a hidden method in the DataSignals class.
# It will show all the available metrics with the corresponding units
# and the time window for which the user is allowed to get data
api.metrics_overview
```

### Getting sample data from the API

After loading the environment variables and authenticating with the API,
the user can get data from
[24SEA API endpoints](https://api.24sea.eu/docs/v1).

The data is retrieved and stored in the DataFrame. All the metrics are stored
in separate columns, and the timestamps are set as the index of the DataFrame.

The data retrieval is done by specifying the sites or the locations or both,
the metrics, and timestamps.

* **Sites**: Case insensitive, it can either match `site` or `site_id`. It is
  an optional parameter.
* **Locations**: Case insensitive, it can either match `location` or
  `location_id`. It is an optional parameter.
* **Metrics**: Case insensitive, it can be a partial match of the metric name.
  If the site and location are specified, and metrics equals `all`, all the
  "allowed" metrics for the specified site and location will be retrieved.
* **Timestamps**: Timezone-aware datetime, strings in ISO 8601 format, or
  shorthand strings compatible with the
  [shorthand_datetime package](https://pypi.org/project/shorthand-datetime/).
  The shorthand strings are a convenient way to specify time windows without
  having to write the exact timestamps. For example, if the user wants to get
  data from the last 7 days, they can simply specify `now-7d` as the start
  timestamp and `now` as the end timestamp.

### Notebook Examples

The Jupyter notebook examples are also available as rendered pages in the
documentation:

* {doc}`../examples/01-get-data`
* {doc}`../examples/02-get-data-async`
* {doc}`../examples/03-get-availability`
* {doc}`../examples/04-get-null-timestamps`
* {doc}`../examples/05-get-stats`
* {doc}`../examples/06-get-oldest-timestamp`