Querying for and Downloading IRSA Images

IRSA offers several program interfaces for querying and downloading images from our holdings. A brief description of each is provided below, along with links to detailed instructions and examples.

Primary Image API
Image Access with Python
Additional Image APIs

Primary Image API

API	Data Sets Available	IVOA Standard	Spatial Queries?	Relational Queries (SQL)?	Output Formats	Method for Downloading Images
Simple Image Access v2 (info)	Most Image Inventories	SIA v2	yes	no	FITS, IPAC_TABLE, HDF5, VOTABLE, JSON, CSV, TSV, TEXT, HTML, POSTGRES, SQLITE, ORACLE, DB	URL in results

Primary Image API: Simple Image Access Version 2 (SIA v2)

SIA v2 is a specification created by the International Virtual Observatory Alliance (IVOA) to standardize image searches and is supported for most imaging data sets stored at IRSA. SIA v2 allows for programmatic image searches with a variety of possible query constraints (e.g., position, wave band) using a set of parameters common across all data sets. To use a SIA v2 service, construct a query URL that specifies your search parameters and submit the query from the command line or within a script. The service will return access URLs for the images that meet your search constraints. The full syntax of SIA v2 queries is described here.

Image Access with Python

IRSA's SIA v2 service can also be accessed from Python using the astroquery function query_sia. This function returns a table of images that meet the search criteria, which can then be downloaded, opened on-the-fly, or used to extract cutouts (without downloading the full image).

Several Jupyter Notebooks have been created to demonstrate searches of IRSA's image and catalog inventories, as well as IRSA-curated datasets available in Amazon Web Service (AWS) cloud storage buckets. Interested users are encouraged to read through the tutorials for techniques and tips.

Additional Image Access APIs

IRSA provides numerous other APIs to access our image inventories. These services, listed below, include previous implementations of the Simple Image Access API, image cutout services, mission-specific tools, and a general purpose Table Access Protocol API. Whenever possible, new queries should be written with our Simple Image Access Version 2 (SIA v2) API.

API	Data Sets Available	IVOA Standard	Spatial Queries?	Relational Queries (SQL)?	Output Formats	Method for Downloading Images
Simple Image Access v1 (info)	WISE, 2MASS, PTF	SIA v1	yes	no	FITS, IPAC_TABLE, HDF5, VOTABLE, JSON, CSV, TSV, TEXT, HTML, POSTGRES, SQLITE, ORACLE, DB	URL in results
IRSA Image Server API (info)	WISE, 2MASS, PTF	---	yes	yes	FITS, IPAC_TABLE, HDF5, VOTABLE, JSON, CSV, TSV, TEXT, HTML, POSTGRES, SQLITE, ORACLE, DB	must be constructed from output
Image Cutouts API (info)	WISE, 2MASS, PTF	---	no	no	FITS	URL in results
2MASS Image Service API (info)	2MASS	SIA v1	yes	no	XML	URL in results
WISE Image Service API (info)	WISE/NEOWISE	---	yes	no	HTML	web page
Spitzer Heritage Archive API (info)	Spitzer	---	yes	no	HTML	web page
Finder Chart API (info)	DSS, 2MASS, SDSS, WISE, IRAS, SEIP, AKARI	---	yes	no	XML, HTML, FITS, PNG, PDF	directly from API; URL in results; web page
Atlas Image API (info)	Atlas datasets	---	yes	no	XML, HTML	script provided in output
Atlas Image Cutouts API (info)	Atlas datasets	---	yes	no	XML, HTML	script provided in output
Table Access Protocol (info)	Entire IRSA Inventory	TAP	yes	yes	FITS, IPAC_TABLE, VOTABLE, CSV, TSV, HTML	table dependent

Simple Image Access Version 1 (SIA v1)

This service is based on an older set of SIA protocols and is limited to the WISE/NEOWISE, 2MASS, and PTF datasets. It allows for only position-based searches to a single table. The IRSA SIA v1 search service has been superseded by the SIA v2 service.

IRSA Image Server API

This service is similar to SIA v1, but expands on the features by allowing users to define which columns they would like returned and to submit SQL-like search clauses. The IRSA Image Server API is limited to the same datasets as the IRSA SIA v1 service. The IRSA TAP service replicates most of the features included here, but has expanded search capabilities and can access any IRSA catalog table.

Image Cutouts API

This service provides a method to retrieve cutouts of WISE, 2MASS, and PTF images discovered through the SIA v1 and Image Server APIs.

2MASS Image Server API

The 2MASS Image Services API is an SIA v1-compliant API specifically for 2MASS images. Images and their associated artifacts can be downloaded programmatically with this service. This service differs from SIA v1 in that it includes for several 2MASS-specific search criteria, such as the hemisphere of the observatory and the scan number of the images. Results are restricted to the VO Table format.

WISE Image Service API

This is an API specific for the WISE Image Service. This API constructs a URL that launches an instance of the WISE Image Service in a browser. The query may or may not be executed according to the parameters passed to the API.

Spitzer Heritage Archive API

An API specific for the Spitzer Heritage Archive that allows for searches by position, program, AORKEY, and NAIFID. This API constructs a URL that launches an instance of the SHA in a browser and, therefore, cannot be used completely programmatically to download data.

Finder Chart API

The Finder Chart API provides a programmatic method for interacting with the Finder Chart service. The results of queries to this API can provide links to files for downloading, can launch the web version of Finder Chart with the results, or can allow direct downloads of the images.

IRSA's implementation of the International Virtual Observatory Alliance (IVOA) Table Access Protocol (TAP) offers program-friendly access to all of our tables. Although TAP is very flexible in its capabilities, most users may find our other APIs easier to use for image queries.