astro query:docs

- Index
- Modules

### Navigation

- next »
- astroquery v0.4.11 »

# Astroquery

This is the documentation for the Astroquery coordinated package of astropy.

Code and issue tracker are on GitHub.

If you use astroquery, please cite the paper Ginsburg, Sipőcz, Brasseur et al 2019.

## Introduction

Astroquery is a set of tools for querying astronomical web forms and databases.

There are two other packages with complimentary functionality as Astroquery: pyvo is an Astropy affiliated package, and Simple-Cone-Search-Creator to generate a cone search service complying with the IVOA standard. They are more oriented to general virtual observatory discovery and queries, whereas Astroquery has web service specific interfaces.

## Installation

Uniquely in the Astropy ecosystem, Astroquery is operating with a continuous deployment model. It means that a release is instantaneously available after a pull request has been merged. These releases are automatically uploaded to PyPI, and therefore the latest version of astroquery can be pip installed. The version number of these automated releases contain the `'dev'` tag, thus pip needs to be told to look for these releases during an upgrade, using the `--pre` install option. If astroquery is already installed, please make sure you use the `--upgrade` (or `-U`) install option as well.

    $ python -m pip install -U --pre astroquery

To install all the mandatory and optional dependencies add the `[all]` identifyer to the pip command above (or use `[docs]` or `[test]` for the dependencies required to build the documentation or run the tests):

    $ python -m pip install -U --pre astroquery[all]

In addition to the automated releases, we also keep doing regular, tagged version for maintenance and packaging purposes. These can be `pip` installed without the `--pre` option and are also available from the `conda-forge` conda channel.

    $ conda install -c conda-forge astroquery

To review recent changes and fixes, please have a look at the changelog:

- Full Changelog

### Building from source

The development version can be obtained and installed from github:

    $ # If you have a github account:
    $ git clone git@github.com:astropy/astroquery.git
    $ # If you do not:
    $ git clone https://github.com/astropy/astroquery.git
    $ cd astroquery
    $ python -m pip install .

To install all the optional dependencies (listed below), add the option `[all]`. To install dependencies required for running the tests locally use `[test]`, and for documentation build `[docs]`. If you would like to modify the source, you can install `astroquery` in editable mode, which means you don’t need to rerun the install command after you made the changes.

To install all dependencies, including those required for local testing and building the documentation, in editable mode:

    $ python -m pip install -e .[all,test,docs]

## Requirements

Astroquery works with Python 3.9 or later.

The following packages are required for astroquery installation & use:

- numpy >= 1.20

- astropy (>=5.0)

- pyVO (>=1.5)

- requests

- keyring

- Beautiful Soup

- html5lib

and for running the tests:

- curl

- pytest-astropy

- pytest-rerunfailures

The following packages are optional dependencies and are required for the full functionality of the `mocserver`, `alma`, and `xmatch` modules:

- astropy-healpix

- regions

- mocpy >= 0.9

For the `vamdc` module:

- vamdclib install version from personal fork: `python -m pip install git+https://github.com/keflavich/vamdclib-1.git`

The following packages are optional dependencies and are required for the full functionality of the `mast` module:

- boto3

## Using astroquery

All astroquery modules are supposed to follow the same API. In its simplest form, the API involves queries based on coordinates or object names. Some simple examples, using SIMBAD:

    >>> from astroquery.simbad import Simbad
    >>> result_table = Simbad.query_object("m1")
    >>> result_table.pprint()

main_id ra dec coo_err_maj coo_err_min coo_err_angle coo_wavelength coo_bibcode matched_id

  deg deg mas mas deg

——- ——- ——- ———– ———– ————- ————– ——————- ———-

  M 1 83.6324 22.0174 5000.0 5000.0 90 X 2022A&A…661A..38P M 1

