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. Currently Z.MAST allows access the CANDELS, GOODS, HFF-DeepSpace and 3D-HST surveys. MAST is planning to add a number of other surveys. See z.MAST documentation.

Using the API

Parameters

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.

Examples

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:
   print(catalog)
   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))