GWOSC Public API Documentation

The Gravitational Wave Open Science Center offers a public API, mostly in the form of JSON format that provides data on timeline segments, catalogs, list of datasets with and without bulk strain data, and single datasets.

If you are working in a Python project, we recommend installing the gwosc Python client to interact with our API. 

pip install gwosc

Summary

Timeline segments

Archive

Event Portal API

The Event Portal API provides data on catalogs, events and list of events. For more information, read the Event Portal documentation page.

Interact with the API

Below are some examples to download json pages using commonly used web tools.

The json information can be accessed programatically from python, from the command line using curl, from inside the web browser as javascript client code, or directly using your web browser.

In these three examples we show how to download the contents at https://gwosc.org/timeline/segments/all/O1/1126051217/200000/ using curl, the python library requests, and the fetch function for javascript.

The same code can be applied to any other API node by replacing the example path with any of the URLs described in this documentation. 


import requests
r = requests.get(
  "https://gwosc.org/timeline/segments/all/O1/1126051217/200000/"
  )
r.json()

curl -o response.json https://gwosc.org/timeline/segments/all/O1/1126051217/200000/

var url = new URL("https://gwosc.org/timeline/segments/all/O1/1126051217/200000/");
fetch(url)
  .then(response => response.json())
  .then(function(response) {
    // work with response
    console.log(response);
  })
  .catch(function (err) {
    alert(err.message);
  });

For an example on how to pass GET parameters, see /eventapi/jsonfull/query/show.

Timeline Segments

/timeline/segments/all/<dataset>/<GPS_start>/<duration>/

Return all the timelines for a given dataset, along with the intervals of time (segments) in which the data for each timeline pass the validation test.

The list of validated segments returned will be constrained to the time interval [GPS_start, GPS_start + duration]

To find all available datasets, see /archive/<GPS_start>/<GPS_end>/json/

To find the GPS time of a specific UTC time, you can use the GPS conversion tool.

Example:

Return all the timelines for the O1 run and its validated segments between times 1,126,051,217 and 1,126,251,217.

/timeline/segments/all/O1/1126051217/200000/

Returns:

(truncated response)

{
  "L1_NO_CW_HW_INJ": {
    "dataset": "O1",
    "start": 1126051217,
    "id": "L1_NO_CW_HW_INJ",
    "end": 1126251217,
    "segments": [[1126051217, 1126151760]]
  },
  ...
  "H1_DATA": {
    "dataset": "O1",
    "start": 1126051217,
    "id": "H1_DATA",
    "end": 1126251217,
    "segments": [
      [1126073529, 1126114861], [1126121462, 1126123267], ...[1126155799, 1126166028]
      ]
  }
}

/timeline/segments/json/<dataset>/<timeline>/<GPS_start>/<duration>/

Return the intervals of time (segments) in which the data for a particular dataset timeline pass the validation test.

The list of validated segments returned will be constrained to the time interval [GPS_start, GPS_start + duration]

To find all available datasets, see /archive/<GPS_start>/<GPS_end>/json/

To find the list of available timelines for a dataset, see /timeline/segments/all/<dataset>/<GPS_start>/<duration>/.

To find the GPS time of a specific UTC time, you can use the GPS conversion tool.

Example:

/timeline/segments/json/O1/L1_NO_CW_HW_INJ/1126051217/2000000/

Returns:

{
  "dataset": "O1",
  "start": 1126051217,
  "id": "L1_NO_CW_HW_INJ",
  "end": 1128051217,
  "segments": [
      [1126051217, 1126151760], [1126976280, 1128051217]
    ]
}

Archive

/archive/all/json/

Return information for all events and runs.

Example:

/archive/all/json/

Returns:

(truncated response)

{
  "events": {
    "151116-v1": {
      "detectors": [],
      "UTCtime": "2015-11-16T22:41:48.700000",
      "GPStime": 1131748925.7,
      "DQbits": 8,
      "INJbits": 8,
      "frametype": ""
    },
    ...
    "GW150914-v3": {
      "detectors": [],
      "UTCtime": "2015-09-14T09:50:45.400000",
      "GPStime": 1126259462.4,
      "DQbits": 8,
      "INJbits": 8,
      "frametype": ""
    }
  },
  ...
  "runs": {
    "O1": {
      "detectors": [
        "H1",
        "L1"
      ],
      "UTCstart": "2015-09-12T00:00:00",
      "GPSstart": 1126051217,
      "UTCend": "2016-01-19T16:00:00",
      "GPSend": 1137254417,
      "DQbits": 2,
      "INJbits": 1,
      "frametype": "%s_HOFT_C02"
    },
    ...
  }
}