All query tools allow coordinate-based queries:

    >>> from astropy import coordinates
    >>> import astropy.units as u
    >>> c = coordinates.SkyCoord("05h35m17.3s -05d23m28s", frame='icrs')
    >>> r = 5 * u.arcminute
    >>> result_table = Simbad.query_region(c, radius=r)
    >>> result_table.pprint(show_unit=True, max_width=80, max_lines=5)
              main_id                  ra       ...     coo_bibcode
                                      deg       ...
    ---------------------------- -------------- ... -------------------
    ALMA J053514.4142-052220.792  83.8100591667 ... 2023MNRAS.522...56V
                             ...            ... ...                 ...
         2MASS J05351163-0522515 83.79846499816 ... 2020yCat.1350....0G
                     [H97b] 9009 83.79990004111 ... 2020yCat.1350....0G
    Length = 3324 rows

For additional guidance and examples, read the documentation for the individual services below.

## Default configuration file

To customize this, copy the default configuration to `$HOME/.astropy/config/astroquery.cfg`, uncomment the relevant configuration item(s), and insert your desired value(s).

- Default Configuration

## Caching

By default Astroquery employs query caching with a timeout of 1 week. The user can clear their cache at any time, as well as suspend cache usage, and change the cache location. Caching persists between Astroquery sessions. If you know the service you are using has released new data recently, or if you believe you are not receiving the newest data, try clearing the cache.

### Service specific settings

The Astroquery cache location is specific to individual services, so each service’s cache should be managed individually. The cache location can be viewed with the following command (using VizieR as an example):

    >>> from astroquery.vizier import Vizier
    >>> print(Vizier.cache_location)
    /Users/username/.astropy/cache/astroquery/Vizier

Each service’s cache is cleared with the `clear_cache` function within that service.

    >>> import os
    >>> from astroquery.vizier import Vizier
    ...
    >>> os.listdir(Vizier.cache_location)
    ['8abafe54f49661237bdbc2707179df53b6ee0d74ca6b7679c0e4fac0.pickle',
    '0e4766a7673ddfa4adaee2cfa27a924ed906badbfae8cc4a4a04256c.pickle']
    >>> Vizier.clear_cache()
    >>> os.listdir(Vizier.cache_location)
    []

### Astroquery-wide settings

Whether caching is active and when cached files expire are controlled centrally through the astroquery `cache_conf` module, and shared among all services. Astroquery uses the Astropy configuration infrastructure, information about temporarily or permanently changing configuration values can be found here.

    >>> from astroquery import cache_conf
    ...
    >>> # Is the cache active?
    >>> print(cache_conf.cache_active)
    True
    >>> # Cache timout in seconds
    >>> print(cache_conf.cache_timeout)
    604800

# Available Services

The following modules have been completed using a common API:

- ALMA Queries (`astroquery.alma`)
- Atomic Line List (`astroquery.atomic`)
- Besancon Queries (`astroquery.besancon`)
- CADC (`astroquery.cadc`)
- CASDA Queries (`astroquery.casda`)
- Cologne Database for Molecular Spectroscopy (CDMS) Queries (`astroquery.linelists.cdms`)
- ESA EUCLID Archive (`astroquery.esa.euclid`)
- ESA Herschel Science Archive (`astroquery.esa.hsa`)
- ESA HST Archive (`astroquery.esa.hubble`)
- ESA Integral Science Legacy Archive (ISLA) (`astroquery.esa.integral`)
- ESA ISO Archive (`astroquery.esa.iso`)
- ESA JWST Archive (`astroquery.esa.jwst`)
- ESA XMM-Newton Archive (`astroquery.esa.xmm_newton`)
- ESASky Queries (`astroquery.esasky`)
- ESO Queries (`astroquery.eso`)
- FIRST Queries (`astroquery.image_cutouts.first`)
- Gaia TAP+ (`astroquery.gaia`)
- GAMA Queries (`astroquery.gama`)
- Gemini Queries (`astroquery.gemini`)
- HEASARC Queries (`astroquery.heasarc`)
- HiPS2fits Service (`astroquery.hips2fits`)
- HITRAN Queries (`astroquery.hitran`)
- IRSA Moving Object Search Tool (astroquery.ipac.irsa.most)
- IRSA Dust Extinction Service Queries (`astroquery.ipac.irsa.irsa_dust`)
- IRSA Image Server program interface (IBE) Queries (`astroquery.ipac.irsa.ibe`)
- IRSA Queries (`astroquery.ipac.irsa`)
- JPL Spectroscopy Queries (astroquery.jplspec)
- MAGPIS Queries (`astroquery.magpis`)
- MAST Queries (`astroquery.mast`)
- CDS MOC Service (`astroquery.mocserver`)
- Minor Planet Center Queries (`astroquery.mpc`/astroquery.solarsystem.MPC)
- NASA ADS Queries (`astroquery.nasa_ads`)
- NED Queries (`astroquery.ipac.ned`)
- NIST Queries (`astroquery.nist`)
- NVAS Queries (`astroquery.nvas`)
- SIMBAD Queries (`astroquery.simbad`)
- Skyview Queries (`astroquery.skyview`)
- Splatalogue Queries (`astroquery.splatalogue`)
- SVO Filter Profile Service Queries (`astroquery.svo_fps`)
- UKIDSS Queries (`astroquery.ukidss`)
- Vamdc Queries (`astroquery.vamdc`)
- VizieR Queries (`astroquery.vizier`)
- VO Simple Cone Search (`astroquery.vo_conesearch`)
- VSA Queries (`astroquery.vsa`)
- xMatch Queries (`astroquery.xmatch`)

