> For the complete documentation index, see [llms.txt](https://brightwind.gitbook.io/brighthub-user-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://brightwind.gitbook.io/brighthub-user-docs/brighthub-python-user-guide/accessing-data-via-the-brighthub-api.md).

# Accessing data via the BrightHub API

You can quickly pull metadata and timeseries data from measurement stations you have access to using the BrightHub API for Python. This page provides a short tutorial in the form of an example, pulling timeseries and metadata from an open source data set.

{% hint style="warning" %}
This tutorial only details using the BrightHub API prepackaged within the opensource Python BrightWind library.

For more detailed documentation on using the BrightHub API see the [API Reference](/brighthub-user-docs/api-reference.md).
{% endhint %}

***

**Before starting**

You should have:

* Installed the BrightWind Python library (see [BrightWind Library Installation](/brighthub-user-docs/brighthub-python-user-guide/brightwind-library-installation.md))
* Set up a free BrightHub account (see [Create a BrightHub User Account](/brighthub-user-docs/quick-start-guide/create-a-brighthub-user-account.md))
* Set up your own measurement station (see [Station Setup Guide](/brighthub-user-docs/station-setup-guide.md))

***

## Authenticate

The library authenticates with an API key, so no password is ever written into a script. Create one from Account Settings, as described in [API Key Management](/brighthub-user-docs/api-reference/api-key-management.md), and note the **Client ID** and **Client Secret**. The secret is shown only once.

Set both as environment variables. The library reads them automatically, so no login step is needed in code:

{% tabs %}
{% tab title="Windows" %}
Open the command prompt in Administrator mode and run:

```
setx BRIGHTHUB_CLIENT_ID "<API key client ID>"
setx BRIGHTHUB_CLIENT_SECRET "<API key client secret>"
```

If Anaconda or a Python environment is already running, restart it for the variables to take effect.
{% endtab %}

{% tab title="macOS and Linux" %}
Add the following to the shell profile, then open a new terminal:

```sh
export BRIGHTHUB_CLIENT_ID="<API key client ID>"
export BRIGHTHUB_CLIENT_SECRET="<API key client secret>"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
An API key belongs to a user account and carries exactly that user's permissions. A station that cannot be opened in the browser is not reachable from Python either.
{% endhint %}

## Find a station

Every call is made against a measurement station's UUID, so the first step is to list the stations that can be reached:

```python
import brightwind as bw

bw.LoadBrightHub.get_measurement_stations()
```

This returns a `pandas.DataFrame` of the stations available to the account, including the UUID of each. To narrow it down, filter by station type or by plant:

```python
bw.LoadBrightHub.get_measurement_stations(measurement_station_type='mast')
bw.LoadBrightHub.get_plants(plant_type='onshore_wind')
```

Copy the UUID of the required station and keep it to hand:

```python
measurement_station_uuid = '9344e576-6d5a-45f0-9750-2a7528ebfa14'
```

## Check the period of measurement

Before pulling data, it is worth knowing what period is actually available:

```python
bw.LoadBrightHub.get_start_end_dates(measurement_station_uuid)
```

```
{'start_date': '2015-12-22T00:01:00', 'end_date': '2016-12-19T23:01:00'}
```

## Get the timeseries data

```python
data = bw.LoadBrightHub.get_data(measurement_station_uuid, file_extension='.parquet')
data.head()
```

The data comes back as a `pandas.DataFrame` indexed by timestamp, with one column per measurement.

To restrict the period, pass either or both date filters. Note the brightwind convention: `date_from` is **inclusive** and `date_to` is **exclusive**.

```python
data = bw.LoadBrightHub.get_data(measurement_station_uuid,
                                 date_from='2016-06-01',
                                 date_to='2016-07-01',
                                 file_extension='.parquet')
```

{% hint style="info" %}
`file_extension` accepts `'.csv'` or `'.parquet'`. Parquet downloads faster and preserves column data types, so it is the better choice for anything large, but it needs a parquet engine installed:

```sh
pip install brightwind[parquet]
```

The current default is `'.csv'`, kept for backwards compatibility. It changes to `'.parquet'` in the next major release of brightwind, and omitting the argument raises a `DeprecationWarning`, so pass it explicitly.
{% endhint %}

## Get the data model

The station's metadata is returned as an IEA Wind Task 43 WRA Data Model, which the `MeasurementStation` class turns into something readable:

```python
data_model_json = bw.LoadBrightHub.get_data_model(measurement_station_uuid)

station = bw.MeasurementStation(data_model_json)
station.get_table()
```

See [IEA Task 43 WRA Data Model](/brighthub-user-docs/station-setup-guide/iea-task-43-wra-data-model.md) for what the model contains.

## Get reanalysis data

Reanalysis nodes can be pulled by coordinate rather than by station:

```python
bw.LoadBrightHub.get_reanalysis('ERA5', latitude=53.4, longitude=-9.1,
                                date_from='2015-01-01', date_to='2020-01-01')
```

A `MeasurementStation` object and a `pandas.DataFrame` are returned for each node. Use `nearest_nodes` to pull more than the single closest node.

{% hint style="warning" %}
The library accepts `ERA5` and `MERRA-2`. CERRA is available in the BrightHub map page but is not yet selectable through `get_reanalysis`. See [Download Reanalysis Data](/brighthub-user-docs/quick-start-guide/download-reanalysis-data.md) to download it from the user interface.
{% endhint %}

## Next

The data returned above is raw. To apply the station's cleaning and calibration before analysing it, see [Downloading cleaned and calibrated data](/brighthub-user-docs/brighthub-python-user-guide/downloading-cleaned-and-calibrated-data.md).