Gravitational Wave Open Science Center

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
× WARNING! The following API nodes are deprecated and will be removed entirely on May 2022. If you are using any of them, consider moving to one of the alternatives below.
  • /catalog_archive/json: Returns all the catalogs along with a description and the version number.
  • /catalog/<cat_name>/filelist/: Returns all events in the catalog with associated parameters and a list of download links for data files.
  • /catalog/<cat_name>/json/: Returns all events in the catalog with associated parameters.
  • /timelinejson/<dataset>/<timelines>/<GPS_start>/<duration>/[<L>/]
  • /archive/<dataset>/json/: Return strain download links for a dataset

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.

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

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.
  • GPS: The GPS time of detection in seconds.
  • catalog.shortName: The release that this parameter estimation belongs to.
  • chi_eff: Spin parameter indicating the effective inspiral spin.
  • 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) \).
  • 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.
  • final_mass_source: The mass of the remnant compact object after merger, assuming a binary black hole model, and measured in the source frame.
  • total_mass_source: The total mass of the binary as measured in the source frame.
  • 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 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.
  • redshift: The calculated redshift.
  • 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 PE sets for different pipelines. The keys of the dictionary are the name of each pipeline. Each PE set contains some of the previous parameter keys plus the following:
    • data_url:
    • date_added: The date this pipeline was added to the database.
    • geocent_time: The geo-centric time of the event.
    • is_preferred: A boolean true/false that marks if this pipeline is the preferred one for the parameter estimations.

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

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
    },
    ...
  }
}

/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
    }
  }
}