GWOSC API

Browse API v2 Version 2 docs Version 1 docs

The second iteration of GWOSC API is now public and ready to use! We recommend upgrading now to take full advantage of the improvements. Scroll down to learn more.

The Gravitational Wave Open Science Center enables programmatic access to data on observation runs, event catalogs, single event detections, parameter estimations, data quality and injection segments, and strain datasets and statistics. This API is intended for researchers, students, educators and the general public to fetch structured data in automated scripts, web apps, or other computer programs.

All API URL endpoints are read-only, this means that all requests to fetch data should use the GET HTTP method. Other HTTP methods will return 40x error responses.

This public API does not require any authentication. All URL endpoints are also authorized for Cross-Origin Resource Sharing (CORS), this means that resources can be fetched from web apps running on web browsers.

The data is available mostly in JSON format, with some endpoints allowing for CSV or ASCII format.

If you need help using this API, you can ask for help in the gravitational wave community forum.

Interacting with the API

For Python projects, we recommend installing the gwosc Python client to fetch data.

pip install gwosc

Below are three examples on how to fetch data from our API in different languages. In all of them, we show how to download the contents at https://gwosc.org/api/v2/runs using curl, the python library requests, and the fetch function for javascript.

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

import requests
r = requests.get(
  "https://gwosc.org/api/v2/runs"
  )
r.json()
curl -o response.json https://gwosc.org/api/v2/runs
var url = new URL("https://gwosc.org/api/v2/runs");
fetch(url)
  .then(response => response.json())
  .then(function(response) {
    // work with response
    console.log(response);
  })
  .catch(function (err) {
    alert(err.message);
  });

API Version 2

With the number of event detections increasing significantly in the recent observation runs, the volume of data accessible through our API expanded accordingly. We recognized that our original API was not suited to the increasingly large responses and the high-frequency requests. In order to address this, we developed GWOSC API version 2, which introduces pagination and throttling for all resources.

These updates ensure that we can scale the service appropriately for the upcoming higher event detection volume that is expected in future observation runs and the associated higher demand on our backend servers. While the data exposed through the API remains the same, the resource contents have been reorganized. Version 2 is optimized for scalability and we hope it provides a smoother experience for both developers and end users. We recommend upgrading to Version 2 to take full advantage of these improvements.

The API provides a downloadable OpenAPI specification (formerly known as Swagger), a standardized format to describe its structure. The OpenAPI specification allows for the creation of auto-generated client libraries in multiple programming languages, and the integration with popular API management tools like Postman, Yaak, etc.

Do not forget to check out the updated documentation or explore the API interactively.

FAQ

How do I migrate from version 1 to version 2?

If you are using the gwosc python client, you just need to upgrade to version 0.8 or higher to start using the new API. For all other cases you can use this quick guide as a reference.

/timeline/segments/all/<dataset>/<GPS_start>/<duration>/
/timeline/segments/json/<dataset>/<timelines>/<GPS_start>/<duration>/
Use these instead:
  • /api/v2/timelines/<timeline>/segments
  • /api/v2/runs/<run>/timelines...
  • /api/v2/event-versions/<event>/timelines...
/archive/all/json/
/archive/<GPS_start>/<GPS_end>/json/
/archive/dataset/<dataset>/json/
Use this instead:
  • /api/v2/runs/<run>/datasets
/archive/links/<dataset>/<detector>/<GPS_start>/<GPS_end>/json/
Use these instead:
  • /api/v2/strain-files
  • /api/v2/runs/<run>/strain-files
  • /api/v2/datasets/<dataset>/strain-files
  • /api/v2/events/<event>/strain-files
  • api/v2/event-versions/<event-version>/strain-files
/eventapi/json
Use this instead:
  • /api/v2/catalogs
/eventapi/jsonfull/allevents/
Use these instead:
  • /api/v2/event-versions
  • /api/v2/event-versions?include-default-parameters
  • /api/v2/event-versions/<event>/parameters
  • api/v2/event-versions/<event>/default-parameters
/eventapi/jsonfull/<cat_name>/
Use these instead:
  • /api/v2/catalogs/<cat_name>/events
  • /api/v2/catalogs/<cat_name>/events?include-default-parameters
/eventapi/jsonfull/query/show
Use this instead:
  • /api/v2/event-versions
/eventapi/json/<cat_name>/<event_name>/[v<version>/]
/eventapi/json/event/<event_name>/[v<version>/]
Use these instead:
  • /api/v2/event-versions/<event_name>-v<version>
  • /api/v2/event-versions/<event_name>@<cat_name>
Is Version 1 still supported? For how long?

Version 1 is now considered deprecated, but it will run alongside Version 2 at least until the release of O4c data.

What's the difference between Version 1 and Version 2 of the API?

The major difference is that version 2 introduces pagination and throttling repeated requests. Version 2 is more oriented to returning serialized objects.

How can I handle pagination in the API?

For requests that span more than the maximum number of objects per page, the API will return only the first page of results. Information related to pagination is stored in the next, previous, results_count, results_per_page, num_pages, and page_number keys at the top level of every results page. Follow the link in the next key until all resources are consumed.

If you are using the gwosc python client, pagination is handled for you automatically.

What's the typical payload size for a response?

Most responses return less than 10KB of data, and some even 1 or 2KB, but some large queries that include all parameter estimations can add up to about 20KB per page.

What do I do if I get a 429 Too Many Requests error?

If you get a 429 response code, it means that you are sending requests that exceed our server capacity to handle. Try adding a 300-500ms delay between requests.

If you are using the gwosc python client, throttling is handled for you automatically.

What should I do if the API returns a 500 Internal Server Error?

A 500 response status code means that our servers are temporarily unavailable. Please try again after connection is restablished.

Is there a community or forum where I can ask questions?

You can ask questions in our gravitational-wave discussion forum ask.igwn.org.

Are there SDKs or client libraries available? What programming languages are supported?

The only official gwosc client for the API is written in Python. However, requests can be made from any program or library that connects to the internet using the HTTP protocol.

Does the API work with GraphQL or other API protocols?

We do not support the GraphQL protocol. The only protocol supported is REST calls with GET HTTP method.

Can I use this API with [my specific platform/tool], e.g., Postman, Zapier?

Yes, you can upload our OpenAPI schema to all platforms that accept importing APIs from such protocol.

When will data from a run become available?

Releases of strain files and associated data are made public after the observation run finishes and the embargo period is over.

Does the API support Webhooks or real-time updates?

No, we do not provide webhooks or real-time updates.