### Example Hourly Forecast URL

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

An example of a fully constructed URL for an hourly forecast file, based on the HOURLY_PATTERN.

```text
https://data.ecmwf.int/forecasts/20220123/00z/ifs/0p25/oper/20220123000000-240h-oper-fc.grib2
```

--------------------------------

### Initialize ECMWF Open Data Client

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Instantiate the Client with various configuration options. This example shows common parameters for specifying the data source, model, resolution, and other operational settings.

```python
from ecmwf.opendata import Client

client = Client(
    source="ecmwf",
    model="ifs",
    resol="0p25",
    beta=False,
    preserve_request_order=False,
    infer_stream_keyword=True,
    debug=False,
    verify=True,
    use_sas_token=None,
    sas_known_key="ecmwf",
    sas_custom_url=None,
    source_accept_ranges=None,
    source_accept_multiple_ranges=None,
)
```

--------------------------------

### Configuration Reference

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/README.md

Comprehensive guide to all configuration options, including client parameters, data sources, and environment variables.

```APIDOC
## Configuration Reference

### Description
This document provides a complete overview of all configuration options available for the ECMWF OpenData library, covering client initialization, data source URLs, environment variables, and feature flags.

### Client Constructor Options
- 13 parameters with default values are available for client initialization.

### Data Sources
- 6 built-in sources (ECMWF, AWS, Azure, Google, esuites, testdata).
- Support for custom URL sources.

### Configuration Methods
- **Environment Variables**: `ECMWF_OPENDATA_URLS` can be used to specify custom data source URLs.
- **Configuration Files**: Settings can be defined in `~/.ecmwf-opendata`.

### Other Configuration Options
- Logging configuration.
- Request defaults for forecasts, ensembles, and seasonal data.
- Feature flags (e.g., `beta`, `preserve_request_order`, `infer_stream_keyword`).
- Stream structure changes (pre/post 2026-05-12).
- SSL verification settings.
- HTTP range request settings.
- Azure SAS token configuration.
- Backward compatibility settings (e.g., `class` keyword).
```

--------------------------------

### Install ECMWF Open Data

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

Install the core library or with optional eccodes support for GRIB/BUFR file inspection.

```bash
pip install ecmwf-opendata                # Core only
pip install ecmwf-opendata[eccodes]       # With eccodes
```

--------------------------------

### Custom Source URL Example

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Define custom source URLs in a JSON configuration file and then use them when initializing the Client. This allows for organization-specific data sources.

```json
{
  "myorg-production": "https://data.myorg.example.com/ecmwf-forecasts",
  "myorg-staging": "https://staging.myorg.example.com/forecasts"
}
```

```python
client = Client(source="myorg-production")
```

--------------------------------

### Python: Request Expansion Examples

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

Demonstrates how list values and ranges expand automatically in requests. Use this to understand how to specify parameters like 'param', 'step', 'date', and 'time'.

```python
# These are equivalent:
param=["2t", "msl"]
param="2t/msl"
param=[2t, "to", msl]  # If shorthand defined (it's not)

# Range expansion (5-element format)
step=[0, "to", 240, "by", 12]  # → [0, 12, 24, ..., 240]
date=[20220120, "to", 20220125]  # → 6 consecutive days
time=[0, "to", 18, "by", 6]  # → [0, 6, 12, 18]
```

--------------------------------

### Install ecmwf-opendata Package

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Install the ecmwf-opendata Python package using pip.

```bash
pip install ecmwf-opendata
```

--------------------------------

### Install eccodes Library

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/05-grib-bufr-utilities.md

Install the eccodes library using pip or conda. This is a prerequisite for the grib/bufr modules.

```bash
pip install eccodes
```

```bash
conda install -c conda-forge eccodes
```

--------------------------------

### Custom Source URL Resolution Example

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Example of creating a source using a custom URL. When accept_ranges and accept_multiple_ranges are None, the function attempts to auto-detect these capabilities from the server's response headers.

```python
# Custom source
source = source_factory(
    name="https://myserver.example.com/forecast-data",
    accept_ranges=None,  # Auto-detect
    accept_multiple_ranges=None
)
# Result: Source(url="https://myserver.example.com/forecast-data", name=None, ...)
```

--------------------------------

### Download Specific Fields and Levels

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

This example shows how to download only specific meteorological parameters (e.g., temperature) at particular pressure levels and lead times. This reduces download size and processing time.

```python
from ecmwf.opendata import Client

client = Client()

# Download specific fields at specific levels
result = client.retrieve(
    param="t",           # Temperature
    levtype="pl",        # On pressure levels
    levelist=[500, 850], # 500 hPa and 850 hPa only
    step=[0, 24, 48],    # 3 lead times
    target="selective.grib2"
)
```

--------------------------------

### Manual Python Logging Setup for Client

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Configure Python's logging module manually before creating the client for more granular control over log output, such as directing logs to a file or using specific handlers.

```python
import logging

# Set up logging to file
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='client.log'
)

# Or use a handler
handler = logging.StreamHandler()
handler.setLevel(logging.DEBUG)
logging.getLogger("ecmwf.opendata").addHandler(handler)

from ecmwf.opendata import Client
client = Client()
```

