The swift_too Python API

Introduction

API Version 2, swifttools version 4.0

The swift_too module (Python package swifttools.swift_too) provides a Python API that gives you almost everything you need to plan and submit Target of Opportunity (TOOs) requests to the Neil Gehrels Swift Observatory (hereafter Swift).

The module is split into the following main classes:

1. SwiftTOO

   This allows Target of Opportunity requests to be constructed and submitted. This includes basic validation before submission, and querying of the status of the request. This is used in the case where you either don't want to have to deal with manual web forms, or you wish to submit a TOO request to Swift based on an automated trigger, for example, if your telescope detects a new transient, and you want Swift to observe it ASAP, you can automate the process of TOO submission using this class. A debug mode is provided to allow you to test the process of submitting a TOO request to completion, without actually submitting a TOO.

2. SwiftObsQuery

   This class allows you to query what observations Swift has already performed. It allows you to search for observations by target ID (a unique identifier for a target) or Observation ID (a unique identifier for a single observation). Also it allows for searches around fixed celestial coordinates, the default inputs for this are J2000 right ascension (RA), declination (dec) and radius in decimal degrees, however we also support astropy's SkyCoord to allow for other coordinate systems to be used for searches, e.g. Galactic Coordinates. In addition you can narrow the search to specific date ranges.

3. SwiftVisQuery

   J2000 RA/dec (given as a SkyCoord or ra and dec properties in decimal degrees). Before submitting a TOO request it's important that you understand if a target can actually be observed by Swift. Targets are typically not observable by Swift if they are closer than 45 degrees to the Sun, 21 degrees and to the Moon. However, targets that are close to +/-69 in declination can exhibit periodic pole constraints also that can cause visibility issues for ~10 day periods. High resolution visibility can be requested, which gives object visiblity at 1 minute timescales, and includes Earth occultation and periods inside the South Atlantic Anomaly. As these are computationally expensive to calculate, we limit high resolution visibliity requests to 20 days in length.

4. SwiftPlanQuery

   Similar to SwiftObsQuery but in this case queries the Swift observing plan, otherwise known as the pre-planned science timeline (PPST). This allows the user to query what was planned to be observed by Swift, and what will be observed in the future. Please note that due to Swift's quick planning turn around, the amount of information on future plans will be limited to the next 1-3 days typically.

5. SwiftUVOTMode

   UVOT modes are typically given as hex modes. This class allows the user to look up the meaning of a given hex code, which is typically a table of UVOT filters associated with that mode, along with any configuration parameters, such as the size of the field of view, whether the data will be taken in event mode, etc.

6. SwiftTOORequests

   This class allows querying of TOO Requests submitted to Swift. By default this will give detail on the most recent 10 TOO requests submitted to Swift. Alternatively, TOOs info can be fetched by year, ID, RA/Dec/Radius, or within a set time period. In addition if the detail parameter is set to True, then this retrieves all information about a TOO request, including non-public information, for TOO requests that you submitted. The class essentially is a container for a number of SwiftTOO_Request objects. In the case where targets are scheduled in the Swift planning calendar, a SwiftCalendar object will be attached which lists the scheduled windows, and shows how much exposure was obtained during those windows.

7. SwiftCalendar

   SwiftCalendar class allows for querying calendar entries for a given TOO. The Calendar shows all planned observations for a TOO, along with an estimate of how much time was actually observed during the calendar window. Note that this is different from the Swift Plan, insofar as the Swift Calendar lists requested observations and can go much farther into the future. However, due to Swift's oversubscription, and other issues, even if an object is in the Calendar, that is not guarantee that Swift will observe it on that day, only that it is in the queue to be observed.

8. SwiftGUANO

   SwiftGUANO provides API access to data obtained by the Gamma-Ray Urgent Archiver for Novel Opportunities (GUANO). GUANO proactively dumps BAT event data, which would otherwise be lost, based on external triggers. These triggers include Fast Radio Bursts, Gamma-Ray Bursts from other missions, Gravitational Wave triggers and Neutrino triggers. SwiftGUANO allows to query these dumps and gives you metadata about the dump.

9. SwiftData

   SwiftData provides an easy interface to download archival or quick-look data from the Swift Science Data Centers in the USA or UK.

10. SwiftResolve

    SwiftResolve provides a simple interface to resolve target names into coordinates, leveraging several name resolvers. This class is also called by other classes when you pass the name parameter instead of giving an ra, dec or skycoord.

The Swift TOO API is built around a client/server model using a modern RESTful interface. Starting with swifttools 4.0, the underlying API has been redesigned as a synchronous REST API (v2), replacing the previous JWT-based queue system. API users are required to register with Swift to submit TOO requests (https://www.swift.psu.edu/toop). Authentication is performed once per session by logging in with a username and password; the returned session cookie is then used for all subsequent requests. Many query endpoints are publicly accessible without authentication; a username of anonymous is assumed when no credentials are provided.

Queries are constructed using the Python classes provided by this module and dispatched directly to the API server. Responses are returned synchronously — there is no longer a queue to poll. Errors are reported back in the response and surfaced as exceptions or status messages in the Python interface.