The Swift TOO API provides a method of interacting with the Neil Gehrels Swift Observatory (hereafter Swift) Target of Opportunity (TOO) request system, without the need to fill out a HTML form, as has been traditional. The motivation for the API is to face head on the challenges of the new era of transient astronomy coming with Vera C. Rubin Observatory and others.
Previously TOO requests typically were submitted by hand, with a human filling out an HTML form. However, this has obvious limitations. Firstly, in the case where a fast reaction is needed by Swift, the act of putting a human-in-the-loop adds latency to the TOO process. For this reason in the past few years, the Swift Science Operations Team (SOT) has implemented automated TOO submission process, which allows automatic submission of TOOs based on external triggers, for example Fermi/LAT GRBs, well localized FRB detections, LIGO GW NS-NS merger events and Neutrino detections.
Notably, these TOOs have been submitted based on external triggers meeting specified requirements, rather than a human deciding that they are of interest, and therefore present a more systematic approach to submitting observations requests.
This is the specific capability that the TOO API brings to the community of Swift users, opening new possibilities in how TOOs are handled.
In addition the Swift TOO API performs several other useful tasks, related to TOO tasks.
It provides an interface that allows both long and short term visibility of targets to be predicted. This enables the accurate coordination of observations, as well as checking if a target is visible to Swift before submitting a TOO. Long term visibility calculations calculate a target's visibility on an essentially day-to-day basis, considering Swift's Sun, Moon and Orbit Pole constraints. The short term visibility calculates (for a maximum 20 day period), high fidelity visibility windows, including the orbital Earth occulations. Using this you can predict exactly when a target may be observed by Swift to minute resolution.
Finally the TOO API provides the ability to query which targets Swift has previously observed. Utilizing this, you are able to request lists of observations, filtered by coordinate, time period, target ID or Observation ID, so you can not only see what Swift has already observed, you can also track the progress of your TOO request.
Currently in order to use the API, we have developed a Python module,
swift_too, which is distributed as part of the
swifttools (install using pip) package, which also include thes
xrt_prods module, for analyzing Swift X-ray Telescope data detailed here.
This Python version of the API should be considered the reference implementation of the Swift TOO API, however, other implementations are possible, as the API communicates using a simple JSON Web Token format that makes it easy to implement submissions utilizing other languages.
We strongly suggest that to get started, people should review the example usages of the API given under the 'Example Notebooks' heading, and downloadable as Jupyter Notebooks.