--------------------------------

### Download Multiple Parameters Simultaneously

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

This example shows how to download multiple weather parameters (e.g., 2m temperature, 10m U/V wind components, mean sea level pressure) in a single request. It's useful for gathering related data efficiently.

```python
from ecmwf.opendata import Client

client = Client()

# Download multiple fields at once
result = client.retrieve(
    param=["2t", "10u", "10v", "msl"],
    target="fields.grib2"
)

print(f"Forecast: {result.datetime}")
print(f"Downloaded {result.size} bytes with parameters: 2t, 10u, 10v, msl")
```

--------------------------------

### Download Data on Pressure Levels

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

This example demonstrates how to download data for a specific parameter (e.g., temperature) at various pressure levels (e.g., 500, 700, 850, 925 hPa). Use this when vertical atmospheric profiles are required.

```python
from ecmwf.opendata import Client

client = Client()

# Download temperature on pressure levels
result = client.retrieve(
    param="t",
    levtype="pl",
    levelist=[500, 700, 850, 925],
    target="levels.grib2"
)

print(f"Downloaded temperature at 500, 700, 850, 925 hPa")
```

--------------------------------

### Download Single Surface Parameter (ECMWF HRES)

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Example of downloading a single surface parameter at a specific forecast step from ECMWF's operational forecast. Requires importing the `Client` class.

```python
from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="oper",
    type="fc",
    step=24,
    param="2t",
    target="data.grib2",
)
```

--------------------------------

### Implement Fallback Data Source Strategy

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Provides an example of a fallback strategy that attempts to download data from multiple sources (ECMWF, AWS, Azure, Google) in sequence, handling potential request exceptions.

```python
from ecmwf.opendata import Client
import requests

sources = ["ecmwf", "aws", "azure", "google"]

for source in sources:
    try:
        client = Client(source=source)
        result = client.retrieve(
            param="msl",
            target="data.grib2"
        )
        print(f"Successfully downloaded from {source}")
        break
    except (requests.RequestException, ValueError) as e:
        print(f"{source} failed: {e}, trying next source...")
        continue
else:
    print("All sources failed")
```

--------------------------------

### Typical Usage Flow for Data Retrieval

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

This comprehensive example illustrates the common workflow for downloading meteorological forecast data. It covers client initialization, querying for the latest forecast date, constructing a data request using MARS keywords, downloading the data, and accessing basic information from the result.

```python
# 1. Create client (connects to data source)
from ecmwf.opendata import Client
client = Client(source="aws")  # or "ecmwf", "azure", "google"

# 2. Query latest forecast date (optional)
latest = client.latest(param="msl")

# 3. Build request with MARS keywords
request = {
    "date": latest,              # Forecast run date
    "time": 0,                   # Forecast run time (UTC)
    "type": "fc",                # Forecast type
    "step": [0, 24, 48],         # Lead times in hours
    "param": ["2t", "msl"],      # Meteorological parameters
    "levtype": "sfc",            # Surface level (or "pl" for pressure)
}

# 4. Download data
result = client.retrieve(request, target="forecast.grib2")

# 5. Use result
print(f"Downloaded {result.size} bytes")
print(f"Forecast date: {result.datetime}")
```

--------------------------------

### Attribution Notice Example

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

This is a sample attribution notice displayed by the library per process when using ECMWF data. It reminds users of the CC BY 4.0 license and the requirement to cite ECMWF.

```text
By downloading data from the ECMWF open data dataset, you agree to 
the terms: Attribution 4.0 International (CC BY 4.0). Please 
attribute ECMWF when downloading this data.
```

--------------------------------

### Verify Downloaded GRIB Data Integrity

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/05-grib-bufr-utilities.md

Use grib_index to create an index of GRIB messages in a file and count_gribs to get the total number of messages. This helps verify that the downloaded data matches expectations.

```python
from ecmwf.opendata import Client
from ecmwf.opendata.grib import grib_index, count_gribs

client = Client()

# Download a subset
result = client.retrieve(
    param=["2t", "msl"],
    type="fc",
    step=24,
    target="subset.grib2"
)

# Verify content
index = grib_index("subset.grib2")
print(f"Total messages: {len(index)}")
print(f"Count method: {count_gribs('subset.grib2')}")

# Check what was actually downloaded
params = set(m['param'] for m in index)
print(f"Parameters: {params}")
```

--------------------------------

### Create Source Instances

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Illustrates creating Source instances for explicit configurations like AWS, and for custom URLs with auto-detection of capabilities.

```python
from ecmwf.opendata.sources import Source

# Explicit source
aws_source = Source(
    url="https://ecmwf-forecasts.s3.eu-central-1.amazonaws.com",
    name="aws",
    accept_ranges=True,
    accept_multiple_ranges=False
)

# Custom URL with auto-detection
custom_source = Source(
    url="https://myserver.com/data"
)
```

--------------------------------

