Welcome to MAST’s zCut API documentation!

• Welcome to MAST’s zCut API documentation!
  • Getting Started
    • Requesting survey list
      • Query
      • Parameters
      • Response
      • Examples
    • Requesting Astrocut
      • Query
      • Parameters
      • Examples
        • Survey Service
        • Astrocut Service

Getting Started

This is documentation for the zcut.mast API, one of the Barbara A. Mikulski Archive for Space Telescopes’ (MAST) web service APIs. This API allows users to request cutouts from various Hubble deep field surveys. It is currently in beta and allows access the the CANDELS survey only, but a number of other surveys are planned additions.

Requesting survey list

This query allows you to get the list of surveys available for a position in the sky.

Query

GET /api/v0.1/survey?ra=150.0945&dec=2.38681&radius=2m HTTP/1.1
Host: mast.stsci.edu/zcut/

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

  • 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/survey?ra=[RA]&dec=[DEC]&radius=[RADIUS]

Response

The API service responds with a JSON object with a single key:

• surveys : array containing the survey(s) that overlap the given position

Examples

1. To receive survey information at ra = 189.49206, dec = 62.20615

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

   https://mast.stsci.edu/zcut/api/v0.1/survey?ra=189.49206&dec=62.20615
   

   This will return the following JSON response:

   HTTP/1.1 200 OK
   Content-Type: application/json; charset=UTF-8
   
   {
     "surveys": [
        "candels_gn_60mas",
        "candels_gn_30mas"
     ]
    }
   

2. To receive survey information at ra = 189.49206, dec = 62.20615, radius = 2m

   perform the following query:

   https://mast.stsci.edu/zcut/api/v0.1/survey?ra=189.49206&dec=62.20615&radius=2m
   

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.

The cutouts can be returned as fits files or image (png/jpg) files, and the user may also optionally specify the particular survey to cutout.

Query

GET /api/v0.1/astrocut?ra=215.36067&dec=53.09557&y=200&x=300&units=px HTTP/1.1
Host: mast.stsci.edu/zcut/

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 (default if units are not provided)

  • If an invalid unit is used, the service will respond with status code 400

• survey: The survey to restrict the cutout (Example: “candels_gn_60mas”) (optional)

  • The survey parameter will restrict to only the matching survey
  • If the provided survey does not match any corresponding surveys for the searched area, the service will respond with status code 400
  • Default behavior is to return all matched surveys

• format: The cutout file format (optional)

  • Default is fits, valid options are fits, jpg, png

• img_params: Dictionary of image parameters (optional)

  • Only used if format is jpg or png

  • Valid entries are:

    • stretch : The stretch to apply to the image array, default asinh. Valid values are: asinh, sinh, sqrt, log, linear.
    • minmax_percent : Percent interval of pixels to keep when scaling, default is [0.5,99.5]
    • minmax_value : Pixel value interval of pixels to keep when scaling, default is to use minmax_percent instead
    • invert : True/false, if True the image will be inverted

Each parameter should be formed in the http query:

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

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/zip;
Content-Disposition: attachment; filename=astrocut_215.36067_53.09557_200x300px.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 = 215.36067, dec = 53.09557 of 100px, perform the following query:

   https://mast.stsci.edu/zcut/api/v0.1/astrocut?ra=215.36067&dec=53.09557&x=100&y=100&units=px
   

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

   HTTP/1.1 200 OK
   Content-Type: application/zip
   Content-Disposition: attachment; filenameastrocut_215.36067_53.09557_100x100px.zip
   

2. To receive a cutout at ra = 102.7, dec = -70.50, x = 5, y = 7, units = s, format=jpg

   perform the following query:

   https://mast.stsci.edu/zcut/api/v0.1/astrocut?ra=215.36067&dec=53.09557&x=5&y=7&units=s&format=jpg
   

API

• Survey Service
• Astrocut Service