Skip to main content

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.