These others are functional, but do not follow a common & consistent API:

- ALFALFA Queries (`astroquery.alfalfa`)
- CosmoSim Queries (`astroquery.cosmosim`)
- Exoplanet Orbit Database (`astroquery.exoplanet_orbit_database`)
- Fermi Queries (`astroquery.fermi`)
- JPL Horizons Queries (`astroquery.jplhorizons`/astroquery.solarsystem.jpl.horizons)
- JPL SBDB Queries (`astroquery.jplsbdb`/astroquery.solarsystem.jpl.sbdb)
- LAMDA Queries (`astroquery.lamda`)
- NASA Exoplanet Archive (`astroquery.ipac.nexsci.nasa_exoplanet_archive`)
- OAC API Queries (`astroquery.oac`)
- OGLE Queries (`astroquery.ogle`)
- Open Exoplanet Catalogue(`astroquery.open_exoplanet_catalogue`)
- SDSS Queries (`astroquery.sdss`)

There are also subpackages that serve as the basis of others.

- WFAU Queries (`astroquery.wfau`)

# Catalog, Archive, and Other

A second index of the services by the type of data they serve. Some services perform many tasks and are listed more than once.

## Catalogs

The first serve catalogs, which generally return one row of information for each source (though they may return many catalogs that each have one row for each source)

- ALFALFA Queries (`astroquery.alfalfa`)
- Exoplanet Orbit Database (`astroquery.exoplanet_orbit_database`)
- GAMA Queries (`astroquery.gama`)
- IRSA Dust Extinction Service Queries (`astroquery.ipac.irsa.irsa_dust`)
- IRSA Image Server program interface (IBE) Queries (`astroquery.ipac.irsa.ibe`)
- IRSA Queries (`astroquery.ipac.irsa`)
- MAST Queries (`astroquery.mast`)
- NASA Exoplanet Archive (`astroquery.ipac.nexsci.nasa_exoplanet_archive`)
- NED Queries (`astroquery.ipac.ned`)
- OGLE Queries (`astroquery.ogle`)
- Open Exoplanet Catalogue(`astroquery.open_exoplanet_catalogue`)
- SDSS Queries (`astroquery.sdss`)
- SIMBAD Queries (`astroquery.simbad`)
- UKIDSS Queries (`astroquery.ukidss`)
- VizieR Queries (`astroquery.vizier`)
- VO Simple Cone Search (`astroquery.vo_conesearch`)
- VSA Queries (`astroquery.vsa`)
- xMatch Queries (`astroquery.xmatch`)

## Archives