/archive/<GPS_start>/<GPS_end>/json/

Return information for all events and runs in the given GPS interval time [GPS_start, GPS_end].

To find the GPS time of a specific UTC time, you can use the GPS conversion tool.

Example:

/archive/1126051217/1137254417/json/

Returns:

(truncated response)

{
  "events": {
    "151116-v1": {
      "detectors": [],
      "UTCtime": "2015-11-16T22:41:48.700000",
      "GPStime": 1131748925.7,
      "DQbits": 8,
      "INJbits": 8,
      "frametype": ""
    },
    ...
    "GW150914-v3": {
      "detectors": [],
      "UTCtime": "2015-09-14T09:50:45.400000",
      "GPStime": 1126259462.4,
      "DQbits": 8,
      "INJbits": 8,
      "frametype": ""
    }
  },
  "runs": {
    "O1": {
      "detectors": [
        "H1",
        "L1"
      ],
      "UTCstart": "2015-09-12T00:00:00",
      "GPSstart": 1126051217,
      "UTCend": "2016-01-19T16:00:00",
      "GPSend": 1137254417,
      "DQbits": 2,
      "INJbits": 1,
      "frametype": "%s_HOFT_C02"
    }
    ...
  }
}

/archive/links/<dataset>/<detector>/<GPS_start>/<GPS_end>/json/

Returns information about each of the strain files in a dataset for a given detector and GPS time interval.

To find all available datasets, see /archive/<GPS_start>/<GPS_end>/json/

The <detector> string should be one of "H1", "L1", "V1", "G1" or "K1".

To find the GPS time of a specific UTC time, you can use the GPS conversion tool.

Example:

/archive/links/O1/L1/1126224017/1126310417/json/

Returns:

(truncated response)

{
  "dataset": "O1",
  "GPSstart": 1126224017,
  "GPSend": 1126310417,
  "strain": [
    {
      "GPSstart": 1126232064,
      "UTCstart": "2015-09-14T02:14:07",
      "detector": "L1",
      "sampling_rate": 4096,
      "duration": 4096,
      "format": "hdf5",
      "url": "https://www...hdf5",
      "min_strain": -2.71368506428908e-18,
      "max_strain": 4.68890735544809e-19,
      "mean_strain": -1.07118201346881e-18,
      "stdev_strain": 3.094487852454e-19,
      "duty_cycle": 51.46484375,
      "BLRMS200": 1.83744275213856e-23,
      "BLRMS1000": 1.08227364482578e-21,
      "BNS": 56.846848301425
    },
    ...
  ]
}

/archive/dataset/<dataset>/json/

Return information about the dataset, including bitmask information.

To find all available datasets, see /archive/<GPS_start>/<GPS_end>/json/

Example:

/archive/dataset/GW150914-v1/json/

Returns:

(truncated response)

{
  "shortName": "GW150914-v1",
  "version": "1",
  "release": "1",
  "description": "https://doi.org/10.7935/K5MW2F23    The 4 kHz files...",
  "duration": 4096,
  "npoints": 16777216,
  "npointsQI": 4096,
  "dqbits": 7,
  "injbits": 5,
  "bits": [
    {
      "mask": 1,
      "bit": 0,
      "shortName": "NO_CBC_HW_INJ",
      "description": "no cbc injections"
    },
    ...
  ]
}

Event Portal

All of the JSON responses in the Event Portal contain most of the parameters described below. See also parameter names from PE summary.

The events key has all events matching the search criteria. Each key inside events is the name of an event followed by the version number prefixed with -v. So for example the 3rd version for GW150914 will appear under the GW150914-v3 key.

Each version will provide parameters for the event. The parameters that contain error estimation will have a corresponding _lower and _upper counterparts for the lower and upper limits of the 90% confidence error bar. Some parameters also contain a _unit counterpart that denotes the physical unit in which the parameter is measured.

For example:

  "chirp_mass": 5.12,
  "chirp_mass_lower": 1.0,
  "chirp_mass_unit": "M_sun",
  "chirp_mass_upper": 0.5,

