0
# Astroquery
1

2
A comprehensive Python library providing unified access to astronomical data resources and web services. Astroquery contains a collection of tools organized into sub-modules, each designed to interface with specific astronomical databases and web services such as SIMBAD, ALMA, ESO, CDS, and many others, enabling astronomers and researchers to programmatically retrieve data from dozens of astronomical archives and catalogs.
3

4
## Package Information
5

6
- **Package Name**: astroquery
7
- **Language**: Python
8
- **Installation**: `pip install astroquery`
9
- **Dependencies**: astropy, requests, beautifulsoup4, html5lib, keyring, pyvo
10

11
## Core Imports
12

13
```python
14
import astroquery
15
```
16

17
Common service imports:
18

19
```python
20
from astroquery.simbad import Simbad
21
from astroquery.vizier import Vizier
22
from astroquery.gaia import Gaia
23
from astroquery.alma import Alma
24
from astroquery.mast import Observations, Catalogs
25
```
26

27
## Basic Usage
28

29
```python
30
from astroquery.simbad import Simbad
31
from astroquery.vizier import Vizier
32
import astropy.units as u
33
from astropy.coordinates import SkyCoord
34

35
# Query SIMBAD for object information
36
result = Simbad.query_object('M1')
37
print(result['main_id', 'ra', 'dec'])
38

39
# Query VizieR catalogs around a position
40
coords = SkyCoord('05h35m17.3s -05h23m28s', frame='icrs')
41
result = Vizier.query_region(coords, radius=2*u.arcmin)
42

43
# Query Gaia for sources in a region
44
result = Gaia.query_object(coords, radius=1*u.deg)
45
print(f"Found {len(result)} sources")
46
```
47

48
## Architecture
49

50
Astroquery follows a consistent architecture across all service modules:
51

52
- **Base Classes**: `BaseQuery` for standard HTTP queries, `BaseVOQuery` for Virtual Observatory services, `QueryWithLogin` for authenticated services
53
- **Service Classes**: Each astronomical service (SIMBAD, Vizier, etc.) implements a service-specific class
54
- **Common Patterns**: All services support `query_object()` and `query_region()` methods with both synchronous and asynchronous variants
55
- **Configuration**: Each service has configurable parameters (server URLs, timeouts, row limits) via astropy's configuration system
56
- **Decorators**: `@async_to_sync` automatically creates synchronous methods from asynchronous implementations
57

58
## Capabilities
59

60
### General Astronomical Databases
61

62
Core astronomical data services including object catalogs, stellar databases, and multi-wavelength surveys that form the foundation of astronomical research.
63

64
```python { .api }
65
# SIMBAD - Astronomical object database
66
from astroquery.simbad import Simbad
67
result = Simbad.query_object(object_name: str, **kwargs)
68
result = Simbad.query_region(coordinates, radius=None, **kwargs)
69

70
# VizieR - Catalog access service  
71
from astroquery.vizier import Vizier
72
result = Vizier.query_object(object_name: str, radius=None, catalog=None, **kwargs)
73
result = Vizier.query_region(coordinates, radius=None, catalog=None, **kwargs)
74

75
# Gaia - European Space Agency's Gaia mission data
76
from astroquery.gaia import Gaia
77
result = Gaia.query_object(coordinate, radius=None, **kwargs)
78
result = Gaia.cone_search(coordinate, radius=None, **kwargs)
79
```
80

81
[General Databases](./general-databases.md)
82

83
### Observatory Archives
84

85
Data archives from major ground-based and space-based observatories providing access to processed observations, raw data, and metadata.
86

87
```python { .api }
88
# ALMA - Atacama Large Millimeter Array
89
from astroquery.alma import Alma
90
result = Alma.query_object(object_name: str, public=True, **kwargs)
91
result = Alma.query_region(coordinates, radius=None, public=True, **kwargs)
92

93
# MAST - Space Telescope Science Institute archives
94
from astroquery.mast import Observations, Catalogs
95
result = Observations.query_object(objectname: str, radius=None, **kwargs)
96
result = Catalogs.query_object(objectname: str, radius=None, catalog="Gsc", **kwargs)
97

98
# ESO - European Southern Observatory
99
from astroquery.eso import Eso
100
result = Eso.query_object(name: str, **kwargs)
101
result = Eso.query_region(coordinates, radius=None, **kwargs)
102
```
103

104
[Observatory Archives](./observatory-archives.md)
105

106
### Space Mission Archives
107

108
Archives from space missions and satellites providing specialized astronomical data including gamma-ray, X-ray, infrared, and ultraviolet observations.
109

110
```python { .api }
111
# ESA - European Space Agency missions
112
from astroquery.esa.jwst import Jwst
113
from astroquery.esa.hubble import Hubble
114
result = Jwst.query_object(name: str, **kwargs)
115
result = Hubble.query_object(name: str, **kwargs)
116

117
# Fermi - Fermi Gamma-ray Space Telescope
118
from astroquery.fermi import Fermi
119
result = Fermi.query_object(object_name: str, energyrange_MeV=(100, 100000), **kwargs)
120
```
121

122
[Space Mission Archives](./space-mission-archives.md)
123

124
### IPAC Services
125

126
Services provided by the Infrared Processing and Analysis Center including infrared surveys, extragalactic databases, and exoplanet archives.
127

