gwdatafind

2.1.1 verified Mon Apr 27 auth: no python

A Python client for the GWDataFind service, used to discover and retrieve Gravitational-Wave data files (e.g., HDF5, GWF) from archives like LIGO/Virgo. Current version 2.1.1, released 2024-12-02. Active development, new releases every few months.

pip install gwdatafind

Common errors

error AttributeError: module 'gwdatafind' has no attribute 'DataFindAPI' ↓

cause Code using the older v1.x API with v2.x installed.

fix

Use import gwdatafind and call gwdatafind.connect() instead.

error gwdatafind.exceptions.AuthenticationError: No authentication token found ↓

cause Connecting to a protected endpoint without setting IGWN_AUTH_TOKEN.

fix

Set the IGWN_AUTH_TOKEN environment variable or install ligo-auth-tokens and run ligo-token.

error TypeError: connect() got an unexpected keyword argument 'host' ↓

cause The `host` parameter was removed in v2.0; use `service` to specify the service endpoint.

fix

Use gwdatafind.connect(service='https://datafind.ligo.org:443') instead of host=.

Warnings

breaking The `connect` function changed from `DataFindAPI` constructor in v1.x to a standalone function in v2.0. Old code using `DataFindAPI` will break. ↓

fix Replace `from gwdatafind import DataFindAPI` with `import gwdatafind` and use `gwdatafind.connect()`.

gotcha The `find_types` method returns a list of strings, but the query is case-sensitive. Use exact observatory code (e.g., 'H1', 'L1', 'V1'). ↓

fix Check exact observatory codes via `connection.find_observatories()`.

deprecated The `find_frame_types` method is deprecated since v2.1 (slated for removal). Use `find_types` instead. ↓

fix Replace `connection.find_frame_types(obs, type)` with `connection.find_types(obs, type)`.

gotcha Default connection timeout is 30 seconds; large queries may need increased timeout via `connect(timeout=120)`. ↓

fix Pass `timeout` parameter to `connect()`: `gwdatafind.connect(timeout=120)`.

Imports

connect
wrong
```
from gwdatafind import connect
```
correct
```
import gwdatafind
```
Since v2.0, connect is a function in the top-level namespace. Using old import will raise AttributeError.
DataFindAPI
wrong
```
from gwdatafind import DataFindAPI
```
correct
```
import gwdatafind
```
DataFindAPI was removed in v2.0; use the connect function instead.

Quickstart

This example connects to the GWDataFind server, finds frame URLs for LIGO Hanford around the first GW detection, and lists available data types. No authentication required for public data.

import os
import gwdatafind

# Set token if available (optional for public data)
os.environ.get('IGWN_AUTH_TOKEN', '')

# Connect to the default LIGO/Virgo archive
connection = gwdatafind.connect()

# Find all frames for a specific observatory and GPS time
frames = connection.find_frames('H1', 1126257414, 1126257416)
for frame in frames:
    print(frame.url)

# Find specific types of data (e.g., trend data)
trends = connection.find_types('H1', 'H1_TREND')
print(trends)