Last modified: January 2023

AHELP for CIAO 4.16


Context: Tools::Download


Find, and optionally download, publicly-available Chandra ObsIds from the Chandra archive.


find_chandra_obsid  arg dec [radius] [download] [instrument] [grating]
[detail] [mirror] [verbose]


The find_chandra_obsid tool will find publicly available Chandra data that covers a circular region of sky (a point search can be used by setting the search radius to 0). The download parameter can be used to download the data, or the download_chandra_obsid script can be used.

This tool makes use of the Chandra Footprint Service, which can also be searched using a web browser.

Single argument

When called with a single argument, it is checked to see if it matches an Observation Id (ObsId) value (that is, an integer between 1 and 65535), otherwise it is treated as an object name.


If an integer value is given, then the Chandra Data Archive is searched to find the location of the observation, and this is used in the search (which means that the ObsId will be one of the returned values). If the ObsId is unrecognized by the archive then it is treated as an object name.

You can check the coordinates that are returned for the name by setting the verbose parameter to 2.

Object names

The name resolver at the CADC is used to convert names to a position. If the name contains a space then it must be given surrounded by quotes - e.g. "NGC 1333" - to ensure that the script recognizes it as a single argument.

You can check the coordinates that are returned for the name by setting the verbose parameter to 2.

Solar system objects

The name resolver does not support solar-system objects.

Using a position

If two arguments are given then they are taken to be the Right Ascension and Declination to search about (J2000). A range of formats can be used (which may require surrounding the value in quotes or protecting characters depending on the shell you are using):

unix% find_chandra_obsid 12.3 -1.2
unix% find_chandra_obsid 12:14 "-1 15 23"
unix% find_chandra_obsid "12h 14m 3.2s" "-0d 5'"

If verbose is set to 2 then the script will display the result of the conversion from the input values into decimal degrees.

Selecting instruments

The default search uses all instruments, but you can restrict the results using the instrument parameter, so

unix% find_chandra_obsid m31 instrument=acis
unix% find_chandra_obsid m31 instrument=aciss

searches for all ACIS or just ACIS-S observations of M31.

Selecting gratings

The default search does not filter on the grating; to do so use the grating parameter.

unix% find_chandra_obsid mkn421 grating=letg
unix% find_chandra_obsid perseus grating=any

searches for LETG observations of Markarian 421 and any grating observations of Perseus.

Downloading data

When the download parameter is "none" - which is the default - then a table of values for the matching observations are displayed. If set to "all" then the matching ObsIds are downloaded to the working directory; in this case the information on the matching ObsIds is not given. When set to "ask", you are queried whether to download each ObsId and then the download will take place for the chosen observations.

The data is downloaded to the current working directory and uses the same layout as the download_chandra_obsid script. If the file already exists it will not be over-written, unless the file size is larger than on disk; a smaller value is taken to mean a previous download attempt was interrupted, so it will append to the file.

Unlike download_chandra_obsid, there is no way to select a subset of data to download for each ObsId.

Subsetting the data for download

This script provides limited capabilities for filtering the data, by using the instrument and grating parameters. More complicated filtering can be done by taking advantage of the fact that the screen output of the script can be manipulated using the CIAO command-line tools. For example

unix% find_chandra_obsid 350.86 58.81 > matches.dat
unix% dmlist matches.dat counts
unix% dmlist "matches.dat[time>20,inst=HRC-I][cols obsid]" data,raw
#  obsid
unix% download_chandra_obsid 1505

shows that ObsId 1505 is the only HRC-I observation with an exposure of 20 ks or higher. The download_chandra_obsid tool is then used to download the matching observation.


Example 1

unix% find_chandra_obsid 3040

All observations that overlap the aim point of ObsId 3040 are reported.

Setting the verbose value to 2, or higher, displays the coordinates returned by by the name resolver; for instance

unix% find_chandra_obsid 3040 verbose=2
Looking for position of ObsId 3040
ObsId 3040 status=archived RA=12 01 53.70 Dec=-18 52 35.50
Found ra=180.47375 dec=-18.8765277778
    = 12h 1m 53.7s -18d 52' 35.5"

Example 2

unix% find_chandra_obsid arp244

In this case a name resolver is used to convert the argument into a position, and then all observations which overlap that position are reported. Unfortunately solar system names are not supported.

Setting the verbose value to 2, or higher, displays the coordinates returned by by the name resolver; for instance

unix% find_chandra_obsid arp244 verbose=2
Querying name resolvers for name=arp244
Found ra=180.47208 dec=-18.87694
    = 12h 1m 53.2992s -18d 52' 36.984"

Example 3

unix% find_chandra_obsid 'ARP 244'

If the object name contains spaces then it must be quoted with single or double quotes.

Example 4

unix% find_chandra_obsid 180.47 -18.88