128
```python { .api }
129
# IRSA - Infrared Science Archive
130
from astroquery.ipac.irsa import Irsa
131
result = Irsa.query_region(coordinates, catalog=None, spatial="Cone", radius=None, **kwargs)
132

133
# NED - NASA Extragalactic Database
134
from astroquery.ipac.ned import Ned
135
result = Ned.query_object(object_name: str, **kwargs)
136
result = Ned.query_region(coordinates, radius=None, **kwargs)
137

138
# NASA Exoplanet Archive
139
from astroquery.ipac.nexsci.nasa_exoplanet_archive import NasaExoplanetArchive
140
result = NasaExoplanetArchive.query_object(object_name: str, table="pscomppars", **kwargs)
141
```
142

143
[IPAC Services](./ipac-services.md)
144

145
### Spectroscopic Databases
146

147
Specialized databases for atomic, molecular, and spectroscopic data used in astronomical spectroscopy and laboratory astrophysics.
148

149
```python { .api }
150
# Splatalogue - Spectroscopy database
151
from astroquery.splatalogue import Splatalogue
152
result = Splatalogue.query_lines(min_frequency, max_frequency, **kwargs)
153

154
# LAMDA - Leiden Atomic and Molecular Database
155
from astroquery.lamda import Lamda
156
result = Lamda.query(molecule=None, **kwargs)
157

158
# NIST - Atomic spectral lines
159
from astroquery.nist import Nist
160
result = Nist.query(linename: str, **kwargs)
161

162
# Hitran - Molecular absorption database
163
from astroquery.hitran import Hitran
164
result = Hitran.query_lines(molecule_number: int, isotopologue_number: int, **kwargs)
165
```
166

167
[Spectroscopic Databases](./spectroscopic-databases.md)
168

169
### Solar System Services
170

171
Services providing ephemerides, orbital elements, and physical data for solar system objects including planets, asteroids, comets, and spacecraft.
172

173
```python { .api }
174
# JPL Horizons - Ephemerides service
175
from astroquery.jplhorizons import Horizons
176
horizons = Horizons(id='Ceres', location='500', epochs='2023-01-01')
177
result = horizons.ephemerides(**kwargs)
178
result = horizons.elements(**kwargs)
179

180
# JPL Small Body Database
181
from astroquery.jplsbdb import SBDB
182
result = SBDB.query(targetname: str, **kwargs)
183

184
# Minor Planet Center
185
from astroquery.mpc import MPC
186
result = MPC.query_object(target: str, **kwargs)
187
```
188

189
[Solar System Services](./solar-system-services.md)
190

191
### Survey and Image Services
192

193
Services for accessing astronomical survey data, image cutouts, and all-sky survey information across multiple wavelengths.
194

195
```python { .api }
196
# SkyView - All-sky survey images
197
from astroquery.skyview import SkyView
198
result = SkyView.get_images(position, survey: str, **kwargs)
199

200
# HiPS2FITS - Hierarchical Progressive Survey conversion
201
from astroquery.hips2fits import Hips2fitsClass
202
result = Hips2fitsClass.query_with_wcs(hips: str, wcs, **kwargs)
203
result = Hips2fitsClass.query_with_circle(hips: str, center, radius, **kwargs)
204
```
205

206
[Survey and Image Services](./survey-image-services.md)
207

208
### Virtual Observatory Services
209

210
Services implementing Virtual Observatory standards for interoperability, cross-matching, and standardized data access protocols.
211

212
```python { .api }
213
# VO Cone Search
214
from astroquery.vo_conesearch import conesearch
215
result = conesearch(center, radius, **kwargs)
216

217
# Cross-match service
218
from astroquery.xmatch import XMatch
219
result = XMatch.query(cat1, cat2, max_distance, **kwargs)
220
```
221

222
[Virtual Observatory Services](./vo-services.md)
223

224
## Configuration and Utilities
225

226
### Global Configuration
227

228
```python { .api }
229
# Global cache configuration
230
from astroquery import cache_conf
231
cache_conf.cache_timeout = 3600  # seconds
232
cache_conf.cache_active = True
233

234
# Service-specific configuration
235
from astroquery.simbad import conf
236
conf.server = 'simbad.cds.unistra.fr'
237
conf.timeout = 60
238
conf.row_limit = 1000
239
```
240

241
### Common Types and Parameters
242

243
```python { .api }
244
# Common parameter types used across services
245
from typing import Union, Optional, List, Dict, Any
246
from astropy.coordinates import SkyCoord
247
from astropy.units import Quantity
248
from astropy.table import Table
249

250
# Coordinate types
251
coordinates: Union[SkyCoord, str]  # Sky position
252
radius: Union[Quantity, str, None]  # Search radius
253

254
# Common parameters
255
get_query_payload: bool = False    # Return query parameters instead of executing
256
cache: bool = True                 # Enable result caching  
257
verbose: bool = False             # Show detailed output
258

259
# Common return types
260
query_result: Table               # Structured tabular data
261
image_result: List               # FITS image data or file handles
262
```
263

264
## Error Handling
265

266
```python { .api }
267
# Common exceptions
268
from astroquery.exceptions import (
269
    InvalidQueryError,           # Invalid query parameters
270
    TimeoutError,               # Request timeout
271
    LoginError,                 # Authentication failure
272
    NoResultsWarning,           # Query returned no results
273
    TableParseError,            # Data parsing error
274
    RemoteServiceError          # Service unavailable
275
)
276

277
# Usage example
278
try:
279
    result = Simbad.query_object('invalid_object_name')
280
except InvalidQueryError as e:
281
    print(f"Query error: {e}")
282
except TimeoutError as e:
283
    print(f"Request timed out: {e}")
284
```