translates to \( {\cal{M}} = {5.12}^{+0.5}_{-1.0} M_{\odot} \).

JSON Response Keys

  • version: The revision number of this entry for the event.
  • gracedb_id: The corresponding trigger ID in the GraceDB database.
  • GPS: The GPS merger time at the geocenter in seconds.
  • catalog.shortName: The release that this parameter estimation belongs to.
  • chi_eff: The effective inspiral spin parameter.
  • chirp_mass: The detector-frame chirp mass of the binary defined by \( {\cal{M}} = \frac{(M_1 M_2)^{3/5}}{(M_1 + M_2)^{1/5}} \) in units of solar mass.
  • chirp_mass_source: The source-frame chirp mass of the binary as measured in the source frame \( {\cal{M}}_{\circ}={\cal M}(1 + z) \) in units of solar mass.
  • commonName: The name of the event as used in the literature, e.g. GW150914.
  • far: The False Alarm Rate of the detection in events per year.
  • p_astro: The probability of astronomical origin, assuming a compact binary.
  • final_mass_source: The source-frame remnant mass estimated using the spins evolved to the ISCO frequency in units of solar mass.
  • total_mass_source: The source-frame combined mass of the primary and secondary masses in units of solar mass.
  • jsonurl: The URL for a json detail of the event (see /eventapi/json/event/<event_name>/).
  • luminosity_distance: The luminosity distance to the source in Mpc.
  • mass_1_source: The source mass of the heavier object in the binary in units of solar mass.
  • mass_2_source: The source mass of the lighter object in the binary in units of solar mass.
  • network_matched_filter_snr: The matched filter signal to noise ratio in the gravitational wave detector network.
  • redshift: The redshift depending on specified cosmology.
  • reference: The URL to the relevant documentation page.
  • strain: A list of strain files associated with this version of the event. The options differ in format, sampling rate, duration and detector.
    • GPSstart: The GPS time of the first sample in the file.
    • detector: A two-letter string denoting the detector (H1, L1, V1, etc).
    • duration: One of 32s, 4096s.
    • format: One of gwf, g-zipped txt, and hdf5.
    • sampling_rate: One of 4096 Hz or 16384 Hz.
    • url: Contains the URL to download the strain file.
  • parameters: Contains a dictionary of parameter sets for different analyses. The keys of the dictionary are the name of each analysis. Each parameter set contains a list of parameters specific to the analysis pipeline. The following keys are common to all pipelines:
    • data_url: URL to download source file for this pipeline.
    • date_added: The date this pipeline was added to the database.
    • is_preferred: A boolean true/false that marks if this pipeline is the preferred one for the parameter estimations.
    • pipeline_type: the string pe for parameter estimation pipelines or search for search pipelines.

/eventapi/json/

Return a dictionary with all the catalogs, a description and url to its release page.

Example:

/eventapi/json/

Returns:

(truncated response)

{
  "GWTC-1-confident": {
    "description": "Confident detections...",
    "url": "https://www.../GWTC-1-confident"
  },
  ...
  "O3_IMBH_marginal": {
    "description": "O3 IMBH marginal candidates...",
    "url": "https://www.../O3_IMBH_marginal"
  }
}

/eventapi/jsonfull/allevents/

Return the whole list of events and their parameters with optional bulk strain data release download links.

Additional output formats are available replacing jsonfull by json, ascii or csv in the url.

i.e. /eventapi/ascii/allevents/, /eventapi/csv/allevents/.

Example:

/eventapi/jsonfull/allevents/

Returns:

(truncated response)