### Client Initialization with Source Factory

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Demonstrates initializing the Client class with different source configurations. The 'source' parameter can be a named source like 'aws', a custom URL, or overridden with range support flags.

```python
from ecmwf.opendata import Client

# Automatically resolves source
client = Client(source="aws")
# Internally: client.source = source_factory("aws", None, None)

# Custom URL source
client = Client(source="https://internal.data.org/forecasts")

# Override range support
client = Client(
    source="ecmwf",
    source_accept_ranges=False,
    source_accept_multiple_ranges=False
)
```

--------------------------------

### Initialize Client Class

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Instantiate the Client class with various configuration options. Choose the data source, forecast model, and resolution. Advanced options control experimental data access, request order, stream inference, debugging, and SSL verification.

```python
Client(
    source: str = "ecmwf",
    model: str = "ifs",
    resol: str = "0p25",
    beta: bool = False,
    preserve_request_order: bool = False,
    infer_stream_keyword: bool = True,
    debug: bool = False,
    verify: bool = True,
    use_sas_token: Optional[bool] = None,
    sas_known_key: str = "ecmwf",
    sas_custom_url: Optional[str] = None,
    source_accept_ranges: Optional[bool] = None,
    source_accept_multiple_ranges: Optional[bool] = None,
)
```

--------------------------------

### Handle RuntimeError for Missing eccodes Library

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/08-errors-and-exceptions.md

Catch RuntimeError if the eccodes library is not installed when attempting to use grib_index() or count_gribs(). Install eccodes using pip or conda to resolve this.

```Python
from ecmwf.opendata.grib import grib_index

try:
    index = grib_index("data.grib2")
except RuntimeError as e:
    print(f"eccodes not available: {e}")
```

```Bash
# Install eccodes
pip install eccodes

# Or via conda
conda install -c conda-forge eccodes
```

--------------------------------

### Retry Data Retrieval on Failure

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Implement a retry mechanism for data retrieval. This example retries up to `max_retries` times with a `retry_delay` between attempts, handling `requests.RequestException`.

```python
import time
import requests
from ecmwf.opendata import Client

client = Client()
max_retries = 3
retry_delay = 2

for attempt in range(max_retries):
    try:
        result = client.retrieve(
            param="msl",
            target="data.grib2"
        )
        print(f"Success on attempt {attempt + 1}")
        break
    except requests.RequestException as e:
        if attempt < max_retries - 1:
            print(f"Attempt {attempt + 1} failed: {e}")
            print(f"Retrying in {retry_delay} seconds...")
            time.sleep(retry_delay)
        else:
            print(f"Failed after {max_retries} attempts")
            raise
```

--------------------------------

### Enable Beta Experimental Data Access

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Instantiate the client with `beta=True` to access experimental or beta data, which appends '/experimental' to the resolution path.

```python
client = Client(beta=True)
```

--------------------------------

### Python: Download Latest Forecast

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

Downloads the latest forecast data. Ensure you have the 'ecmwf-opendata' library installed. This snippet saves the data to a file named 'data.grib2'.

```python
from ecmwf.opendata import Client

client = Client()
result = client.retrieve(param="msl", target="data.grib2")
print(f"Downloaded: {result.datetime}")
```

--------------------------------

### Expand Date Range with Integers

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/03-date-utilities.md

Expands a list containing start and end integers to a list of YYYYMMDD date strings. Assumes a step of 1 day.

```python
from ecmwf.opendata.date import expand_date

# YYYYMMDD integers
dates = expand_date([20220120, "to", 20220123])
print(dates)  # ['20220120', '20220121', '20220122', '20220123']
```

--------------------------------

### Handle Connection Errors

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/08-errors-and-exceptions.md

Catch `requests.ConnectionError` and `requests.Timeout` when a network issue prevents connection to the data source. This example shows basic error handling for initial connection attempts.

```python
from ecmwf.opendata import Client
import requests

client = Client(source="https://invalid.server.example.com")

try:
    result = client.retrieve(param="msl", target="data.grib2")
except requests.ConnectionError as e:
    print(f"Connection failed: {e}")
except requests.Timeout as e:
    print(f"Request timed out: {e}")
```

--------------------------------

### Get Latest Forecast Date

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Retrieve the most recent forecast date matching specified parameters without downloading data. Useful for determining the latest available forecast run.

```python
from ecmwf.opendata import Client

client = Client()

# Get latest forecast without time constraint
latest_date = client.latest(type="fc", step=24, param="msl")
print(f"Latest forecast: {latest_date}")

# Get latest at a specific time
latest_0z = client.latest(type="fc", step=24, time=0)
print(f"Latest 00 UTC run: {latest_0z}")

# Use latest date in subsequent retrieve
date = client.latest(type="fc", param="2t")
result = client.retrieve(
    date=date,
    type="fc",
    step=24,
    param="2t",
    target="data.grib2"
)
```

--------------------------------

### Backward Compatibility: Legacy `class` Keyword

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

For compatibility with older ECMWF APIs, the `class` keyword can be used and is mapped to the `model` keyword. This example demonstrates equivalent calls using both keywords.

