Skip to main content

Due to the lapse in federal government funding, NASA is not updating this website. We sincerely regret this inconvenience.

API and Command Line Access

The catalogs and astronomical archives of the HEASARC are accessible through different Application Programming Interfaces (APIs) and Command Line Interfaces (CLI)

  • astroquery

    Heasarc with Astropy/Astroquery

    The astroquery.heasarc queries the main archive and astroquery.skyview queries SkyView imaging.

    astroquery.heasarc
    astroquery.skyview
    astroquery@HEASARC details

  • Virtual Observatory API

    HEASARC data is accessible through the Virtual Observatory (VO) protocols, meaning common queries work at all VO-compatible archives.
    • For simple catalog searches, use Cone
    • To locate imagine data, Simple Image Access (SIA)
    • For spectra, Simple Spectral Access (SSA)
    • For complex catalog searches, use Table Access Protocol (TAP)
    Details of VO APIs ...

  • Custom APIs

    The XAMIN catalog and archive interface allows users to query the HEASARC catalogs, plot the results and download the the associated data products. It includes both a web API and a Command Line interface.
    • The command line interface runs like
      runquery key1=value1 key2=value2
    • The corresponding web interface is:
      https://heasarc.gsfc.nasa.gov/xamin/query?key1=value1&key2=value2
    Details of Custom APIs ...

  • Command-line downloads

    For downloading lots of data with a batch of requests from the command line, we provide a convenient Perl script to manage the downloads for you. We also have tips on using wget and curl in your own scripts.
    Command line downloads

About Astroquery at HEASARC

Warning:

The released version of astroquery.skyview is currently broken. (We had a DOS attack and had to block the protocol the last astroquery released was incorrectly using.) The fix is to download and install the current but not-yet-released version:

pip install git+https://github.com/astropy/astroquery.git

The HEASARC now supports access to the archive products through the open source astroquery package. There are two modules that we now maintain: astroquery.heasarc module (version >= 0.4.8) and astroquery.skyview. Examples include the following code snippet that shows how to use astroquery.heasarc to locate and download data for a specific source and a specific mission:

from astroquery.heasarc import Heasarc # Look at the catalogs available: catalogs = Heasarc.list_catalogs(master=True) # the user selects a catalog for NuSTAR data, numaster. Then: from astropy.coordinates import SkyCoord position = SkyCoord.from_name('ngc 3783') table = Heasarc.query_region(position, catalog='numaster') # When you have constrained the results, download the data: links = Heasarc.locate_data(table) Heasarc.download_data(links)

As you can see, some knowledge of the HEASARC structure helps, but there is also a lot in the module documentation.

Another example fetching imaging data from SkyView. This service uses full-sky or large survey data to generate custom images on the fly. An example of using it might look like:

from astroquery.skyview import SkyView SkyView.list_surveys() # User selects a survey, then: images = SkyView.get_images(position='Eta Carinae', survey=['Fermi 5', 'HRI', 'DSS'], scaling='log', pixels=512, width=1) # which downloads the data. Then look at one: import matplotlib.pyplot as plt plt.imshow(images[2][0].data)

See the astroquery documentation for astroquery.heasarc and astroquery.skyview for more details.