Welcome to the z.MAST API documentation!

Getting Started

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

Using the API


The API services for each survey can perform both spatial and column searches. They accept the following parameters:

  • catalog: the catalog/table to search (required)
  • ra: the ra coordinate
  • dec: the dec coordinate
  • radius: the radius (optional, default = 0.2d)
  • column or column.filter: Filter by table column with optional decorators, e.g.,
    • A_IMAGE=1 (search for rows where A_IMAGE is equal to 1)
    • A_IMAGE.max=1 (search for rows where A_IMAGE is at most 1)

For column filtering with decorators and other arguments for sorting, paging, formatting and selecting columns from results, the z.MAST APIs follow the conventions of the Catalogs.MAST APIs. For more details see the Catalogs.MAST documentation.

Table and Column Information

For information on the available tables and columns that can be searched for each survey, see the Data Description page or use the metadata API calls for each survey API.


Search GOODS by parameters. The example below will search the goods_master_view for records where ACS_F435W_MAG is greater than 46 and class_star equals zero.

GET /api/v0.1/goods?catalog=goods_master_view&ACS_F435W_MAG.min=46&class_star=0&flatten_response=false&include_info=false  HTTP/1.1
Host: z.mast.stsci.edu
    "data": [
            "objID": 1000036330,
            "ID": 36330,
            "ID_IAU": "J123745.13+622153.0",
            "RA": 189.438041,
            "DEC": 62.3647359,
            "Field": "GOODS-N",
            "Class_star": 0.0,
            "ACS_F435W_MAG": 48.6088,
            "ACS_F606W_MAG": 30.4467,
            "ACS_F775W_MAG": 28.2451,
            "ACS_F850LP_MAG": 27.5085,
            "A_IMAGE": 2.006,
            "B_IMAGE": 1.796,
            "KRON_RADIUS": 8.34,
            "FWHM_IMAGE_F850LP": 11.37,
            "FLUX_RADIUS_2_F850LP": 8.007
            "objID": 1100003189,
            "ID": 3189,
            "ID_IAU": "J033208.75-273955.6",
            "RA": 53.0364689,
            "DEC": -27.6654447,
            "Field": "GOODS-S",
            "Class_star": 0.0,
            "ACS_F435W_MAG": 47.024,
            "ACS_F606W_MAG": 27.2352,
            "ACS_F775W_MAG": 26.1581,
            "ACS_F850LP_MAG": 25.222,
            "A_IMAGE": 5.32,
            "B_IMAGE": 4.192,
            "KRON_RADIUS": 5.33,
            "FWHM_IMAGE_F850LP": 28.34,
            "FLUX_RADIUS_2_F850LP": 9.438
            "objID": 1100032187,
            "ID": 32187,
            "ID_IAU": "J033254.78-274628.8",
            "RA": 53.228243,
            "DEC": -27.7746751,
            "Field": "GOODS-S",
            "Class_star": 0.0,
            "ACS_F435W_MAG": 47.0688,
            "ACS_F606W_MAG": 27.8761,
            "ACS_F775W_MAG": 27.3704,
            "ACS_F850LP_MAG": 26.4877,
            "A_IMAGE": 3.17,
            "B_IMAGE": 2.682,
            "KRON_RADIUS": 5.35,
            "FWHM_IMAGE_F850LP": 17.49,
            "FLUX_RADIUS_2_F850LP": 6.225

Search all catalogs in the CANDELS survey by RA and DEC:

import requests

metadata_url = "http://z.mast.stsci.edu/api/v0.1/candels/metadata.json"
r = requests.get(metadata_url)
response = r.json()

catalogs = [r["table"] for r in response["catalogs"]]

for catalog in catalogs:
   api_url = "http://z.mast.stsci.edu/api/v0.1/candels?ra=53.084175&dec=-27.7560646&radius=0.001&catalog=%s" % catalog
   r = requests.get(api_url)
   response = r.json()
   info = response["info"]
   data = response["data"]
   print(catalog, len(data))

Object API

Survey APIs