If two arguments are given then the script interpets these as Right Ascension and Declination. This call will find all the publicly-available Chandra observations that overlap the circle with a center at RA of 180.47 degrees and Declination of -18.88 degrees, and a radius of 1 arcminute.

Example 5

unix% find_chandra_obsid 12:1:54 -18:52:36

The script supports the most common formats for specifying RA and Dec. Values that include spaces will need to be quoted to avoid being interpreted as multiple arguments by the shell - e.g.

unix% find_chandra_obsid "12 1 54" "-18 52 36"
unix% find_chandra_obsid "12h 1m 54s" "-18d 52' 36"'"'

Setting the verbose value to 2, or higher, displays the decimal coordinates calculated by the script:

unix% find_chandra_obsid "12h 15m 46s" "-0 0 4" verbose=2
Converting 12h 15m 46s and -0 0 4 to decimal degrees.
-> 183.941666667 -0.00111111111111

Example 6

unix% find_chandra_obsid 180.47 -18.88 detail=obsid

Here we list just the ObsId values for each observation. The detail setting can also be changed to all to get more columns (basically the RA and Dec of the aim point for each observation).

Example 7

unix% find_chandra_obsid 180.47 -18.88 download=ask

Instead of listing all the matches, you will be asked whether to download each ObsId; the output will look something like

There were 7 matching observations:

1/7: Obsid=315 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=73.2 ObsDate=1999-12-01
   PI=Murray Target=NGC 4038/NGC 4039
2/7: Obsid=3040 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=69.9 ObsDate=2001-12-29
   PI=Fabbiano Target=NGC 4038/NGC 4039
7/7: Obsid=3718 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=35.2 ObsDate=2002-07-13
   PI=Fabbiano Target=NGC 4038/NGC 4039

Use h to get help on the download options.

1/7: Obsid=315 Sepn=0.3 Inst=ACIS-S Grat=NONE Exp=73.2 ObsDate=1999-12-01
   PI=Murray Target=NGC 4038/NGC 4039

Download [y, n, q, a, h]: y


The instrument and grating flags can be used to restrict the set of matches, in which case the use of download=all may be appropriate; this downloads all the matching data without asking you for confirmation.

Example 8

unix% find_chandra_obsid 350.86 58.81 instrument=hrc

Here we restrict the search to just HRC observations.

Example 9

unix% find_chandra_obsid 350.86 58.81 radius=0

Here we restrict the search to those observations that overlap the given point, rather than any part of a circle about the point.

Example 10

unix% find_chandra_obsid 'cas a' grating=any

Here we find all the grating observation of Cas A.

Example 11

unix% find_chandra_obsid 12:0 0 radius=60 instrument=hrci grating=letg

The grating and instrument parameters can be combined to restrict, in this case, to HRC-I observations with the LETG, using a search of 1 degree about RA=12:0:0 and a Declination of 0.


name type def min max units reqd
arg string         yes
dec string         yes
radius real 1 0   arcmin  
download string none        
instrument string all        
grating string all        
detail string basic        
mirror string          
verbose integer 1 0 5    

Detailed Parameter Descriptions

Parameter=arg (string required)

RA, ObsId, or name of source

The Right Ascension (J2000) or name of the source.

Many common RA formats can be used, as shown below. Values including a space need to be surrounded by quotes.

If the Dec argument is empty than the value is taken to be wither be an ObsId (if an integer in the range 1 to 65535), or the name of the source and sent to the CADC name resolver. Set verbose to 2 to see the position that is returned.

Not all names can be resolved; for instance solar system objects.

Parameter=dec (string required)

Dec of source

The declination (J2000) of the source. If not given, or set to "", the first argument is taken to be the name or ObsId of the source.

Many common formats can be used, as shown below. Values including a space need to be surrounded by quotes or protetected in some way, depending on your shell:

Parameter=radius (real default=1 min=0 units=arcmin)

Radius for search overlap in arcmin

The search radius around the source to look for overlap with any Chandra observation. A value of 0 means that the search location must lie within the "footprint" of a Chandra observation for it to be returned.

Parameter=download (string default=none)

What ObsIDs should be downloaded?

What should be done with matching ObsIDS?

Value Description
none No data is downloaded. A list of matching observations is displayed to the screen (the detail parameter controls the level of detail).
ask The user is asked whether each matching ObsID should be downloaded.
all All matching ObsIDs are downloaded. Care should be taken here since this can result in a lot of data being downloaded from the archive.

Note that there is no way to restrict the data being downloaded. If you only want a subset of files for each ObsID then use the download_chandra_obsid script once you have found the list of matching ObsID values.

Parameter=instrument (string default=all)

Choice of instrument

The search can be restricted to one or more instruments using this parameter:

