spacer link to MAST page spacer logo image spacer
 
link to STScI page


MAST Web Services

MAST Discovery Portal API
HTTP GET Requests
    - Script Examples
    - Mission Searches
    - Simple Cone Search
    - Simple Image Access Protocol
    - Simple Spectral Access Protocol
RSS News Feed
Soap Services

MAST Discovery Portal API

Many MAST data holdings can be searched using the MAST Discovery Portal API. This API allows for programmatic access to all data available through the MAST Discovery Portal (mast.stsci.edu). API documentation is found at https://mast.stsci.edu/api.


HTTP GET Requests

MAST data holdings can also be searched using MAST classic HTTP GET requests. The GET request allows the search parameters to be included in the URL. As such, they can be called from within programs to automate data searches. The results can be returned in a variety of formats including HTML, VOTable XML format, excel spreadsheet, and comma-separated values which can simplify ingesting results into user-written programs. In addition, submitting GET requests can bypass restrictions currently placed on the web search forms (e.g., restrictions on the max_records value). Unfortunately, there has been little documentation on how the GET requests are formulated. This document will summarize the services currently available from MAST and give examples showing how they can be used.

Remember, when creating URLs, special characters must be encoded. URLs may only use alphanumerics [0-9a-zA-Z], the characters "$-_.+!*'()," and special reserved characters. The characters "<" and ">" must be specified as "%3C" and "%3E" respectively. For example, to specify a parameter such as RA > 120, the GET request parameter would be RA=%3E120. Blanks can be specified using the "+" character. Nulls can be specified as \null.


Script Examples

Scripts for retrieving MAST search results can be written in many programming languages. Basically you just need to download and extract information from a web page. A few simple examples are shown below. We welcome more examples from users.


Mission Searches

In general, mission searches are specified in the form:

https://archive.stsci.edu/[data set]/search.php?action=Search&params

where [data set] is the MAST-defined acronym for a particular set of data (listed below), and params is the list of search parameters as defined below. This does not apply to Kepler or K2 however so the correct values for [data set] are shown in parentheses below. Note that "action=Search" is a required parameter for all mission search requests. For the pointings search however, action may equal either "Search+Pointings" or "Search+Exposures".

The current list of data sets, links to mission-specific search fields, and search general parameters are shown in the following list:


In general, any parameter listed on the HTML search form can be specified in a GET request. If you are parsing the results, it would be easier and probably faster, to request the search results in CSV or VOTable format using the "outputformat" parameter.

