Swift TOO API - Introduction to the API

API Version 2 (swifttools 4.0)

Author: Jamie A. Kennea (Penn State)

Introduction

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

Visibility and Observation checking

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

API usage

The recommended way to use the API is via the Python module swift_too, distributed as part of the swifttools (install using pip) package. The package also includes the xrt_prods module for analyzing Swift X-ray Telescope data, documented here.

In order to install the swifttools module, Python 3.8 or later is required. Using the standard pip command, swifttools can be installed as follows:

% pip install swifttools

Starting with swifttools 4.0, the underlying transport has been redesigned as a modern RESTful API (v2). Requests are sent directly over HTTPS and responses are returned synchronously — there is no longer a job queue to poll. Authentication uses a session cookie obtained by logging in with your username and API key, rather than a shared-secret JWT. The Python module handles all of this transparently, so existing high-level code requires minimal changes.

Direct REST access is also straightforward for other languages, as the API follows standard OpenAPI 3.1 conventions with JSON request and response bodies.

Getting started

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.