gwdatafind

library2.1.1pypypi✓ verified 84d ago

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.

data http-networking

pip install gwdatafind

package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · GWDATAFIND

gwdatafind

datapythonv2.1.1

Install

3.4s avg

Import

1273ms

Disk

38MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.348s · 39.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.4s · import 1.198s · 40MB

38MB installed

● package 38MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect

✓ import gwdatafind

✗ from gwdatafind import connect

Since v2.0, connect is a function in the top-level namespace. Using old import will raise AttributeError.

DataFindAPI

✓ import gwdatafind

✗ from gwdatafind import DataFindAPI

DataFindAPI was removed in v2.0; use the connect function instead.

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)

Debug

Known issues

breakingThe `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()`.

affects: >=2.0.0

gotchaThe `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()`.

affects: all

deprecatedThe `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)`.

affects: >=2.1.0

gotchaDefault 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)`.

affects: all

Errors

Common errors & fixes

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

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

fix

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

gwdatafind.exceptions.AuthenticationError: No authentication token found

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`.

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

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=`.

Upgrade

Version history

2.1.1latest on PyPI · released Oct 31, 2025

Audit

Dependencies

ligo-auth-tokensoptionalAuthentication for protected data endpoints

igwn-auth-utilsoptionalAlternative authentication using IGWN SciToken

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/gwdatafind/ ↗

homepagehttps://gwdatafind.readthedocs.io ↗

docshttps://gwdatafind.readthedocs.io ↗