Archive MAST Observations

Mikulski Archive for Space Telescopes observations (HST, JWST, TESS, Kepler, ...).

• Module name: mast
• Python class: astroquery.mast.Observations
• Functions: 27

Call any function below with the astroquery_execute MCP tool. Descriptions are taken from the upstream astroquery/astropy docstrings.

Function	Summary
authenticated	Observations.authenticated
clear_cache	Removes all cache files.
disable_cloud_dataset	Disables downloading public files from S3 instead of MAST.
download_file	Downloads a single file based on the data URI
download_products	Download data products.
enable_cloud_dataset	Enable downloading public files from S3 instead of MAST.
filter_products	Filters an Table of data products based on given filters.
get_cloud_uri	For a given data product, returns the associated cloud URI.
get_cloud_uris	Given an Table of data products or query criteria and filter parameters,
get_metadata	Returns metadata about the requested query type.
get_product_list	Queries the service and returns a table object.
get_product_list_async	Given a "Product Group Id" (column name obsid) returns a list of associated data products.
get_unique_product_list	Given a "Product Group Id" (column name obsid), returns a list of associated data products with
list_missions	Lists data missions archived by MAST and available through astroquery.mast.
login	Log into the MAST portal.
logout	Log out of current MAST session.
query_criteria	Queries the service and returns a table object.
query_criteria_async	Given an set of criteria, returns a list of MAST observations.
query_criteria_count	Given an set of filters, returns the number of MAST observations meeting those criteria.
query_object	Queries the service and returns a table object.
query_object_async	Given an object name, returns a list of MAST observations.
query_object_count	Given an object name, returns the number of MAST observations.
query_region	Queries the service and returns a table object.
query_region_async	Given a sky position and radius, returns a list of MAST observations.
query_region_count	Given a sky position and radius, returns the number of MAST observations in that region.
reset_cache_location	Resets the cache location to the default astropy cache
resolve_object	Resolves an object name to a position on the sky.

Functions

authenticated

No description in upstream docstring.

Observations.authenticated()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="authenticated",
    params={},
)

Parameters

No parameters.

clear_cache

Removes all cache files.

Observations.clear_cache()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="clear_cache",
    params={},
)

Parameters

No parameters.

disable_cloud_dataset

Disables downloading public files from S3 instead of MAST.

Observations.disable_cloud_dataset()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="disable_cloud_dataset",
    params={},
)

Parameters

No parameters.

download_file

Downloads a single file based on the data URI

Observations.download_file(uri, *, local_path=None, base_url=None, cache=True, cloud_only=False, verbose=True)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="download_file",
    params={"uri": "<uri>"},
)

Parameters

Parameter	Type	Default	Description
uri (required)	str		The product dataURI, e.g. mast:JWST/product/jw00736-o039_t001_miri_ch1-long_x1d.fits
local_path	str	None	Directory or filename to which the file will be downloaded. Defaults to current working directory.
base_url	str	None	A base url to use when downloading. Default is the MAST Portal API
cache	bool	True	Default is True. If file is found on disk it will not be downloaded again.
cloud_only	bool	False	Default False. If set to True and cloud data access is enabled (see enable_cloud_dataset) files that are not found in the cloud will be skipped rather than downloaded from MAST as is the default behavior. If cloud access is not enables this argument as no affect.
verbose	bool	True	Default True. Whether to show download progress in the console.

Returns

str — download status message. Either COMPLETE, SKIPPED, or ERROR.

download_products

Download data products.

Observations.download_products(products, *, download_dir=None, flat=False, cache=True, curl_flag=False, mrp_only=False, cloud_only=False, verbose=True, **filters)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="download_products",
    params={"products": "<products>"},
)

If cloud access is enabled, files will be downloaded from the cloud if possible.

Parameters

Parameter	Type	Default	Description
products (required)	str, list, Table		Either a single or list of obsids (as can be given to get_product_list), or a Table of products (as is returned by get_product_list)
download_dir	str	None	Optional. Directory to download files to. Defaults to current directory.
flat	bool	False	Default is False. If set to True, and download_dir is specified, it will put all files into download_dir without subdirectories. Or if set to True and download_dir is not specified, it will put files in the current directory, again with no subdirs. The default of False puts files into the standard directory structure of "mastDownload/<obs_collection>/<obs_id>/". If curl_flag=True, the flat flag has no effect, as astroquery does not control how MAST generates the curl download script.
cache	bool	True	Default is True. If file is found on disc it will not be downloaded again. Note: has no affect when downloading curl script.
curl_flag	bool	False	Default is False. If true instead of downloading files directly, a curl script will be downloaded that can be used to download the data files at a later time.
mrp_only	bool	False	Default False. When set to true only "Minimum Recommended Products" will be returned.
cloud_only	bool	False	Default False. If set to True and cloud data access is enabled (see enable_cloud_dataset) files that are not found in the cloud will be skipped rather than downloaded from MAST as is the default behavior. If cloud access is not enables this argument as no affect.
verbose	bool	True	Default True. Whether to show download progress in the console.
**filters