```python
# These are equivalent:
client.retrieve(class="od", param="msl", target="data.grib2")
client.retrieve(model="ifs", param="msl", target="data.grib2")
```

--------------------------------

### Configure Client Options

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Instantiate the Client with custom options for data source, model, resolution, and request handling. Options include specifying the server (ecmwf, aws, google, azure), model type (ifs, aifs-single, aifs-ens), resolution, and controlling request order and stream keyword inference.

```python
client = Client(
    source="ecmwf",
    model="ifs",
    resol="0p25",
    preserve_request_order=False,
    infer_stream_keyword=True,
)
```

--------------------------------

### Client Initialization

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Initialize the Client with various options to configure data source, model, resolution, and request handling.

```APIDOC
## Client Initialization

### Description
Initializes the `Client` object with configurable options.

### Parameters
#### Constructor Parameters
- **source** (string) - Optional - Specifies the data source server. Possible values: `ecmwf`, `aws`, `google`, `azure`. Defaults to `ecmwf`.
- **model** (string) - Optional - Specifies the data model. Possible values: `ifs`, `aifs-single`, `aifs-ens`. Defaults to `ifs`.
- **resol** (string) - Optional - Specifies the data resolution. Defaults to `0p25`.
- **preserve_request_order** (boolean) - Optional - If `True`, preserves the order of requested fields. If `False`, sorts requests for efficiency. Defaults to `False`.
- **infer_stream_keyword** (boolean) - Optional - If `True`, infers the `stream` keyword. Defaults to `True` if `model` is `ifs`.

### Request Example
```python
client = Client(
    source="ecmwf",
    model="ifs",
    resol="0p25",
    preserve_request_order=False,
    infer_stream_keyword=True,
)
```
```

--------------------------------

### Client Constructor

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Initializes the Client for downloading ECMWF open data. It supports multiple data sources and configuration options for data retrieval.

```APIDOC
## Client Constructor

### Description
Initializes the Client for downloading ECMWF open data. It supports multiple data sources and configuration options for data retrieval.

### Parameters
#### Constructor Parameters
- **source** (str) - Optional - Data source: "ecmwf", "aws", "azure", "google", or a full HTTP/HTTPS URL. ECMWF source is limited to 500 simultaneous connections. Cloud sources (AWS, Azure, Google) are recommended as alternatives.
- **model** (str) - Optional - Forecast model: "ifs" (physics-driven), "aifs-single" (data-driven), or "aifs-ens" (ensemble data-driven).
- **resol** (str) - Optional - Data resolution in degrees. Currently only "0p25" (0.25 degree) is available.
- **beta** (bool) - Optional - Enable access to experimental data. When `True`, appends `/experimental` to the resolution path.
- **preserve_request_order** (bool) - Optional - If `True`, writes retrieved data in the order specified in the request. For example, `param=[2t,msl]` ensures `2t` appears first in output. If `False`, optimizes request ordering to minimize HTTP requests. Note: setting to `True` on large requests adds server load.
- **infer_stream_keyword** (bool) - Optional - Automatically infer the correct `stream` value based on other request parameters. Set `False` to use the stream value exactly as specified. Requires domain knowledge to set correctly when `False`. Default `True` if model is "ifs".
- **debug** (bool) - Optional - Enable debug logging. Sets logging level to DEBUG.
- **verify** (bool) - Optional - Verify SSL certificates in HTTP requests. Set `False` to skip verification (not recommended for production).
- **use_sas_token** (Optional[bool]) - Optional - Enable SAS token authentication for Azure. If `None`, automatically enabled when `source="azure"`.
- **sas_known_key** (str) - Optional - Known SAS token source. Currently only "ecmwf" is predefined. Used with `_get_azure_sas_token()`.
- **sas_custom_url** (Optional[str]) - Optional - Custom URL to fetch SAS tokens from Azure. Required if `sas_known_key` is not recognized.
- **source_accept_ranges** (Optional[bool]) - Optional - Override HTTP range request support detection. If `None`, inferred from response headers.
- **source_accept_multiple_ranges** (Optional[bool]) - Optional - Override multiple byte-range request support detection. If `None`, inferred from response headers. Cloud sources (AWS, Azure, Google) set to `False` by default.
```

--------------------------------

### Override Default Range Settings

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Override the default range request settings for a known source like 'ecmwf' by explicitly setting accept_ranges and accept_multiple_ranges. This example forces multi-range support.

```python
# Override defaults
ecmwf_source = source_factory(
    name="ecmwf",
    accept_ranges=True,
    accept_multiple_ranges=True  # Override default to force multi-range
)
```

--------------------------------

### Get Latest Forecast Datetime

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

The latest() method queries the server for the most recent matching forecast and returns its date and time without downloading the data. This is useful for checking data availability.

```python
from ecmwf.opendata import Client

client = Client(source="ecmwf")

print(client.latest(
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
))
```

--------------------------------

### Using Environment Variable Configured Source

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Instantiate the Client using a source name defined in the ECMWF_OPENDATA_URLS environment variable.

```python
from ecmwf.opendata import Client
c = Client(source='staging')
```

