Low-level API¶

The gwosc.api package provides low-level interface functions that handle direct requests to the GWOSC host. Inside the gwosc.api package there are two modules, each one dealing with the 2 available versions of the API.

gwosc.api.v1: Legacy API functions for backward compatibility
gwosc.api.v2: Newer API functions with improved functionality

Given the sharp increase of detections in recent runs, we rebuilt our public API to cope with increased response length, and high-frequency requests. API v2 introduces pagination and throttling features for all resources to guarantee scalability, and a smoother experience for developers and end users. To learn more, visit https://gwosc.org/api/.

Backward Compatibility

For backward compatibility, the main gwosc.api module imports all functions from the v1 API. This means existing code that imports from gwosc.api will continue to work without changes.

gwosc.api provides the low-level interface functions that handle direct requests to the GWOSC host.

gwosc.api.DEFAULT_URL = 'https://gwosc.org'¶: The default GWOSC host URL

API v2 (Current)

gwosc.api.v2.fetch_allowed_params(host='https://gwosc.org', session=None)¶

Return a list with the “default parameters”.

These parameters are almost always estimated for event detections. Use the parameter names (strings) to filter events in the fetch_event_versions() select argument.

Parameters:¶

host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.

Returns:¶

params – A list of parameter names.

Return type:¶

list[str]

gwosc.api.v2.fetch_catalogs(host='https://gwosc.org', session=None, pagesize=None)¶

Returns a list with all catalogs.

Parameters:¶

host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – A list of catalogs.

Return type:¶

iterable[dict]

gwosc.api.v2.fetch_event_strain_data(event, detector=None, version=None, catalog=None, sample_rate=None, duration=None, format='hdf5', host='https://gwosc.org', session=None, pagesize=None)¶

Return strain file objects from single-event releases.

Parameters:¶

event¶: the ID of an event, e.g. 'GW150914'.
detector=None¶: the prefix of the GW detector, e.g. 'L1'.
version=None¶: the version number of the requested event.
catalog=None¶: the catalog in which the requested event appears.
sample_rate=None¶: the sample rate of the strain file data, either 4096 or 16384 [Hz].
duration=None¶: the duration of the strain file, 32 or 4096 [s].
format='hdf5'¶: the file format of the strain file. One of 'hdf', 'gwf', 'txt'.
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – An iterable of strain file dictionaries.

Return type:¶

iterable[dict]

gwosc.api.v2.fetch_event_version(event, catalog=None, version=None, host='https://gwosc.org', session=None)¶

Returns an event.

Parameters:¶

event¶: the name of the event.
catalog=None¶: name of catalogue that hosts this event.
version=None¶: the version of the data release to use, defaults to the highest available version.
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.

Returns:¶

data – A dictionary with the event detail.

Return type:¶

dict

gwosc.api.v2.fetch_event_versions(name=None, segment=None, catalogs=None, select=None, host='https://gwosc.org', session=None, pagesize=None)¶

Returns an event.

Parameters:¶

name=None¶: a full or partial name for an event.
segment=None¶: a gps time tuple (start, end) to restrict the search.
catalogs=None¶: a single catalog name or a list of catalog names.
select=None¶: a dictionary with query parameters, e.g. {‘min-p-astro’: 0.5}.
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – A list of event version dictionaries.

Return type:¶

iterable[dict]

gwosc.api.v2.fetch_json(url, session=None, **kwargs)¶

Fetch JSON data from a remote URL.

Parameters:¶

url¶: the remote URL to fetch
session=None¶: the session to use for the request. If None, falls back to direct requests.get()
**kwargs¶: other keyword arguments are passed directly to requests.get() or requests.Session.get()

Returns:¶

data – the data fetched from url as parsed by requests.Response.json()

Return type:¶

dict or list

See also

json.loads: for details of the JSON parsing

gwosc.api.v2.fetch_run(run, host='https://gwosc.org', session=None)¶

Return a run detail.

Parameters:¶

run¶: the name of the run, e.g. O1.
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.

Returns:¶

data – A dictionary with the run detail.

Return type:¶

dict

gwosc.api.v2.fetch_run_strain_files(run=None, detector=None, start=None, end=None, sample_rate=None, host='https://gwosc.org', session=None, pagesize=None)¶

Return strain file objects from bulk-data releases.

Parameters:¶