Returns

Table — The manifest of files downloaded, or status of files on disk if curl option chosen.

enable_cloud_dataset

Enable downloading public files from S3 instead of MAST.

Observations.enable_cloud_dataset(provider='AWS', profile=None, verbose=True)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="enable_cloud_dataset",
    params={},
)

Requires the boto3 library to function.

Parameters

Parameter	Type	Default	Description
provider	str	'AWS'	Which cloud data provider to use. We may in the future support multiple providers, though at the moment this argument is ignored.
profile	str	None	Profile to use to identify yourself to the cloud provider (usually in ~/.aws/config).
verbose	bool	True	Default True. Logger to display extra info and warning.

filter_products

Filters an Table of data products based on given filters.

Observations.filter_products(products, *, mrp_only=False, extension=None, **filters)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="filter_products",
    params={"products": "<products>"},
)

Parameters

Parameter	Type	Default	Description
products (required)	Table		Table containing data products to be filtered.
mrp_only	bool	False	Default False. When set to true only "Minimum Recommended Products" will be returned.
extension	string or array	None	Default None. Option to filter by file extension.
**filters

Returns

Table — Filtered table of data products.

get_cloud_uri

For a given data product, returns the associated cloud URI.

Observations.get_cloud_uri(data_product, *, include_bucket=True, full_url=False)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_cloud_uri",
    params={"data_product": "<data_product>"},
)

If the product is from a mission that does not support cloud access an exception is raised. If the mission is supported but the product cannot be found in the cloud, the returned path is None.

Parameters

Parameter	Type	Default	Description
data_product (required)	Row, str		Product to be converted into cloud data uri.
include_bucket	bool	True	Default True. When false returns the path of the file relative to the top level cloud storage location. Must be set to False when using the full_url argument.
full_url	bool	False	Default False. Return an HTTP fetchable url instead of a cloud uri. Must set include_bucket to False to use this option.

Returns

str or None — Cloud URI generated from the data product. If the product cannot be found in the cloud, None is returned.

get_cloud_uris

Given an Table of data products or query criteria and filter parameters,

Observations.get_cloud_uris(data_products=None, *, include_bucket=True, full_url=False, pagesize=None, page=None, mrp_only=False, extension=None, filter_products={}, return_uri_map=False, verbose=True, **criteria)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_cloud_uris",
    params={},
)

returns the associated cloud data URIs.

Parameters

Parameter	Type	Default	Description
data_products	Table, list	None	Table containing products or list of MAST uris to be converted into cloud data uris. If provided, this will supercede page_size, page, or any keyword arguments passed in as criteria.
include_bucket	bool	True	Default True. When False, returns the path of the file relative to the top level cloud storage location. Must be set to False when using the full_url argument.
full_url	bool	False	Default False. Return an HTTP fetchable url instead of a cloud uri. Must set include_bucket to False to use this option.
pagesize	int	None	Default None. Can be used to override the default pagesize when making a query. E.g. when using a slow internet connection. Query criteria must also be provided.
page	int	None	Default None. Can be used to override the default behavior of all results being returned for a query to obtain one specific page of results. Query criteria must also be provided.
mrp_only	bool	False	Default False. When set to True, only "Minimum Recommended Products" will be returned.
extension	string or array	None	Default None. Option to filter by file extension.
filter_products	dict	{}	Filters to be applied to data products. Valid filters are all products fields listed here. The column name as a string is the key. The corresponding value is one or more acceptable values for that parameter. Filter behavior is AND between the filters and OR within a filter set. For example: {"productType": "SCIENCE", "extension"=["fits","jpg"]}
return_uri_map	bool	False	Default False. If set to True, returns a dictionary mapping the original data product URIs to their corresponding cloud URIs. This is useful for tracking which products were successfully converted to cloud URIs.
verbose	bool	True	Default True. Whether to issue warnings if a product cannot be found in the cloud.
**criteria