--------------------------------

### MARS Keyword Validation: Spelling Suggestions

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

The library provides spelling suggestions for misspelled MARS keywords using Levenshtein distance. This example shows how a misspelling of 'param' might trigger a warning.

```python
client.retrieve(praam="2t", target="data.grib2")
# Warning: Did you mean 'param' instead of 'praam'?
```

--------------------------------

### Retrieve Data from Google Cloud Storage

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Demonstrates setting the data source to Google Cloud Storage.

```python
from ecmwf.opendata import Client

client = Client(source="google")

result = client.retrieve(
    param="msl",
    target="data.grib2"
)
```

--------------------------------

### Download All Data Fields

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Use the download() method to fetch all data files from the server, ignoring specific parameter keywords. This is useful for downloading entire files.

```python
from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.download(
    param="msl",
    type="fc",
    step=24,
    target="data.grib2",
)
```

--------------------------------

### Extract Maximum Forecast Step

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/03-date-utilities.md

Use this function to get the maximum forecast step value from an integer or a string representation. It correctly parses single step values and range specifications like '0-240'.

```python
from ecmwf.opendata.date import end_step

print(end_step(240))  # 240
print(end_step("240"))  # 240
print(end_step("0-240"))  # 240
print(end_step("100-360"))  # 360
```

--------------------------------

### Download and Open GRIB Data with Pandas/Xarray

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Demonstrates downloading GRIB2 forecast data and opening it with xarray. Requires the 'cfgrib' engine for xarray.

```python
from ecmwf.opendata import Client
import xarray as xr

client = Client()

# Download data
result = client.retrieve(
    param=["2t", "msl"],
    step=24,
    target="forecast.grib2"
)

# Open with xarray (requires cfgrib)
# ds = xr.open_dataset("forecast.grib2", engine="cfgrib")
# print(ds)
```

--------------------------------

### Create Source Instance with Factory

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Use source_factory to create a Source instance for a known source like 'aws'. It automatically resolves the URL and range capabilities. Defaults are used when accept_ranges and accept_multiple_ranges are None.

```python
from ecmwf.opendata.sources import source_factory

# Resolve a known source
aws_source = source_factory(
    name="aws",
    accept_ranges=None,
    accept_multiple_ranges=None
)
print(aws_source.url)  # https://ecmwf-forecasts.s3.eu-central-1.amazonaws.com
print(aws_source.accept_multiple_ranges)  # False
```

--------------------------------

### Handle Non-2xx HTTP Errors

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/08-errors-and-exceptions.md

Catch `requests.HTTPError` when the server returns a non-successful status code (e.g., 404 Not Found, 403 Forbidden, 500 Server Error). This example demonstrates handling authentication-related errors.

```python
from ecmwf.opendata import Client
import requests

client = Client(source="azure", use_sas_token=False)  # No auth

try:
    result = client.retrieve(param="msl", target="data.grib2")
except requests.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e}")
```

--------------------------------

### Download Entire Files

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Use the `download` method to retrieve an entire GRIB file without specifying subsetting parameters. This is useful when you need the complete dataset.

```python
from ecmwf.opendata import Client

client = Client()

# Download full file (ignores param, level, number keywords)
result = client.download(
    type="fc",
    step=24,
    target="full_file.grib2"
)

print(f"Downloaded entire file: {result.size} bytes")
```

--------------------------------

### Enable Debug Logging at Client Initialization

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Enable verbose output from the multiurl library and internal request processing by setting the debug flag to True during Client initialization.

```python
client = Client(debug=True)
```

--------------------------------

### Count GRIB Messages in a File

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/05-grib-bufr-utilities.md

Use this function to get the total number of GRIB messages in a specified file. It's optimized for speed by iterating without extracting metadata. Ensure the file path is correct.

```python
from ecmwf.opendata.grib import count_gribs
from ecmwf.opendata import Client

client = Client()
result = client.retrieve(param="msl", target="data.grib2")

num_messages = count_gribs("data.grib2")
print(f"Downloaded file contains {num_messages} GRIB messages")
```

--------------------------------

### Count BUFR Messages in a File

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/05-grib-bufr-utilities.md

This function counts the total number of BUFR messages in a given file. It is similar to `count_gribs` in its implementation, iterating through messages without metadata extraction. The file must be a valid BUFR file, and the eccodes library must be installed.

```python
from ecmwf.opendata.bufr import count_bufrs
from ecmwf.opendata import Client

client = Client()
result = client.retrieve(type="tf", target="data.bufr")  # type="tf" fetches BUFR data

num_messages = count_bufrs("data.bufr")
print(f"BUFR file contains {num_messages} messages")
```

--------------------------------

### Retrieve Data from AWS

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Demonstrates configuring the client to use AWS as the data source, which is noted for being faster and having no connection limits.

```python
from ecmwf.opendata import Client

# AWS is faster and doesn't have connection limits
client = Client(source="aws")

result = client.retrieve(
    param="msl",
    target="data.grib2"
)
```

--------------------------------

### Index GRIB File Metadata

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/05-grib-bufr-utilities.md