{
  "events": {
    "151008-v1": {
      "GPS": 1128348574.5,
      "catalog.shortName": "GWTC-1-marginal",
      "chi_eff": null,
      "chi_eff_lower": null,
      "chi_eff_unit": null,
      "chi_eff_upper": null,
      "chirp_mass": 5.12,
      "chirp_mass_lower": null,
      "chirp_mass_source": null,
      "chirp_mass_source_lower": null,
      "chirp_mass_source_unit": null,
      "chirp_mass_source_upper": null,
      "chirp_mass_unit": "M_sun",
      "chirp_mass_upper": null,
      "commonName": "151008",
      "far": 10.17,
      "far_lower": null,
      "far_unit": "yr^-1",
      "far_upper": null,
      "final_mass_source": null,
      "final_mass_source_lower": null,
      "final_mass_source_unit": null,
      "final_mass_source_upper": null,
      "jsonurl": "https://www.../151008/v1",
      "luminosity_distance": null,
      "luminosity_distance_lower": null,
      "luminosity_distance_unit": null,
      "luminosity_distance_upper": null,
      "mass_1_source": null,
      "mass_1_source_lower": null,
      "mass_1_source_unit": null,
      "mass_1_source_upper": null,
      "mass_2_source": null,
      "mass_2_source_lower": null,
      "mass_2_source_unit": null,
      "mass_2_source_upper": null,
      "network_matched_filter_snr": 8.8,
      "network_matched_filter_snr_lower": null,
      "network_matched_filter_snr_unit": "",
      "network_matched_filter_snr_upper": null,
      "redshift": null,
      "redshift_lower": null,
      "redshift_unit": null,
      "redshift_upper": null,
      "reference": "https://doi.org/10.7935/82H3-HH23",
      "strain": [
        {
          "GPSstart": 1128348559,
          "detector": "H1",
          "duration": 32,
          "format": "gwf",
          "sampling_rate": 16384,
          "url": "https://...gwf"
        },
        ...
        {
          "GPSstart": 1128346527,
          "detector": "L1",
          "duration": 4096,
          "format": "txt",
          "sampling_rate": 4096,
          "url": "https://...txt.gz"
        }
      ],
      "total_mass_source": null,
      "total_mass_source_lower": null,
      "total_mass_source_unit": null,
      "total_mass_source_upper": null,
      "version": 1
    },
    ...
  }
}

/eventapi/jsonfull/GWTC/

Returns the full list of events in the cumulative Grativational Wave Transient Catalog with optional bulk strain data release download links.

Additional output formats are available replacing json by json, ascii or csv in the url.

i.e. /eventapi/ascii/allevents/, /eventapi/csv/allevents/.

Example:

/eventapi/jsonfull/GWTC/

Returns:

(truncated response)

{
  "events": {
    "GW150914-v3": {
      "GPS": 1126259462.4,
      ...
      "strain": [
      {
        "GPSstart": 1126259447,
        "detector": "H1",
        "duration": 32,
        "format": "gwf",
        "sampling_rate": 16384,
        "url": "https://...gwf"
      },
      ...
      ],
      "version": 3
    },
    ...
  }
}

/eventapi/jsonfull/<cat_name>/

Returns the full list of events in the cat_name catalog with optional bulk strain data release download links.

Additional output formats are available replacing json by json, ascii or csv in the url.

i.e. /eventapi/ascii/allevents/, /eventapi/csv/allevents/.

To find a list of all available catalogs, see /eventapi/json/

Example:

/eventapi/jsonfull/GWTC-1-marginal/

Returns:

(truncated response)

{
  "events": {
    "151008-v1": {
      "GPS": 1128348574.5,
      "strain": [
      {
        "GPSstart": 1128348559,
        "detector": "H1",
        "duration": 32,
        "format": "gwf",
        "sampling_rate": 16384,
        "url": "https://...gwf"
      },
      ...
      ],
      ...
      "version": 1
    },
    ...
  }
}

/eventapi/jsonfull/query/show

Return all events that satisfy the criteria set in the GET parameters.

Additional output formats are available replacing jsonfull by json, ascii or csv in the url.

i.e. /eventapi/ascii/allevents/, /eventapi/csv/allevents/.

Prepend the GET parameters with min- and max- to delimit the search range of that parameter.

Append GET parameters with &.

GET Parameters

name-contains: A string that the event (or an alias) may contain.

release: A comma-separated list of catalogs.

gps-time: The GPS time interval enclosing the events.

lastver: Boolean to show (=true) or hide (=false) previous versions of the events.

mass-1-source: The source mass of the heavier compact object in the merger, as measured in the source frame.

mass-2-source: The source mass of the lighter compact object in the merger, as measured in the source frame.

network-matched-filter-snr: The network Signal to Noise Ratio of the Matched Filtering.

luminosity-distance: The luminosity distance to the source.

chi-eff: Spin parameter indicating the effective inspiral spin.

total-mass-source: The total mass of the binary as measured in the source frame.

chirp-mass: The chirp mass of the binary defined by \( {\cal M}= \frac{(M_1 M_2)^{3/5}}{(M_1 + M_2)^{1/5}} \).

