_images/mastlogo_thumb.png

Welcome to the TESScut.MAST API documentation!

Getting Started

This is documentation for the TESScut.MAST API, one of the Barbara A. Mikulski Archive for Space Telescopes’ (MAST) web service APIs. This API allows users to make a variety of queries related to TESS FFI.

Information on MAST’s other APIs can be found here.

Requesting Sectors

This query allows you to get sector information for a position in the sky

Query

GET /api/v0.1/tesscut/sector?ra=102.7&dec=-70.50  HTTP/1.1
Host: mast.stsci.edu/tesscut

Parameters

The API service accepts the following parameters:

  • ra : the ra coordinate (required)

  • dec: the dec coordinate (required)

  • radius : the radius (optional, default = 0.2d)

    • The radius parameter accepts the following units:

      • d : degrees (default if units are not provided)
      • s : arcseconds
      • m : arcminutes
      • px : pixels (21 arseconds/pixel)
    • If an invalid radius unit is used, the service will respond with status code 400

Each parameter should be formed in the http query:

[host]/api/v0.1/tesscut/sector?ra=[RA]&dec=[DEC]&radius=[RADIUS]

Response

The API service responds with a JSON object with the following keys:

  • results : array containing sector(s) information with keys:

    • sectorName : CAOM sector name identifier
    • sector : Sector number
    • camera : Camera
    • ccd : Chip

Examples

  1. To receive sector information at ra = 102.7, dec = -70.50

    using the default radius of 0.2d, perform the following query:

    https://mast.stsci.edu/tesscut/api/v0.1/tesscut/sector?ra=102.7&dec=-70.50
    

    This will return the following JSON response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8
    
    {
      "results": [
          {
              "sectorName": "tess-s0002-4-3",
              "sector": "0002",
              "camera": "4",
              "ccd": "3"
          }
      ]
     }
    
  2. To receive sector information at ra = 102.7, dec = -70.50, radius = 2s

    perform the following query:

    https://mast.stsci.edu/tesscut/api/v0.1/tesscut/sector?ra=102.7&dec=-70.50&radius=2s
    

Requesting AstroCut

This query allows you to get a zip file of cutout file(s) for a section of sky using the astrocut python package

Query

GET /api/v0.1/tesscut/astrocut?ra=102.7&dec=-70.50&y=5&x=5   HTTP/1.1
Host: mast.stsci.edu/tesscut

Parameters

The API service accepts the following parameters:

  • ra : the ra coordinate (required)

  • dec: the dec coordinate (required)

  • y: the y dimension of the cutout to perform (required)

  • x: the x dimension of the cutout to perform (required)

  • units
    • The units parameter accepts the following units:

      • d : degrees
      • s : arcseconds
      • m : arcminutes
      • px : pixels (21 arseconds/pixel) (default if units are not provided)
    • If an invalid unit is used, the service will respond with status code 400

  • sector: The sector to restrict the cutout as an int (Example: 1) (optional)
    • The sector parameter will restrict to only the matching sector
    • If the provided sector number does not matched the corresponding sector(s) for the searched area, the service will respond with status code 400
    • Default behavior is to return all matched sectors
  • resolve: Whether to resolve the passed ra and dec coordinates (optional, default True)

Each parameter should be formed in the http query:

[host]/api/v0.1/tesscut/sector?ra=[RA]&dec=[DEC]&y=[Y]&x=[X]&units=[UNITS]

Response

The API service responds with a zip file containing all cutout files created by astrocut.

Note: The named .fits files in the zip file will refer to the size as translated into pixel dimensions

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename=astrocut_<ra>_<dec>_<y>x<x><units>.zip

If no files were created, the service responds with an empty response array

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
   "results": []
}

Examples

  1. To receive a square cutout at ra = 102.7, dec = -70.50 of 5px, perform the following query:

    https://mast.stsci.edu/tesscut/api/v0.1/tesscut/astrocut?ra=102.7&dec=-70.50&x=5&y=5
    

    This will return the following response and begin a zip file download:

    HTTP/1.1 200 OK
    Content-Type: application/zip
    Content-Disposition: attachment; filename=astrocut_102.7_-70.50_5x5.zip
    
  2. To receive a cutout at ra = 102.7, dec = -70.50, x = 0.2, y = 0.3, units = d

    perform the following query:

    https://mast.stsci.edu/tesscut/api/v0.1/tesscut/astrocut?ra=102.7&dec=-70.50&x=0.2&y=0.3&units=d