Returns

list — List of URIs generated from the data products. May contain entries that are None if data_products includes products not found in the cloud.

get_metadata

Returns metadata about the requested query type.

Observations.get_metadata(query_type)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_metadata",
    params={"query_type": "<query_type>"},
)

Parameters

Parameter	Type	Default	Description
query_type (required)	str		The query to get metadata for. Options are observations, and products.

Returns

Table — The metadata table.

get_product_list

Queries the service and returns a table object.

Observations.get_product_list(*args, **kwargs)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_product_list",
    params={},
)

Given a "Product Group Id" (column name obsid) returns a list of associated data products. Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. See column documentation here.

To return unique data products, use Observations.get_unique_product_list.

Parameters

Parameter	Type	Default	Description
*args
**kwargs

Returns

A Table object. —

get_product_list_async

Given a "Product Group Id" (column name obsid) returns a list of associated data products.

Observations.get_product_list_async(observations)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_product_list_async",
    params={"observations": "<observations>"},
)

Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. See column documentation here.

To return unique data products, use Observations.get_unique_product_list.

Parameters

Parameter	Type	Default	Description
observations (required)	str or Row or list/Table of same		Row/Table of MAST query results (e.g. output from query_object) or single/list of MAST Product Group Id(s) (obsid). See description here.

Returns

list of Response`` —

get_unique_product_list

Given a "Product Group Id" (column name obsid), returns a list of associated data products with

Observations.get_unique_product_list(observations)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="get_unique_product_list",
    params={"observations": "<observations>"},
)

unique dataURIs. Note that obsid is NOT the same as obs_id, and inputting obs_id values will result in an error. See column documentation here.

Parameters

Parameter	Type	Default	Description
observations (required)	str or Row or list/Table of same		Row/Table of MAST query results (e.g. output from query_object) or single/list of MAST Product Group Id(s) (obsid). See description here.

Returns

Table — Table containing products with unique dataURIs.

list_missions

Lists data missions archived by MAST and available through astroquery.mast.

Observations.list_missions()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="list_missions",
    params={},
)

Parameters

No parameters.

Returns

list — List of available missions.

login

Log into the MAST portal.

Observations.login(token=None, store_token=False, reenter_token=False)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="login",
    params={},
)

Parameters

Parameter	Type	Default	Description
token	string	None	Default is None. The token to authenticate the user. This can be generated at https://ssoportal.stsci.edu/idp/profile/SAML2/Redirect/SSO?execution=e1s1 If not supplied, it will be prompted for if not in the keyring or set via $MAST_API_TOKEN
store_token	bool	False	Default False. If true, MAST token will be stored securely in your keyring.
reenter_token	bool	False	Default False. Asks for the token even if it is already stored in the keyring or $MAST_API_TOKEN environment variable. This is the way to overwrite an already stored password on the keyring.

logout

Log out of current MAST session.

Observations.logout()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="logout",
    params={},
)

Parameters

No parameters.

query_criteria

Queries the service and returns a table object.

Observations.query_criteria(*args, **kwargs)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_criteria",
    params={},
)

Given an set of criteria, returns a list of MAST observations. Valid criteria are returned by get_metadata("observations")

Parameters

Parameter	Type	Default	Description
*args
**kwargs

Returns

A Table object. —

query_criteria_async

Given an set of criteria, returns a list of MAST observations.

Observations.query_criteria_async(*, pagesize=None, page=None, resolver=None, **criteria)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_criteria_async",
    params={},
)

Valid criteria are returned by get_metadata("observations")

Parameters

Parameter	Type	Default	Description
pagesize	int	None	Can be used to override the default pagesize. E.g. when using a slow internet connection.
page	int	None	Can be used to override the default behavior of all results being returned to obtain one specific page of results.
resolver	str	None	The resolver to use when resolving a named target into coordinates. Valid options are "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.
**criteria

Returns

list of Response`` —

query_criteria_count

Given an set of filters, returns the number of MAST observations meeting those criteria.

Observations.query_criteria_count(*, pagesize=None, page=None, resolver=None, **criteria)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_criteria_count",
    params={},
)

Parameters

Parameter	Type	Default	Description
pagesize	int	None	Can be used to override the default pagesize. E.g. when using a slow internet connection.
page	int	None	Can be used to override the default behavior of all results being returned to obtain one specific page of results.
resolver	str	None	The resolver to use when resolving a named target into coordinates. Valid options are "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.
**criteria

Returns

int —

query_object