Use `grib_index` to extract MARS metadata from all messages in a GRIB file. This function requires the `eccodes` library to be installed and the input file to be a valid GRIB file. It returns a list of dictionaries, each containing metadata for a GRIB message.

```python
from ecmwf.opendata.grib import grib_index

# Index a downloaded GRIB file
index = grib_index("forecast.grib2")

# Print metadata for first few messages
for msg in index[:3]:
    print(f"Param: {msg['param']}, Level: {msg.get('levelist', 'sfc')}, Step: {msg['step']}h")
# Output:
# Param: 2t, Level: sfc, Step: 0h
# Param: msl, Level: sfc, Step: 0h
# Param: u, Level: 850, Step: 0h

# Find all messages for a specific parameter
msl_messages = [m for m in index if m['param'] == 'msl']
print(f"Found {len(msl_messages)} msl messages")

# Check available levels
levels = set(m.get('levelist', 'sfc') for m in index if m['param'] == 't')
print(f"Temperature available at levels: {sorted(levels)}")
```

--------------------------------

### Python: Try Multiple Data Sources

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

Attempts to download data from multiple sources ('ecmwf', 'aws', 'azure') in a specified order. It breaks the loop and uses the first successful source. Requires the 'requests' library for exception handling.

```python
from ecmwf.opendata import Client
import requests

for source in ["ecmwf", "aws", "azure"]:
    try:
        client = Client(source=source)
        result = client.retrieve(param="msl", target="data.grib2")
        break
    except requests.RequestException:
        print(f"{source} failed, trying next...")
```

--------------------------------

### Source Fallback Strategy

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Demonstrates how to implement a fallback strategy to AWS if the primary ECMWF source fails. Ensure logging is configured to observe connection attempts.

```python
import logging
from ecmwf.opendata import Client

logging.basicConfig(level=logging.WARNING)

# Try primary ECMWF source
try:
    client = Client(source="ecmwf", verify=True)
    result = client.retrieve(param="msl", target="data.grib2")
except Exception as e:
    print(f"ECMWF source failed: {e}, trying AWS...")
    
    # Fall back to AWS
    client = Client(source="aws")
    result = client.retrieve(param="msl", target="data.grib2")
```

--------------------------------

### Assert Invalid Range Bounds

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/08-errors-and-exceptions.md

These assertions ensure that the start value is less than or equal to the end value and that the step is greater than zero in range expansion functions. They are raised by expand_list(), expand_date(), and expand_time() when these conditions are violated. Recovery involves providing valid ranges.

```python
assert start <= end and by > 0, (start, end, by)
```

```python
from ecmwf.opendata.date import expand_list

try:
    expand_list([24, "to", 0])  # Backwards
except AssertionError:
    print("Start must be <= end")

try:
    expand_list([0, "to", 24, "by", 0])  # Zero step
except AssertionError:
    print("Step must be > 0")
```

```python
# Use valid ranges
expand_list([0, "to", 24, "by", 6])      # OK
expand_date([20220120, "to", 20220125])  # OK
expand_time([0, "to", 18, "by", 6])      # OK
```

--------------------------------

### Request AIFS-ENS Data from ECMWF

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/examples/aifs-ens-earthkit.ipynb

Use earthkit-data to request data from the 'ecmwf-open-data' source, specifically targeting the 'ecmwf' client for 'aifs-ens' model data. This example retrieves mean sea level pressure ('msl') and 2 metre temperature ('2t') for a single time step.

```python
ds = earthkit.data.from_source(
    "ecmwf-open-data", 
    source="ecmwf", 
    model="aifs-ens",    
    time=12,
    stream="enfo",
    type="cf",
    param=["msl", "2t"],
    target="data.grib2",
)
```

--------------------------------

### Import Client Class

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

This snippet shows how to import the main Client class from the ecmwf.opendata package. This is the primary way to access the package's functionality.

```python
from ecmwf.opendata import Client
```

--------------------------------

### Python: Download Multiple Levels

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/00-index.md

Downloads data for a specific parameter ('t' for temperature) across multiple pressure levels. Use 'levtype="pl"' for pressure levels and provide a list of desired levels in 'levelist'.

```python
client = Client()
result = client.retrieve(
    param="t",          # Temperature
    levtype="pl",       # Pressure levels
    levelist=[500, 850],
    target="data.grib2"
)
```

--------------------------------

### Expand Numeric Range List

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/03-date-utilities.md

Use this function to expand lists containing numeric range syntax into a flat list of integers. It supports 3-element and 5-element formats for specifying ranges with optional step values. Ensure that start is not greater than end and step is positive to avoid assertion errors.

```python
from ecmwf.opendata.date import expand_list

# Forecast steps
steps = expand_list([0, "to", 24, "by", 6])
print(steps)  # [0, 6, 12, 18, 24]

# Pressure levels
levels = expand_list([100, "to", 1000, "by", 100])
print(levels)  # [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000]

# No expansion
levels = expand_list([500, 700, 850])
print(levels)  # [500, 700, 850]
```

--------------------------------

