GW Open Science Data Archive client

0.8.2 verified Fri May 01 auth: no python

A python interface to the Gravitational Wave Open Science Center (GWOSC) data archive. Version 0.8.2 requires Python >=3.10. Regular releases, roughly quarterly.

pip install gwosc

Common errors

error ImportError: cannot import name 'dataset' from 'gwosc' ↓

cause dataset is not a top-level export; it lives in the datasets submodule.

fix

from gwosc.datasets import dataset

error AttributeError: module 'gwosc' has no attribute 'api' ↓

cause The package name is 'gwosc', but the api module may not be imported on Python 3.10+ due to namespace changes.

fix

pip install --upgrade gwosc to get latest version that ensures submodules are importable.

error ValueError: Unknown dataset ... ↓

cause Passing a dataset name instead of a URL to API functions.

fix

Use the URL returned by dataset() or construct it: f'https://www.gw-openscience.org/api/v2/events/{name}/'

error HTTPError: 404 Client Error: Not Found ↓

cause Using old API endpoint (e.g., /archive/ instead of /api/v2/).

fix

Update URL to use the /api/v2/ prefix.

Warnings

breaking The API endpoint changed from /archive/ to /api/v2/. Old code using direct URL construction will break. ↓

fix Use the provided functions like fetch_json with the new base URL, or update URLs to https://www.gw-openscience.org/api/v2/.

deprecated The function `datasets.find_datasets` is deprecated in favor of `dataset()`. ↓

fix Replace `from gwosc.datasets import find_datasets` with `from gwosc.datasets import dataset` and call `dataset()`.

gotcha The `dataset()` function returns a list of URLs, not dataset names. Many users expect names and try to use them directly in API calls. ↓

fix Use `datasets = dataset(); [d['dataset'] for d in datasets]` to extract names if needed.

gotcha Running `fetch_json` without a proper user-agent may result in HTTP 403 errors from the GWOSC servers. ↓

fix Set the `User-Agent` header: `fetch_json(url, headers={'User-Agent': 'MyApp/1.0'})`.

Imports

GWOSC
wrong
```
import gwosc.GWOSC
```
correct
```
from gwosc.api import GWOSC
```
GWOSC is a class in the api module, not a submodule.

fetch_json

wrong

from gwosc import fetch_json

correct

from gwosc.api import fetch_json

fetch_json is not exposed at package level.

dataset

wrong

from gwosc import dataset

correct

from gwosc.datasets import dataset

dataset is a function in the datasets module.

run_query
wrong
```
from gwosc import run_query
```
correct
```
from gwosc.api import run_query
```
run_query is in the api module, not top-level.

Event

wrong

from gwosc import Event

correct

from gwosc.datasets import Event

Event is a class in the datasets module.

Quickstart

Basic usage: list datasets and fetch event metadata from the API.

from gwosc.datasets import dataset
from gwosc.api import fetch_json

# List datasets
datasets = dataset()
print(datasets)

# Query for event details
json_data = fetch_json('https://www.gw-openscience.org/api/v2/events/GW150914/')
print(json_data)