.. Gresley documentation master file, created by
   sphinx-quickstart on Mon Jan 22 13:09:07 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. meta::
   :description: Z.MAST is designed to enhance access, increase discoverability, and enable visualization of datasets related to galaxy evolution from the Mikulski Archive for Space Telescopes (MAST) 
    missions and aid in Hubble Space Telescope (HST) and James Webb Space Telescope (JWST) observation planning.
   :keywords: Hubble, Z.mast, Galaxy Evolution, astronomy, catalog, MAST, Space Telescope, NASA, STScI

.. image:: mastlogo_thumb.png
           
******************************************
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 <https://z.mast.stsci.edu/documentation.html>`_. 

.. toctree::
   :maxdepth: 3

   3D-HST <3dhst.rst>
   CANDELS <candels.rst>
   HFF-DeepSpace <deepspace.rst>
   GOODS <goods.rst>
   Object Lookup <object_lookup.rst>
   Spectral Energy Distribution Plots <sed_plot.rst>
   Swagger UI <swagger/index.rst>

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.,

     - :code:`A_IMAGE=1` (search for rows where A_IMAGE is equal to 1)
     - :code:`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 <https://catalogs.mast.stsci.edu/docs/general_catalog_service.html>`_.

Table and Column Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For information on the available tables and columns that can be searched for each survey, see the
`Data Description page <https://z.mast.stsci.edu/data-description.html>`_ 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.

.. sourcecode:: http

   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

.. sourcecode:: json

      {
          "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:

.. sourcecode:: python

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


Other Links
===============

You may find these links of interest: 

`MAST's Z Cut API for image cutouts <https://mast.stsci.edu/zcut/docs/index.html>`_.

`MAST's other APIs <https://mast.stsci.edu/api/v0/>`_.