run=None¶: the ID of a run, e.g. 'O1'.
detector=None¶: the prefix of the GW detector, e.g. 'L1'.
start=None¶: the GPS start of the desired interval.
end=None¶: the GPS end of the desired interval.
sample_rate=None¶: the sample rate of the strain file data, either 4096 or 16384 [Hz].
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – An iterable of strain file dictionaries.

Return type:¶

iterable[dict]

gwosc.api.v2.fetch_runs(host='https://gwosc.org', session=None, pagesize=None)¶

Return a list of all past runs.

Parameters:¶

host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – An iterable of runs.

Return type:¶

iterable[dict]

gwosc.api.v2.fetch_segments(flag, start, end, host='https://gwosc.org', session=None, pagesize=None)¶

Return segment dictionaries in the (start, end) GPS time interval.

Parameters:¶

flag¶: name of flag, e.g. 'H1_DATA'.
start¶: the GPS start time of your query.
end¶: the GPS end time of your query.
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org.
session=None¶: the session to use for HTTP requests.
pagesize=None¶: the number of results per page.

Returns:¶

data – An iterable of segment dictionaries.

Return type:¶

iterable[dict]

gwosc.api.v2.produce_fetched_objects(url, session=None)¶

API v1 (Legacy)

gwosc.api.v1.fetch_allevents_json(full=False, host='https://gwosc.org')¶

Returns the JSON metadata for the allevents API

Parameters:¶

host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org

Returns:¶

data – the JSON data retrieved from GWOSC and returned by requests.Response.json()

Return type:¶

dict or list

gwosc.api.v1.fetch_allowed_params_json(host='https://gwosc.org')¶

gwosc.api.v1.fetch_catalog_json(catalog, host='https://gwosc.org')¶

Returns the JSON metadata for the given catalogue

Parameters:¶

catalog¶: the name of the event catalog, e.g. GWTC-1-confident
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org

Returns:¶

data – the JSON data retrieved from GWOSC and returnend by requests.Response.json()

Return type:¶

dict or list

gwosc.api.v1.fetch_cataloglist_json(host='https://gwosc.org')¶

Returns the JSON metadata for the catalogue list.

Parameters:¶

host='https://gwosc.org'¶: the URL of the GWOSC host to query

Returns:¶

data – the JSON data retrieved from GWOSC and returned by requests.Response.json()

Return type:¶

dict or list

gwosc.api.v1.fetch_dataset_json(gpsstart, gpsend, host='https://gwosc.org')¶

Returns the JSON metadata for all datasets matching the GPS interval

Parameters:¶

gpsstart¶: the GPS start of the desired interval
gpsend¶: the GPS end of the desired interval
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org

Returns:¶

data – the JSON data retrieved from GWOSC and returned by json.loads

Return type:¶

dict or list

gwosc.api.v1.fetch_event_json(event, catalog=None, version=None, host='https://gwosc.org')¶

Returns the JSON metadata for the given event.

By default, this function queries across all catalogs and all data-release versions, returning the highest available version, unless the version and/or catalog keywords are specified.

Parameters:¶

event¶: the name of the event to query
catalog=None¶: name of catalogue that hosts this event
version=None¶: restrict query to a given data-release version
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org

Returns:¶

data – the JSON data retrieved from GWOSC and returned by json.loads

Return type:¶

dict or list

gwosc.api.v1.fetch_filtered_events_json(select, host='https://gwosc.org')¶

Return the JSON metadata for the events constrained by select

Parameters:¶

select¶: a list of range constrains for the events. All ranges should have inclusive ends (<= and >= operators).
host='https://gwosc.org'¶: the URL of the GWOSC host to query, defaults to https://gwosc.org

Returns:¶

data – the JSON data retrieved from GWOSC and returnend by requests.Response.json()

Return type:¶

dict or list

Example

>>> fetch_filtered_events_json(
...     select=[
...         "mass-1-source <= 5",
...         "mass-2-source =< 10",
...         "10 <= luminosity-distance <= 100",
...     ]
... )

gwosc.api.v1.fetch_json(url, **kwargs)¶

Fetch JSON data from a remote URL

Parameters:¶

url¶: the remote URL to fetch
kwargs : dict¶: other keyword arguments are passed directly to requests.get()

Returns:¶

data – the data fetched from url as parsed by requests.Response.json()

Return type:¶

dict or list