Getting Started

Below are some example queries using the TESScut API.

Note: TESScut limits each user to no more than 5 requests per second. After the user has reached this limit, TESScut will return a 503 Service Temporarily Unavailable Error.

Requesting Sectors

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

Query

GET /api/v0.1/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 = 0d)

    • 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:

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

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 0d, perform the following query:

    GET https://mast.stsci.edu/tesscut/api/v0.1/sector?ra=100.2&dec=-6.1 HTTP/1.1
    

    This will return the following JSON response:

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

    perform the following query:

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

Requesting a cutout

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/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 False)

Each parameter should be formed in the http query:

GET [host]/api/v0.1/astrocut?ra=[RA]&dec=[DEC]&y=[Y]&x=[X]&units=[UNITS] HTTP/1.1

The service applies a cutout area limit of 10,000 pixels. If the requested cutout area exceeds this limit, the service will respond with status code 400.

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:

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

    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:

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

Moving Targets

Sector information and cutouts can also be requested for moving targets. In this case instead of supplying a RA and Dec, the user supplies an object name/ID and optionally an object type. The target name/ID and type are those understood by the JPL HOrizons ephemerides service.

Moving Target Sectors

This query returns the sectors crossed by a given moving target.

Query

The API service accepts the following parameters:

  • obj_id : the target name/ID (required)

  • obj_type: the target type (optional, by default tries majorbody then smallbody)

Each parameter should be formed in the http query:

GET [host]/api/v0.1/sector?obj_id=[NAME]&obj_type=[TYPE] HTTP/1.1

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 for the asteroid Stichius, perform the following query:

    GET https://mast.stsci.edu/tesscut/api/v0.1/moving_target/sector?obj_id=Stichius   HTTP/1.1
    

    This will return the following JSON response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8
    
    {
      "results": [
          {
              "sectorName": "tess-s0001-1-1",
              "sector": "0001",
              "camera": "1",
              "ccd": "1"
          }
      ]
     }
    
  2. To receive sector information for the asteroid Eleonora, perform the following query:

    perform the following query:

    GET https://mast.stsci.edu/tesscut/api/v0.1/moving_target/sector?obj_id=Eleonora HTTP/1.1
    

Moving Target Cutouts

This query allows you to get a zip file of cutout file(s) for a region around a moving target using the astrocut python package.

Query

The API service accepts the following parameters:

  • obj_id : the target name/ID (required)

  • obj_type: the target type (optional, by default tries majorbody then smallbody)

  • 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

Each parameter should be formed in the http query:

GET [host]/api/v0.1/moving_target/astrocut?obj_id=[NAME]&obj_type=[TYPE]&y=[Y]&x=[X]&units=[UNITS] HTTP/1.1

The service applies a cutout area limit of 10,000 pixels. If the requested cutout area exceeds this limit, the service will respond with status code 400.

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_<target name>_<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 around the obj_id = Eleonora of 5px, in TESS sector 6 perform the following query:

    GET https://mast.stsci.edu/tesscut/api/v0.1/moving_target/astrocut?obj_id=Eleonora&x=5&y=5&sector=6 HTTP/1.1
    

    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_Eleonora_5x5.zip
    
  2. To receive a cutout of obj_id = Stichius, x = 0.2, y = 0.3, units = d

    perform the following query:

    GET https://mast.stsci.edu/tesscut/api/v0.1/moving_target/astrocut?obj_id=Stichius&x=0.2&y=0.3&units=d HTTP/1.1