HEASoft and XSPEC are now available as conda packages. See details ....
How to Query VO-enabled Services
There are a number of programmatic ways to work with the VO protocols. One client that we recommend is the Astropy-affiliated Python package called PyVO. There is plenty of help on its documantion site, but we also provide a set of Jupyter notebooks that we use in workshops to teach how to do multi-mission science using PyVO.
But if you want to know how to call VO services directly, the below gives an overview and links for more information. These VO services are web APIs that you can use within your software. All you need to know is the base URL of the service you are interested in and the parameters the service uses.
Finding services
One of the hardest parts of implementing the VO idea is making it easier to locate the services you might want. The VO created the Registry standard, which is best used through a client like PyVO or a web interface. The NAVO collaboration include such a web search interface at STScI. Here's how to use it.
Step 1: Go to the STScI registry.
Step 2: To search for HEASARC services, select 'Id' from the 'All Fields' drop down and enter "nasa.heasarc" in the search box.
Step 3: Now you can browse a list of resources provided at the HEASARC, or more likely, add some search terms to narrow it down to the one(s) you are interested in. HEASARC services are registered by dataset, so you search for the data you want and then look at the API options for retrieving it. Alternatively, if you know the type of service you need, you can narrow the results. For example:
Step 4: Open the 'Capability Type' drop down option. You will get a list of the various capabilities at the HEASARC related to the given dataset, and the types of services are described below. Select the type of service to see a list of those services at the HEASARC.
Step 5: Now select, for example, the first listed dataset. You will go to a page containing a lot of information on the selection.
Step 6: Under 'Available Service Interfaces' click on 'Simple Cone Search'. Alternatively, if you are looking for a different way to access the same data, look for the options here. You will see a serviceURL under 'Available endpoints for the standard interface'. The service URL is the base of the API interface. You then add parameters depending on which type, as described below.
Simple Table Searches
The Simple Cone Search (SCS) service allows a user to get a subset of a catalog only by specifying center coordinates and a search radius. Once you have the base URL, you can construct a URL containing RA, Dec, and search radius. The format should be "RA=xx&DEC=yy&SR=zz" where xx,yy,and zz are the RA, Dec, and search radius respectively. The response is a VOTable with the columns of that table that match the spatial parameters. If you run your query in a browser. You will see the response in XML format containing data on targets inside the search radius.
XML isn't great to look at, but clients like PyVO know how to turn them into user-friendly Astropy Tables.
Image Services
Likewise, the Simple Image Access (SIA) enables searches for images in a region of the sky. The response depends on the service. The HEASARC has two kinds of SIA services. The Xamin SIA serves images that exist on the archive in the mission data products. The SkyView SIA is very different. It has a wide variety of multiwavelength full-sky imaging data and will construct a cutout or mosaic on the fly according to the center point and size you specify. But both are queried the same way.
Example:Your are interested in SFD IR and Dustmap Surveys for M20. You need to find the service URL for the SFD survey and, after querying the registry,you find the base URL is:
https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?survey=sfd&
Now append a set of coordinates and a search radius to the above base URL. The syntax is "POS=RA,DEC&SIZE=SR". For M20, the RA and Dec in decimal degrees in J2000 are: RA=270.67 and Dec=-22.97. A complete query might look something like:
https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?survey=sfd&POS=270.67,-22.97&SIZE=3
After running this query, you will get a VOTable that contains a number of links and metadata describing the matching images and how to fetch them.
Note that in the case of SkyView, the image is created on the fly to be the position and size you specify. For Xamin, it fetches the archived mission product. So the final URLs will also look very different. Also, Xamin services use the DataLink step as described next.
Spectra Services
The query is very similar to an SIA query. Follow the same proceedure to get the base URL for a HEASARC SSA service. Follow steps 1-3 for retrieving a SSA URL and then proceed with the following steps:
Example:
You are interested in Chandra data for 3c273. Follow the steps above, select "Chandra Observations", cut and paste the SSA base URL and append the coordinates for 3c273. In this case, a complete URL might look like:
https://heasarc.gsfc.nasa.gov/xamin/vo/ssa?table=chanmaster&POS=187.27,2.05&SIZE=.01&REQUEST=queryData
Xamin use a more modern workflow, for a number of IVOA reasons, which has an extra step. The search result has URLs that are "DataLink" URLs as indicated by the format column. Select the one you want, call the DataLink URL, and you will get back another VOTable that has the URL to the image itself as well as any related products the service offers. The main object of interest can be selected by the values in the semantics and format columns, e.g., "#this" for the main result, and "application/fits" for a FITS format. The other rows are products offered as related to your image, such as "#cutout" or "#calibration". So first you get
https://heasarc.gsfc.nasa.gov/xamin/vo/datalink?datalink_key&id=ivo://nasa.heasarc/chanmaster?7365/chandra.obs.pha
and at the next level you get this:
https://heasarc.gsfc.nasa.gov/FTP/chandra/data/byobsid/5//7365/primary/acisf07365N003_pha2.fits.gz
You can then download your FITS file from the above URL.
Complex tabular operations
The Cone Search only allows you to retrieve data based on coordinates and a radius. But many users need more complicated searches, for example specifying a constraint on one of the table's other column values, or a cross-match between two different tables. These types of queries must be expressed in the ADQL dialect of SQL. The basic usage is as above: find the base URL in the registry and then add your search expression as a long string to the query parameter.
The HEASARC tables are all available under the same URL endpoint. It's in the query itself that you specify the table(s) you want. The current base URL is:
https://heasarc.gsfc.nasa.gov/xamin/vo/tap
You can do a few things with this endpoint. If you append '/tables' to this URL, you will get the (long) list of available tables. If you append '/examples' you'll see some examples ADQL queries that you can learn from and adapt. For other types of queries that can be performed please refer to the TAP standard. Queries are best shown with examples. For instance, this query searches for observations common to the rostmaster catalog AND the chanmaster catalog with a minimum exposure of 10ks.
SELECT * FROM rosmaster as ros INNER JOIN chanmaster as chan ON ros.name = chan.name WHERE ros.exposure > 10000 and chan.exposure > 10000 ORDER by ros.exposure
To send that query, the URL is constructed from the base and a few other fields:
https://heasarc.gsfc.nasa.gov/xamin/vo/tap/sync?REQUEST=doQuery&LANG=ADQL&QUERY=%27SELECT%20*%20FROM%20rosmaster%20as%20ros%20INNER%20JOIN%20chanmaster%20as%20chan%20ON%20ros.name%20=%20chan.name%20WHERE%20ros.exposure%20%3E%2010000%20and%20chan.exposure%20%3E%2010000%20ORDER%20by%20ros.exposure%27
The result is a VOTable containing the matching tabular data as in a Cone search.