### get_parts()

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Queries GRIB index files to identify byte-ranges for requested fields, returning tuples of (url, byte_ranges) for partial file downloads.

```APIDOC
## get_parts()

### Description
Query GRIB index files to identify byte-ranges for requested fields. Returns tuples of `(url, byte_ranges)` for partial file downloads.

### Parameters
- **data_urls** (list) - List of data file URLs.
- **for_index** (dict) - Keywords and values to match in index.

### Returns
List of `(url, byte_ranges_tuple)` tuples where `byte_ranges_tuple` is a tuple of `(offset, length)` pairs.

### Raises
- **ValueError**: No matching index entries found for the request.
```

--------------------------------

### Check Request Preparation

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/08-errors-and-exceptions.md

Inspect how the ecmwf-opendata client prepares requests before execution. This snippet shows the URLs that will be constructed and the index that will be searched, aiding in understanding the client's internal logic.

```python
from ecmwf.opendata import Client

client = Client()

# See what the client will request
for_urls, for_index = client.prepare_request(
    param="msl",
    type="fc",
    step=24
)

print("URLs will be constructed with:", for_urls)
print("Index will be searched for:", for_index)
```

--------------------------------

### Download Ignoring Parameter Keyword

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Demonstrates that the `param` keyword is ignored when using the `download` method, as it downloads the entire file.

```python
# Download ignores param keyword
result = client.download(
    param="msl",  # This is ignored
    type="fc",
    step=24,
    target="full.grib2"
)
```

--------------------------------

### Client.download()

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Downloads the whole data files from the server, ignoring keywords like 'param', 'levelist', or 'number'. It accepts the same parameters as Client.retrieve().

```APIDOC
## Client.download()

### Description
Downloads the whole data files from the server, ignoring keywords like 'param', 'levelist', or 'number'. It accepts the same parameters as Client.retrieve().

### Method
`client.download(**kwargs)`

### Parameters
- **type** (string) - The type of data (compulsory, defaults to 'fc').
- **stream** (string) - The forecast system (optional if unambiguous, compulsory otherwise).
- **date** (string) - The date at which the forecast starts.
- **time** (string) - The time at which the forecast starts.
- **step** (integer) - The forecast time step in hours.
- **target** (string) - The path to the file where the data will be downloaded.

### Request Example
```python
from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.download(
    param="msl",
    type="fc",
    step=24,
    target="data.grib2",
)
```
```

--------------------------------

### SSL Certificate Verification (Production)

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/07-configuration-reference.md

Configures the client to verify SSL certificates using the system's certificate store. This is the recommended setting for production environments.

```python
client = Client(verify=True)  # Default
```

--------------------------------

### Download Latest Forecast Data

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Use this snippet to download the latest forecast for a specific parameter like mean sea level pressure. It initializes the client and retrieves the data, printing the downloaded size and forecast date.

```python
from ecmwf.opendata import Client

# Create client
client = Client()

# Download latest forecast for mean sea level pressure
result = client.retrieve(
    param="msl",
    target="msl.grib2"
)

print(f"Downloaded {result.size} bytes")
print(f"Forecast date: {result.datetime}")
```

--------------------------------

### Specify Time Steps

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/README.md

Use the `step` keyword to select specific time steps for forecasts. Multiple steps can be requested as a list.

```python
...
   step=24,
...
```

```python
...
   step=[24, 48],
...
```

--------------------------------

### Retrieve Data from Azure Storage

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Shows how to configure the client to use Azure Storage as the data source. Note that Azure requires a SAS token, which is auto-generated by the client.

```python
from ecmwf.opendata import Client

# Azure requires SAS token (auto-generated)
client = Client(source="azure")

result = client.retrieve(
    param="msl",
    target="data.grib2"
)
```

--------------------------------

### Download Data for Specific Forecast Steps

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Retrieve forecast data for a defined set of lead times (steps) in hours. This is useful when you need data at particular future points in time.

```python
from ecmwf.opendata import Client

client = Client()

# Download specific forecast lead times
result = client.retrieve(
    param="2t",
    step=[0, 24, 48, 72, 96],
    target="steps.grib2"
)

print(f"Downloaded forecasts for steps: 0, 24, 48, 72, 96 hours")
```

--------------------------------

### Create Source from Custom URL

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/02-source-factory.md

Create a Source instance using a custom URL. Range request capabilities can be explicitly disabled or enabled by setting accept_ranges and accept_multiple_ranges.

```python
# Custom URL
custom_source = source_factory(
    name="https://data.myorg.org/forecasts",
    accept_ranges=False,  # Explicitly disable ranges
    accept_multiple_ranges=False
)
```

--------------------------------

### Retrieve Multiple Parameters and Levels

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Use to download forecast data for multiple parameters and pressure levels. Specify parameters and levels as lists.

```python
# Multiple parameters and levels
result = client.retrieve(
    type="fc",
    step=24,
    param=["2t", "10u", "10v"],  # 2m temperature, 10m winds
    target="forecast.grib2"
)
```