Mission search examples:

  • Search the HST archive for observations within the specified radius (in arcminutes), centered on the given RA and Dec values (in decimal degrees), allow a maximum of 1000 records, and output the default columns as comma-separated values: (Try it)
    https://archive.stsci.edu/hst/search.php?RA=53.084&DEC=-27.873&radius=100. &max_records=1000&outputformat=CSV&action=Search

  • Search the Kepler archive for the first 1000 files (sorted by Kepler ID) that have become public in 2009, that was part of the EX program, and output comma-separated values with RA in decimal hours: (try it)
    https://archive.stsci.edu/kepler/data_search/search.php? ads_release_date=%3C2010&ktc_investigation_id=EX&max_records=1000&coordformat=dechr&outputformat=CSV&action=Search

  • Do similiar cone search for XMM-OM data with a search radius of 5 arcminutes show sql query, sexigesimal coordinates, and output results in HTML (this type of request is good for testing) (Try it)
    https://archive.stsci.edu/xmm-om/search.php?RA=53.084&DEC=-27.873 &radius=5.&showquery=on&action=Search

  • Search the Kepler/GALEX cross match catalog for nuvg_color values between 0.0 and 0.5. Use the kggoldstandard version for more accurate matches. (try it)
    https://archive.stsci.edu/kepler/kgmatch/search.php?action=Search&search_table=kggoldstandard&nuvg_color=0.0..0.5

  • Search the Kepler target search form for entries where fuvnuv is not null, the number of seasons on CCD = 4, and the effective temperature is > 10,000. (try it)
    https://archive.stsci.edu/kepler/kepler_fov/search.php?action=Search&fuvnuv=!\null&kct_num_season_onccd=4&kic_teff=%3E10000

  • Search the Kepler Objects of Interest table for confirmed planets. Return all (139) columns (i.e., not just defaults) with coordinates in decimal degrees and output in pipe-separated format (note some columns contains commas, so don't use CSV format): (try it)
    https://archive.stsci.edu/kepler/koi/search.php?action=Search&koi_disposition=confirmed&verb=3&coordformat=dec&outputformat=PSV">

  • Search the EPIC table for the top 100 extended sources (by EPIC id) and remove any null columns. (try it)
    https://archive.stsci.edu/k2/epic/search.php?action=Search&objtype=extended&max_records=100&remnull=on&verb=3

  • Search the HST archive for pep_id 9293, allow a maximum of 1000 records, and output results as comma-separated values: (Try it)
    https://archive.stsci.edu/hst/search.php?sci_pep_id=9293 &max_records=1000&outputformat=CSV&action=Search

  • Search HST as above, but return results in VOTable format (Try it)
    https://archive.stsci.edu/hst/search.php?sci_pep_id=9293 &max_records=1000&outputformat=VOTable&action=Search

  • Search the HSC summary table for matchid < 20, return all non-null columns in VOTable format (Try it)
    https://archive.stsci.edu/hst/hsc_sum/search.php?matchid=%3C20 &action=Search&mag_type=xcat.SumMagAper2CatView &remnull=on&outputformat=VOTable&action=Search

  • Search HUT database for observations of M81 and M31, and return only columns for target name and data id: (Try it)
    https://archive.stsci.edu/hut/search.php?action=Search&target=m+81,m+31 &selectedColumnsCsv=hut_target_name,hut_data_id

  • Search for HST ACS data taken with the F814W filter and within the specified search area. Return up to 5000 records containing data set name, RA and Dec in CSV format. (Try it)
    https://archive.stsci.edu/hst/search.php?RA=36.821&DEC=-40.933&radius=30 &sci_spec_1234=*F814*&sci_instrume=ACS&max_records=5000 &selectedColumnsCsv=sci_data_set_name,sci_ra,sci_dec&outputformat=CSV &action=Search

  • Search the ACS Pointings table for the target "M 81" with output format = "CSV", and greater than 2 exposures in the U band: (Try it)
    https://archive.stsci.edu/pointings/search.php?pnt_ucount=%3E2&target=m+81 &primary=ACS&outputformat=CSV&action=Search+Pointings
Notes:
  1. Be sure to include "action=Search" (with capital S) in the mission searches, but not for SCS or SIAP requests.
  2. Parameter order is not important.
  3. For HST searches, sci_aec is set to "S" by default. This will return Science (S) but not Calibration (C) data. If both are desired, add the param sci_aec=%.
  4. Use a comma separated list for selected columns with the selectedColumnsCsv parameter, and specify all column names in lower case. Don't use selectedColumnsList as seen from the search form.
  5. Parameters such as resolver=don'tresolve should probably be encoded to be resolve=don%27tresolve. It seems to work without it though. (See PHP command called urlencode).
  6. There is currently a 300 second execution time limit on archive.stsci.edu which can cause large search requests to abort. Contact MAST if you run into this problem.
  7. Specifying an output format to download results as a file (e.g., outputformat=CSV_File) may avoid browser memory limitations that could cause a large request to fail. This however may require user-interaction.

Simple Cone Search (SCS)

MAST missions can also be searched using the Simple Cone Search protocol (SCS). The base url is the same as for MAST mission searches (i.e., https://archive.stsci.edu/[data_set]/search.php) without the "action=Search" parameter. The search radius parameter "SR" must be included in the URL for the cgi script to recognize a simple cone search is being requested. Besides the search radius in decimal degrees, RA and DEC parameters are also required to perform a cone search. The results are returned in VOTable format. The SCS protocol can be used with any MAST mission and the general MAST parameters can be included as well. Examples:
  • Find archived Kepler observations at RA,Dec = 290.985,43.388 and a search radius = 0.02 degrees (try it) (Note not all listed data sets may be public, see release date field.)
    https://archive.stsci.edu/kepler/data_search/search.php?RA=290.985&DEC=43.388&SR=0.02

  • To search the Hubble Source Catalog (HSC) Summary table at RA,Dec = 53.084,-27.873 with a search radius = 0.01 degrees (returns about 200 entries) (try it)
    https://archive.stsci.edu/hst/hsc_sum/search.php?RA=53.084&DEC=-27.873&SR=0.01
    To do the same search on the HSC Detailed Search, use: (try it)
    https://archive.stsci.edu/hst/hsc/search.php?RA=53.084&DEC=-27.873&SR=0.01

  • This example will return about 50 HST observations (in VOTable format) at RA,Dec = 53.084,-27.873 and a search radius = 0.01 degrees (try it)
    https://archive.stsci.edu/hst/search.php?RA=53.084&DEC=-27.873&SR=0.01

  • Same as above except use a larger search radius (0.02) but only allow a maximum of 100 records to be returned (try it)
    https://archive.stsci.edu/hst/search.php?RA=53.084&DEC=-27.873&SR=0.02&max_records=100

  • To find all high level science products at the same coordinates: (try it)
    https://archive.stsci.edu/hlsp/search.php?RA=53.084&DEC=-27.873&SR=0.01

Simple Image Access Protocol (SIAP)

Many MAST missions and High Level Science Products (HLSPs) can also be searched using the Simple Image Access protocol (SIAP). The base URL is
https://archive.stsci.edu/siap/search.php
followed by the SIAP parameters. There are two exceptions. Tthe HST Press Release images SIAP service which has a base url:
https://archive.stsci.edu/stpr/vo_search.php
and the GOODS cutout service which has the base url:
https://archive.stsci.edu/eidol.php
By default, up to 2000 entries will be returned but specifying max_records=nnn can override the default. Adding the parameter "representative=y" will return only "representative" images as defined for the MAST scrapbook tool. Note some missions and particularly HLSPs, cover small areas of the sky. Currently the list of instruments, and High Level Science Products (HLSPs) that can be queried using the SIAP include:
  • WFPC - HST Wide Field Planetary Camera
  • WFPC2 - HST Wide Field Planetary Camera 2
  • NICMOS - HST Near Infrared Camera and Multi Object Spectrometer
  • STIS - Space Telescope Imaging Spectrograph
  • FOC - HST Faint Object Camera
  • ACS - HST Advance Camera Survey
  • UIT - Ultraviolet Imageing Telescope
  • VLA-FIRST - VLA Faint Images of the Radio Sky at 20 cm
  • AL218 - VLA Array AL218 Texas Survey Source Snapshots
  • UDF - HLSP Ultra Deep Field
  • UDFUV - HLSP Ultraviolet Images of Ultra Deep Field
  • HDF - HLSP Hubble Deep Field
  • HDF_SOUTH - HLSP Hubble Deep Field South
  • GOODS - HLSP The Great Observatories Origins Deep Survey
  • TNO - HLSP trans-Neptunian objects
  • HELIX - HLSP HST Helix Observations
  • MAOZ_ATLAS - HLSP HST Atlas of Ultraviolet Images of Nearby Galaxies
  • CANDELS - Cosmic Assembly Near-IR Deep Extragalactic Legacy Survey
  • STPR - HST Press Release Images 2008 - 2010 (see note above)
  • ANGRRR - Archive of Nearby Galaxies: Reduce, Reuse, Recycle (ANGRRR)
  • ACSGGCT - ACS Galactic Globular Cluster Survey (ACSGGCT)
  • ANDROMEDA - Deep Optical Photometry of Six Fields in the Andromeda Galaxy
  • HIPPIES - Hubble Infrared Pure Parallel Imaging Extragalactic Survey (HIPPIES)
  • CLASH - Cluster Lensing And Supernova survey with Hubble (CLASH)
  • COMA - HST ACS Coma Cluster Treasury Survey
  • APPP - HST Archive Pure Parallels
  • 3CR - The revised 3C catalogue (3CR, Bennett 1962)
  • ANGST - HST ACS Nearby Galaxy Survey (ANGST)
  • SGAL - HST WFPC2 Spiral Galaxies
  • M51 - HST ACS mosaic images of M51
  • M82 - HST multicolor ACS mosaic images of M82
  • GALEX_ATLAS - GALEX atlas of Nearby Galaxies
  • HERITAGE - HST Heritage Press Release Images
  • COSMOS - HST Cosmic Evolution Survey
  • GEMS - HST Galaxy Evolution from Morphology and SEDs
  • PHAT - Panchromatic Hubble Andromeda Treasury (PHAT)
  • HUDF09 - Hubble Ultra Deep Field 2009 (HUDF09)
SIAP Examples:
  • Search for HST press release images at RA=149.0, Dec=69.0 within a
    5 degree search area: (Try it)
    https://archive.stsci.edu/stpr/vo_search.php?pos=149.0,69.0&size=5.0

  • Search for MAST images (other than HST PR images) at RA+151.0, Dec=+69.0 and a search area of 0.5 degrees: (Try it)
    https://archive.stsci.edu/siap/search.php?POS=151.0,69.0&SIZE=0.5

  • Display supported SIAP parameters: (Try it)
    https://archive.stsci.edu/siap/search.php?format=metadata

  • Find WFPC2 observations at RA,Dec = 53.084,-27.873, format = GIF, and a rectangular search area 0,05 degrees wide: (Try it)
    https://archive.stsci.edu/siap/search.php?POS=53.08,-27.873 &SIZE=0.05&FORMAT=gif&ID=wfpc2

  • Find "representative" WFPC2 observations as above: (Try it)
    https://archive.stsci.edu/siap/search.php?representative=y&POS=53.08,-27.873 &SIZE=0.05&FORMAT=gif&ID=wfpc2

  • Search for data from the HIPPIES HLSP: (Try it)
    https://archive.stsci.edu/siap/search.php?ID=HIPPIES&pos=95.952,-64.665&size=0.05

  • Create cutouts from the GOODS HLSP images at ra,dec of 189.194,62.159 with a width of about 4": (Try it)
    https://archive.stsci.edu/eidol.php?pos=189.194,62.159&size=0.001


Simple Spectral Access Protocol (SSAP)

MAST spectral missions can now be searched using the VO Simple Spectral Access Protocol (SSAP). It is similiar to the SIAP standard in that it returns a VOTable-format file with links to (spectral) data sets. Note the MAST SSAP services, like the SIAP and cone search services, were written using VOTable version 1.0 and are now (hopefully) updated to version 1.1. The latest VOTable standard however is version 1.3. All the VO standards (e.g., VOTable, SSAP, SIAP, etc.) evolve independently.

The current list of missions with SSAP services include:

  • fos
  • ghrs
  • stis
  • hst (to include all instruments)
  • iue
  • hut
  • euve
  • fuse
  • wuppe
  • befs
  • tues
  • hpol

The SSAP standard itself has evolved over the last several years, and the MAST services have not been updated for ahwhile. There were 2 main versions implemeted so far:

  • The original standard, known as version 0.4 in the VAO registry, was never officially approved but was adopted by several data centers before the official version was available. We were supporting SSAP version 0.4 services up until last year for HUT, FUSE, EUVE, WUPPE, IUE, HPOL, and HST.
  • The first officially-approved standard is now available and is known as version 1.0 (actually the latest version is 1.1?). Currently all MAST spectral missions support version 1.02. (see SSAP paper and Spectral Data Model papers for description of protocol).

The examples below describe version 1 services.

SSAP Examples:

  • Search for FUSE spectra at RA+151.0, Dec=+69.0 and a search area of 2.0 degrees: (Try it)
    https://archive.stsci.edu/ssap/search2.php?id=FUSE&POS=151.0,69.0&SIZE=2.0

  • Search all MAST spectral missions for spectra of the planet Mars: (Try it)
    https://archive.stsci.edu/ssap/search2.php?targetname=mars

  • Display all spectra with an object name of gamma * and display the results as an HTML table: (Try it)
    https://archive.stsci.edu/ssap/search2.php?targetname=gamma*&outputformat=HTML_Table

  • Search for all MAST spectra at RA+151.0, Dec=+69.0 and a search area of 0.5 degrees: (Try it)
    https://archive.stsci.edu/ssap/search2.php?POS=151.0,69.0&SIZE=0.5

  • Display supported SSAP parameters: (Try it)
    https://archive.stsci.edu/ssap/search2.php?format=metadata

  • Search for FOS spectra at RA+151.0, Dec=+69.0 and a search area of 2.0 degrees: (Try it)
    https://archive.stsci.edu/ssap/search2.php?id=FOS&POS=151.0,69.0&SIZE=2.0

RSS Services

We currently have two RSS services: the RSS news service, and the HST Press Release images service. The first examples show how to list our most recent news items in either HTML or RSS XML-format:
  • https://archive.stsci.edu/mast_news.php?out=html&desc=t&last=10
    shows last 10 entries (by date) in html with descriptions (Try it)
  • https://archive.stsci.edu/mast_news.php?desc=t&last=10
    shows same in rss xml format (Try it)
  • https://archive.stsci.edu/mast_news.php?out=html&last=10
    summary in html of last 10 (no descriptions) (Try it)
  • https://archive.stsci.edu/mast_news.php?out=html&id=25
    show entry 25 in html (Try it)
Here are examples using the HST press release RSS service:
  • https://archive.stsci.edu/stpr/search.php?ra=149.0&dec=69.0&radius=300&action=Search&outputformat=RSS
    Find press release images within a 300 arcminute circle of RA,Dec 149.0,69.0 (Try it)

  • https://archive.stsci.edu/stpr/search.php?action=Search&format=image/tiff&outputformat=RSS
    Find all press release images available in tiff format (Try it)

Other Services

There is currently a service to return footprints using the VO STC-S convention. It returns a simple xml file. The service accepts 2 parameters, 'dsn' for specifying the MAST data set name, and 'table' for specifying the source of the footprint. Valid table values currently include caom, obscore_images, and obscore. The CAOM is the most complete source. Note that CAOM footprints repeat the first vertice at the end of the list, so for example, a rectangular footprint will be described with 5 vertices.
  • https://archive.stsci.edu/footprint.php?dsn=z3ddb205t&table=caom
    To retrieve the GHRS footprint for z3ddb205t from the CAOM table (Try it)

SOAP Services

We have one SOAP-based web service which is accessed via the ADS. The web service allows users to enter a data set name and find where it is archived. The service can be accessed from the web form at:
http://ads.harvard.edu/ws/DataVerifier, or, using the latest ADEC naming conventions:
http://vo.ads.harvard.edu/dv/DataVerifier.cgi