Archive services provide data, usually in FITS images or spectra. They will generally return a table listing the available data first.

- ALFALFA Queries (`astroquery.alfalfa`)
- ALMA Queries (`astroquery.alma`)
- CADC (`astroquery.cadc`)
- CASDA Queries (`astroquery.casda`)
- ESA HST Archive (`astroquery.esa.hubble`)
- ESA JWST Archive (`astroquery.esa.jwst`)
- ESA XMM-Newton Archive (`astroquery.esa.xmm_newton`)
- ESO Queries (`astroquery.eso`)
- Fermi Queries (`astroquery.fermi`)
- Gaia TAP+ (`astroquery.gaia`)
- Gemini Queries (`astroquery.gemini`)
- HEASARC Queries (`astroquery.heasarc`)
- IRSA Image Server program interface (IBE) Queries (`astroquery.ipac.irsa.ibe`)
- IRSA Queries (`astroquery.ipac.irsa`)
- MAGPIS Queries (`astroquery.magpis`)
- MAST Queries (`astroquery.mast`)
- NED Queries (`astroquery.ipac.ned`)
- NVAS Queries (`astroquery.nvas`)
- SDSS Queries (`astroquery.sdss`)
- Skyview Queries (`astroquery.skyview`)
- UKIDSS Queries (`astroquery.ukidss`)
- VSA Queries (`astroquery.vsa`)

## Simulations

These services query databases of simulated or synthetic data:

- Besancon Queries (`astroquery.besancon`)
- CosmoSim Queries (`astroquery.cosmosim`)

## Line List Services

There are several web services that provide atomic or molecular line lists, as well as cross section and collision rates. Those services are:

- Atomic Line List (`astroquery.atomic`)
- Cologne Database for Molecular Spectroscopy (CDMS) Queries (`astroquery.linelists.cdms`)
- HITRAN Queries (`astroquery.hitran`)
- JPL Spectroscopy Queries (astroquery.jplspec)
- LAMDA Queries (`astroquery.lamda`)
- NIST Queries (`astroquery.nist`)
- Splatalogue Queries (`astroquery.splatalogue`)
- Vamdc Queries (`astroquery.vamdc`)

## Other

There are other astronomically significant services, that don’t fit the above categories. Those services are here:

- Astrometry.net plate solutions (`astroquery.astrometry_net`)
- Institut de Mécanique Céleste et de Calcul des Éphémérides (IMCCE) Solar System Services (`astroquery.imcce`/astroquery.solarsystem.imcce)
- JPL Horizons Queries (`astroquery.jplhorizons`/astroquery.solarsystem.jpl.horizons)
- JPL SBDB Queries (`astroquery.jplsbdb`/astroquery.solarsystem.jpl.sbdb)
- NASA ADS Queries (`astroquery.nasa_ads`)
- NEODyS Queries (`astroquery.solarsystem.neodys`)
- TAP/TAP+ (`astroquery.utils.tap`)

# Topical Collections

Some services focusing on similar topics are also collected in topical submodules:

- Image Cutout Services (`astroquery.image_cutouts`)
- Solar System Services (`astroquery.solarsystem`)

## Developer documentation

The modules and their maintainers are listed on the Maintainers wiki page.

The Astroquery API Specification is intended to be kept as consistent as possible, such that any web service can be used with a minimal learning curve imposed on the user.

- Astroquery API Specification
- Template Module
- Astroquery Testing

The following Astroquery modules are mostly meant for internal use of services in Astroquery, you can use them for your scripts, but we don’t guarantee API stability.

- Astroquery utils (`astroquery.utils`)
- Astroquery query (`astroquery.query`)
- TAP/TAP+ (`astroquery.utils.tap`)

To debug astroquery, logging level can be configured with the following:

    >>> from astroquery import log
    >>> log.setLevel(level)

If `level` is set to `"DEBUG"`, then HTTP requests are logged. If `level` is set to `"TRACE"`, then HTTP requests and responses are logged.

## License

Astroquery is licensed under a 3-clause BSD style license - see Licenses.