chirp-mass-source: The chirp mass of the binary as measured in the source frame \( {\cal M}_{\circ}={\cal M}(1 + z) \).

redshift: The calculated redshift.

far: The False Alarm Rate of the detection in events per year.

p-astro: The probability of astronomical origin, assuming a compact binary.

final-mass-source: The mass of the remnant compact object after merger, assuming a binary black hole model, and measured in the source frame.

Example:

/eventapi/jsonfull/query/show?min-mass-1-source=2&max-mass-1-source=10&max-chi-eff=0.5

Returns:

(truncated response)

{
  "events": {
    "GW190425-v2": {
      "GPS": 1240215503.0,
      ...
      "version": 2
    },
    ...
  }
}

import requests
payload = {
  "min-mass-1-source": 2,
  "max-mass-1-source": 10,
  "max-chi-eff": 0.5,
}
r = requests.get(
  "https://gwosc.org/eventapi/jsonfull/query/show",
  params=payload,
  )
r.json()
curl -o response.json \
"https://gwosc.org/eventapi/jsonfull/query/show\
?min-mass-1-source=2&max-mass-1-source=10&max-chi-eff=0.5"
var search_params = {
  "min-mass-1-source" : 2,
  "max-mass-1-source" : 10,
  "max-chi-eff" : 0.5
};
var url = new URL("https://gwosc.org/eventapi/jsonfull/query/show");
for (let key in search_params) { url.searchParams.append(key, search_params[key]); }
fetch(url)
  .then(function(response) {
      segments = response.json();
  })
  .catch(function(err) {
      alert(err.message);
  });

/eventapi/json/<cat_name>/<event_name>/[v<version>/] /eventapi/json/event/<event_name>/[v<version>/]

Return a detail json for a single event event_name.

If v<version> is ommited, it will automatically return the latest version.

If <cat_name> is provided, it will return the event version corresponding to cat_name.

If both v<version> and <cat_name> are provided but are incompatible, it will return a 404 page.

To find a list of all available catalogs, see /eventapi/json/

To find a list of all available v<event_name> and v<version>, see /eventapi/json/allevents/.

Example:

/eventapi/json/O1_O2-Preliminary/GW150914/v1/

Returns:

(truncated response)

{
  "events": {
    "GW150914-v1": {
      "GPS": 1126259462.4,
      "catalog.shortName": "O1_O2-Preliminary",
      "chi_eff": null,
      "chi_eff_lower": null,
      "chi_eff_unit": null,
      "chi_eff_upper": null,
      "chirp_mass": null,
      "chirp_mass_lower": null,
      "chirp_mass_source": null,
      "chirp_mass_source_lower": null,
      "chirp_mass_source_unit": null,
      "chirp_mass_source_upper": null,
      "chirp_mass_unit": null,
      "chirp_mass_upper": null,
      "commonName": "GW150914",
      "far": null,
      "far_lower": null,
      "far_unit": null,
      "far_upper": null,
      "final_mass_source": null,
      "final_mass_source_lower": null,
      "final_mass_source_unit": null,
      "final_mass_source_upper": null,
      "jsonurl": "https://...",
      "luminosity_distance": null,
      "luminosity_distance_lower": null,
      "luminosity_distance_unit": null,
      "luminosity_distance_upper": null,
      "mass_1_source": null,
      "mass_1_source_lower": null,
      "mass_1_source_unit": null,
      "mass_1_source_upper": null,
      "mass_2_source": null,
      "mass_2_source_lower": null,
      "mass_2_source_unit": null,
      "mass_2_source_upper": null,
      "network_matched_filter_snr": null,
      "network_matched_filter_snr_lower": null,
      "network_matched_filter_snr_unit": null,
      "network_matched_filter_snr_upper": null,
      "parameters": {},
      "redshift": null,
      "redshift_lower": null,
      "redshift_unit": null,
      "redshift_upper": null,
      "reference": "https://doi.org/10.7935/K5MW2F23",
      "strain": [
        {
          "GPSstart": 1126259446,
          "detector": "H1",
          "duration": 32,
          "format": "gwf",
          "sampling_rate": 16384,
          "url": "https://...gwf"
        },
        ...
      ],
      "total_mass_source": null,
      "total_mass_source_lower": null,
      "total_mass_source_unit": null,
      "total_mass_source_upper": null,
      "version": 1
    }
  }
}