Setting Instrument(s)
all No instrument filter is applied.
acis Only ACIS-I or ACIS-S data is returned.
hrc Only HRC-I or HRC-S data is returned.
acisi Only ACIS-I data is returned.
aciss Only ACIS-S data is returned.
hrci Only HRC-I data is returned.
hrcs Only HRC-S data is returned.

Parameter=grating (string default=all)

Choice of grating

The search can be restricted to one or more grating settings using this parameter:

Setting Grating(s)
all No grating filter is applied.
none Only observations with no grating are returned.
letg Only LETG data is returned.
hetg Only HETG data is returned.
any Search for LETG or HETG observations.

Parameter=detail (string default=basic)

Columns to display

This parameter controls the number of columns displayed when the download parameter is "none". The options are:

Setting Columns
basic obsid, sepn, inst, grat, time, obsdate, piname, target
obsid obsid
all obsid, sepn, inst, grat, time, rastr, decstr, obsdate, piname, target, ra, dec

and the description of the columns is given below:

Column Description
obsid The Observation Id for the observation.
sepn The separation, in arcminutes, between the aim point of the observation and the search location.
inst The instrument used in the observation, one of ACIS-S, ACIS-I, HRC-S, or HRC-I.
grat Thr grating used in the observation, one of NONE, LETG, or HETG.
time The exposure time of the observation, in kiloseconds.
rastr The RA of the aim point of the observation, using h:m:s format (J2000).
decstr The Declination of the aim point of the observation, using d:m:s format (J2000).
obsdate The date of the observation. When the detail level is basic then this contains just the day of the observation; the time is included when the detail level is all.
piname The surname of the Principal Investigator for the observation.
target The target name.
ra The RA of the aim point of the observation, in decimal degrees.
dec The Declination of the aim point of the observation, in decimal degrees.

Parameter=mirror (string default=)

Use this instead of the CDA HTTPS site

Please contact the CXC HelpDesk if you want to use this functionality.

Parameter=verbose (integer default=1 min=0 max=5)

Verbose level

If set to 0 then there will be no screen output apart from error messages. The default setting of 1 is intended for most users; a value of 2 will display the position found for the name when the dec argument is empty. Higher levels are mainly useful for debugging (e.g. when reporting a problem to to the CXC HelpDesk).

Parameter handling

This script has a default mode setting of "h", rather than the usual "ql", so that you can say:

unix% find_chandra_obsid 234.568 -23.24
unix% find_chandra_obsid "1h 33m 50s" "30d 39' 40"
unix% find_chandra_obsid m101

without having to be prompted for an declination (when using just a name), or having to clear out previous values. It does mean that it is an error to call the script without either a position or object name on the command line (i.e. you will not be prompted for these arguments).

Use pset if you wish to permanently set options, for instance to set instrument to acis to exclude HRC observations.

Changes in the scripts 4.15.1 (January 2023) release

Improved handling of non-ASCII PI names.

Changes in the scripts 4.14.1 (February 2022) release

The script is better able to cope with running on a system where the openssl library does not have access to SSL certificates.

Changes in the scripts 4.13.0 (December 2020) release

The script should be more robust to changes made to the Chandra Data Archive web site.

Changes in the scripts 4.11.2 (April 2019) release

Support running on some macOS/openSSL systems by catching CERTIFICATE_VERIFY_FAILED errors and falling through to curl or wget in these cases.

Changes in the scripts 4.10.3 (November 2018) release

Fall through to curl or wget for https access to the Chandra Data Archive.

Changes in the scripts 4.10.2 (May 2018) release

Updated to handle the move of the Chandra Footprint Service to a https URL. Unfortunately not all Python builds in the CIAO 4.10 release can handle SSL requests; in these cases the script will attempt to use curl and then wget to access the data. If you are having problems, run with verbose=3 and send the information to the CXC HelpDesk.

Changes in the scripts 4.9.3 (May 2017) release

Updated to use as the default FTP server. Fixed the problem when download=ask is chosen when using Python 3.5.

Changes in the scripts 4.8.1 (December 2015) release

The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.

Changes in the scripts 4.7.1 (December 2014) release

Support for searching by ObsId

If a single argument is given and it is an integer in the range 1 to 65535, then it is first checked against the Chandra Data Archive and, if it matches an existing ObsId, then its position is used, otherwise it is passed to the name server.

Changes in the scripts 4.5.4 (August 2013) release

Support for CDA mirror sites

The mirror parameter and support for the CDA_MIRROR_SITE environment variable has been added to allow data access from a mirror of the Chandra Data Archive site.

Screen output

A minor change to the screen output when no matches are found (the search position is now included in the message).

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.


There are no known bugs for this tool.

See Also

cda_data, cda_search
download_chandra_obsid, download_obsid_caldb, obsid_search_csc, search_csc