```python
# Pressure level data
result = client.retrieve(
    type="fc",
    step=[12, 24, 36],
    param="t",
    levtype="pl",
    levelist=[500, 850],  # 500 hPa and 850 hPa
    target="levels.grib2"
)
```

--------------------------------

### Retrieve Data with Exact Date and Time

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Demonstrates retrieving data using various formats for specifying the exact date and time, including integers, ISO strings, Python date objects, and datetime objects.

```python
from ecmwf.opendata import Client
from datetime import datetime, date

client = Client()

# Date as YYYYMMDD integer
result = client.retrieve(
    date=20220123,
    time=0,
    param="msl",
    target="data.grib2"
)

# Date as ISO string
result = client.retrieve(
    date="2022-01-23",
    time=0,
    param="msl",
    target="data.grib2"
)

# Date as Python object
result = client.retrieve(
    date=date(2022, 1, 23),
    time=0,
    param="msl",
    target="data.grib2"
)

# Datetime with full precision
result = client.retrieve(
    date=datetime(2022, 1, 23, 0, 0, 0),
    param="msl",
    target="data.grib2"
)
```

--------------------------------

### Client Class Reference

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/README.md

Reference for the primary `Client` class, including its constructor, data retrieval methods, and utility functions.

```APIDOC
## Client Class

### Description
The `Client` class is the primary interface for interacting with the ECMWF OpenData library. It provides methods for downloading data, querying forecasts, and preparing requests.

### Methods
- **Constructor**: Initializes the client with up to 13 parameters.
- **`retrieve(parameters)`**: Downloads data with subsetting capabilities.
- **`download(parameters)`**: Downloads full data files.
- **`latest(parameters)`**: Queries the latest forecast date.
- **`prepare_request(parameters)`**: Normalizes MARS requests.
- **`get_parts(parameters)`**: Extracts byte ranges from data.
- **`patch_stream(parameters)`**: Handles stream mapping.
- **`user_to_url(parameters)`** and **`user_to_index(parameters)`**: Map user-friendly identifiers to URLs and index information.

### Additional Features
- SAS token handling for Azure.
- `Result` class specification.
- File path patterns (HOURLY_PATTERN, MONTHLY_PATTERN).
- MARS keywords reference table.
```

--------------------------------

### Expand Date and Step Ranges for Downloads

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Utilize range notation for specifying forecast steps or dates. This allows for downloading data across a continuous sequence of time points without listing each one individually.

```python
from ecmwf.opendata import Client

client = Client()

# Use range notation instead of explicit lists
result = client.retrieve(
    param="2t",
    step=[0, "to", 240, "by", 24],  # 0, 24, 48, ..., 240
    target="range.grib2"
)

print("Downloaded steps: 0, 24, 48, 72, ..., 240 hours")

# Date ranges
result = client.retrieve(
    date=[20220101, "to", 20220110],  # 10 days
    param="msl",
    target="dates.grib2"
)
```

--------------------------------

### Client Instance Attributes

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/01-client-class.md

Provides access to the resolved data source, model, resolution, and other configuration settings after the Client has been initialized.

```APIDOC
## Client Instance Attributes

### Description
Provides access to the resolved data source, model, resolution, and other configuration settings after the Client has been initialized.

### Attributes
- **source** (Source) - Resolved data source with URL and range request settings.
- **model** (str) - The forecast model specified at construction.
- **resol** (str) - The resolution specified at construction.
- **beta** (bool) - Whether experimental data access is enabled.
- **preserve_request_order** (bool) - Whether request order preservation is enabled.
- **infer_stream_keyword** (bool) - Whether stream inference is enabled.
- **session** (requests.Session) - Shared HTTP session for all requests.
- **verify** (bool) - SSL certificate verification setting.
- **use_sas_token** (bool) - Whether SAS token authentication is active.
- **sas_token** (Optional[str]) - Cached Azure SAS token.
- **url** (str) - The resolved data source URL (property).
```

--------------------------------

### Retrieve Data from Custom URL Source

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Shows how to specify a custom URL for the data source, useful for internal archive servers.

```python
from ecmwf.opendata import Client

# Use an internal archive server
client = Client(source="https://internal-archive.example.com/ecmwf")

result = client.retrieve(
    param="msl",
    target="data.grib2"
)
```

--------------------------------

### Continuous Monitoring for New Forecasts

Source: https://github.com/ecmwf/ecmwf-opendata/blob/main/_autodocs/09-usage-examples.md

Implements a continuous monitoring loop to check for the latest available forecast data, download it if it's newer than a local copy, and handle potential errors. Checks every 10 minutes.

```python
from ecmwf.opendata import Client
from datetime import datetime
import time

client = Client(source="aws")

while True:
    try:
        # Check for new forecast
        latest = client.latest(param="msl")
        print(f"{datetime.utcnow()}: Latest forecast {latest}")
        
        # Download if newer than local copy
        result = client.retrieve(
            date=latest,
            param="msl",
            target="latest.grib2"
        )
        print(f"Downloaded {result.size} bytes")
        
    except Exception as e:
        print(f"Error: {e}")
    
    # Check every 10 minutes
    time.sleep(600)
```