Using MAST Catalogs 

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

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.

Format through decorator

/catalog/subpath.json
/catalog/subpath.csv
/catalog/subpath.xml
/catalog/subpath.votable

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

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

JSON Sample Response flatten_response=true, include_info=true

{
    "info": [{ "name": "column name", "type": "column type"}....],
    "data": [[], []]
}

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 Delimiters
Parameter Value	Delimiter Description
comma	`,` (default)
space	(space)
tab	`\t`
semicolon	`;`
pipe	`\|`
iraf	`INDEF`

Examples

CSV Sample Response include_info=true

column_a, column_b, column_c
value-a, value-b, value-c

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 

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.

Selecting Multiple Columns Multiple Parameters

columns=Column_A
columns=column_b

Selecting Multiple Columns With List

columns=["Column_A", "column_b"]
or
columns=[Column_A, column_b]

Column Filtering 

Basic Filtering

With the search query, columns may be filtered by given values.

Example: Search filter where sample_column equals FOO

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

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

sample_column.gt=5

Filtering
decorator	description	example
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 

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.

Sort Order Decorators
decorator	order	example
None	ASC	`sample_column`
`.ASC`	ASC	`sample_column.asc` (note case insensitivity)
`DESC`	DESC	`SAMPLE_COLUMN.DESC` (note case insensitivity)

Paging 

The result set may be paged through the use of the pagesize (default = 50000) and page (default = 1)