Queries the service and returns a table object.

Observations.query_object(*args, **kwargs)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_object",
    params={},
)

Given an object name, returns a list of MAST observations. See column documentation here.

Parameters

Parameter	Type	Default	Description
*args
**kwargs

Returns

A Table object. —

query_object_async

Given an object name, returns a list of MAST observations.

Observations.query_object_async(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None, resolver=None)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_object_async",
    params={"objectname": "<objectname>"},
)

See column documentation here.

Parameters

Parameter	Type	Default	Description
objectname (required)	str		The name of the target around which to search.
radius	str or Quantity object	<Quantity 0.2 deg>	Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.
pagesize	int	None	Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.
page	int	None	Defaulte None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.
resolver	str	None	The resolver to use when resolving a named target into coordinates. Valid options are "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

Returns

list of Response`` —

query_object_count

Given an object name, returns the number of MAST observations.

Observations.query_object_count(objectname, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None, resolver=None)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_object_count",
    params={"objectname": "<objectname>"},
)

Parameters

Parameter	Type	Default	Description
objectname (required)	str		The name of the target around which to search.
radius	str or Quantity object	<Quantity 0.2 deg>	The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.
pagesize	int	None	Can be used to override the default pagesize. E.g. when using a slow internet connection.
page	int	None	Can be used to override the default behavior of all results being returned to obtain one specific page of results.
resolver	str	None	The resolver to use when resolving a named target into coordinates. Valid options are "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. Default is None.

Returns

int —

query_region

Queries the service and returns a table object.

Observations.query_region(*args, **kwargs)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_region",
    params={},
)

Given a sky position and radius, returns a list of MAST observations. See column documentation here.

Parameters

Parameter	Type	Default	Description
*args
**kwargs

Returns

A Table object. —

query_region_async

Given a sky position and radius, returns a list of MAST observations.

Observations.query_region_async(coordinates, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_region_async",
    params={"coordinates": "<coordinates>"},
)

See column documentation here.

Parameters

Parameter	Type	Default	Description
coordinates (required)	str or coordinates object		The target around which to search. It may be specified as a string or as the appropriate coordinates object.
radius	str or Quantity object	<Quantity 0.2 deg>	Default 0.2 degrees. The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.
pagesize	int	None	Default None. Can be used to override the default pagesize for (set in configs) this query only. E.g. when using a slow internet connection.
page	int	None	Default None. Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

list of Response`` —

query_region_count

Given a sky position and radius, returns the number of MAST observations in that region.

Observations.query_region_count(coordinates, *, radius=<Quantity 0.2 deg>, pagesize=None, page=None)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="query_region_count",
    params={"coordinates": "<coordinates>"},
)

Parameters

Parameter	Type	Default	Description
coordinates (required)	str or coordinates object		The target around which to search. It may be specified as a string or as the appropriate coordinates object.
radius	str or Quantity object	<Quantity 0.2 deg>	The string must be parsable by Angle. The appropriate Quantity object from units may also be used. Defaults to 0.2 deg.
pagesize	int	None	Can be used to override the default pagesize for. E.g. when using a slow internet connection.
page	int	None	Can be used to override the default behavior of all results being returned to obtain a specific page of results.

Returns

int —

reset_cache_location

Resets the cache location to the default astropy cache

Observations.reset_cache_location()

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="reset_cache_location",
    params={},
)

Parameters

No parameters.

resolve_object

Resolves an object name to a position on the sky.

Observations.resolve_object(objectname, *, resolver=None, resolve_all=False)

Call via MCP

astroquery_execute(
    module_name="mast",
    function_name="resolve_object",
    params={"objectname": "<objectname>"},
)

Parameters

Parameter	Type	Default	Description
objectname (required)	str		Name of astronomical object to resolve.
resolver	str	None	The resolver to use when resolving a named target into coordinates. Valid options are "SIMBAD" and "NED". If not specified, the default resolver order will be used. Please see the STScI Archive Name Translation Application (SANTA) for more information. If resolve_all is True, this parameter will be ignored. Default is None.
resolve_all	bool	False	If True, will try to resolve the object name using all available resolvers ("NED", "SIMBAD"). Function will return a dictionary where the keys are the resolver names and the values are the resolved coordinates. Default is False.

Returns

``SkyCoord, dict — If `resolve_all` is False, returns a `SkyCoord` object with the resolved coordinates. If `resolve_all` is True, returns a dictionary where the keys are the resolver names and the values are `SkyCoord` objects with the resolved coordinates.