.. _using-mast-catalogs: ######################## Using MAST Catalogs ######################## .. contents:: Table of Contents :depth: 3 ***************** Getting Started ***************** MAST Catalogs allows for pragmatic search of available Catalog APIs through the construction of either **GET** query strings or **POST** parameters. Not all options are provided by all catalogs and are indicated in their respective documentations. ******************** Searching Catalogs ******************** Query Return Formats ====================== .. _encoding-formats-label: Encoding Formats -------------------- Several different return formats are possible including: JSON, CSV, XML and VOTable Also, for specific formats, such as JSON and CSV formatting may be adjusted based on parameters To request specific formats, a path decorator, format parameter or header ``accept`` may be specified. JSON is returned by default. .. sourcecode:: HTTP :caption: Format through decorator /catalog/subpath.json /catalog/subpath.csv /catalog/subpath.xml /catalog/subpath.votable .. sourcecode:: HTTP :caption: Format through query or passed parameter /catalog/subpath?format=json format = json /catalog/subpath?format=csv format = csv /catalog/subpath?format=xml format = xml /catalog/subpath?format=votable format = votable .. sourcecode:: HTTP :caption: Format through accept header "Accept": "json" "Accept": "csv" "Accept": "xml" "Accept": "votable" JSON -------- Requesting this format will return results in a JSON format with ``Content-Type: application/json`` Options ^^^^^^^^^^^^ ``raw`` * *default=true* * Request all responses to be in faw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types. ``flatten_response`` * *default=true* * Request responses to return as a list of lists rather than a list of objects. ``include_info`` * *default=true* * Request responses to include column info. If true, the response will include the ``info`` key within the return object with available column information. **Examples** .. sourcecode:: JSON :caption: JSON Sample Response ``flatten_response=true, include_info=true`` { "info": [{ "name": "column name", "type": "column type"}....], "data": [[], []] } .. sourcecode:: JSON :caption: JSON Sample Response ``flatten_response=false, include_info=false`` { "data": [{}, {}] } CSV ------ Requesting this format will return results in a CSV format with ``Content-Type: text/csv`` Options ^^^^^^^^^ ``delimiter`` * *default=comma* * Chosen delimiter for the CSV file. Supported options below ``include_info`` * *default=true* * Request responses to include column info. If false, the returned csv begin with the first data row. Supported Delimiters ^^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: CSV Delimiters :header: "Parameter Value", "Delimiter Description" "comma", "``,`` (default)" "space", (space) "tab", ``\t`` "semicolon", ``;`` "pipe", ``|`` "iraf", ``INDEF`` **Examples** .. sourcecode:: CSV :caption: CSV Sample Response include_info=true column_a, column_b, column_c value-a, value-b, value-c .. sourcecode:: CSV :caption: CSV Sample Response \nclude_info=false value-a, value-b, value-c XML -------- Requesting this format will return results in a XML format with ``Content-Type: text/xml`` Options ^^^^^^^^^^^ ``include_info`` * *default=true* * Request responses to include column info. If false, the returned xml fields default to ``i`` VOTable ------------- Requesting this format will return results in a VOTable format with ``Content-Type: text/xml`` Options ^^^^^^^^^^ ``include_info`` * *default=true* * Request responses to include column info. If false, the returned VO table columns will default to ``field_name`` column names of type ``char`` .. _selecting-columns-label: Selecting Columns ===================== Returned columns may be selected for the response. Columns submitted will be verified in a case insensitive manner so that only columns with corresponding data columns are returned. If no valid columns are submitted, all default columns will be returned. Columns selected will preserve requested case and order. Columns can be selected by using the ``columns`` parameter. To choose multiple columns, the ``columns`` parameter may be included multiple times or multiple columns may be submitted as a list. Both options may be intermixed but this is discouraged. .. sourcecode:: HTTP :caption: Selecting Multiple Columns Multiple Parameters columns=Column_A columns=column_b .. sourcecode:: HTTP :caption: Selecting Multiple Columns With List columns=["Column_A", "column_b"] or columns=[Column_A, column_b] .. _column-filtering-label: Column Filtering =================== Basic Filtering ------------------ With the search query, columns may be filtered by given values. Example: Search filter where ``sample_column`` equals ``FOO`` .. sourcecode:: HTTP sample_column=FOO This will execute a search query where ``sample_column`` must equal ``FOO`` For a given column, if additional filtering is required the column name may appear multiple times, resulting in **OR** filter conditions applied. Example: Search filter where ``sample_column`` equals ``FOO`` **OR** ``sample_column`` equals ``BAR`` .. sourcecode:: HTTP sample_column=FOO sample_column=BAR Filtering Decorators ----------------------- Filtered column names may be also use optional decorators for greater functionality. To add a decorator, the column name should be followed by the desired decorator separated by a period. For example, to filter the search so that ``sample_column`` is greater than ``5`` .. sourcecode:: HTTP sample_column.gt=5 .. csv-table:: Filtering :header: "decorator", "description", "example" :widths: 10, 20, 20 "min", "minimum", ``sample_column.min=0.2`` "gte", "greater than or equal to (equal to min)", ``sample_column.gte=0.2`` "gt", "greater than", ``sample_column.gt=0.3`` "max", "maximum", ``sample_column.max=1.5`` "lte", "less than or equal to (equal to max)", ``sample_column.lte=1.5`` "lt", "less than", ``sample_column.lt=1.4`` "like", "like", ``sample_column.like=te`` "contains", "contains", ``sample_column.min=test`` "noteq", "not equal to", ``sample_column.noteq=0`` "notlt", "not less than to", ``sample_column.notlt=0`` "notgt", "not greater than to", ``sample_column.notgt=0`` .. _sorting-label: Sorting =========== To select the sort order of the results use the `sort_by` parameter. The default sort order for a provided column is `ASC`. The provided sort parameter will be applied only to valid columns in a case insensitive manner. If not sorting option is provided the result will return in the default sort by the query. Multiple sorting may be provided and will be sorted according to the provided order. As with column selection, multiple ``sort_by`` parameters may be provided or ``sort_by`` may include a list of sort options. To indicate sort order, include a sorting decorator. .. csv-table:: Sort Order Decorators :header: "decorator", "order", "example" :widths: 10, 10, 20 None, ASC, ``sample_column`` ``.ASC``, ASC, ``sample_column.asc`` (note case insensitivity) ``DESC``, DESC, ``SAMPLE_COLUMN.DESC`` (note case insensitivity) .. _paging-label: Paging ========== The result set may be paged through the use of the ``pagesize`` (default = 50000) and ``page`` (default = 1)