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)