0
# General Astronomical Databases
1

2
Core astronomical data services that provide access to fundamental astronomical catalogs, object databases, and multi-wavelength surveys. These services form the foundation of astronomical research by offering standardized access to comprehensive stellar, galactic, and extragalactic data.
3

4
## Capabilities
5

6
### SIMBAD - Astronomical Object Database
7

8
SIMBAD (Set of Identifications, Measurements and Bibliography for Astronomical Data) provides comprehensive information about astronomical objects outside our solar system, including identifiers, coordinates, measurements, and bibliographic references.
9

10
```python { .api }
11
from astroquery.simbad import Simbad
12

13
def query_object(object_name: str, *, wildcard: bool = False, criteria=None,
14
                get_query_payload: bool = False, verbose: bool = False) -> Table:
15
    """
16
    Query SIMBAD for information about a specific astronomical object.
17
    
18
    Parameters:
19
    - object_name: Name or identifier of the astronomical object
20
    - wildcard: Enable wildcard matching for object names  
21
    - criteria: Dictionary specifying query criteria/fields
22
    - get_query_payload: Return query parameters instead of executing
23
    - verbose: Show detailed output
24
    
25
    Returns:
26
    Table with object information including coordinates, identifiers, and measurements
27
    """
28

29
def query_objects(object_names: List[str]) -> Table:
30
    """
31
    Query SIMBAD for multiple objects simultaneously.
32
    
33
    Parameters:
34
    - object_names: List of object names or identifiers
35
    
36
    Returns:
37
    Table with information for all queried objects
38
    """
39

40
def query_region(coordinates: Union[SkyCoord, str], radius: Union[Quantity, str] = "2 arcmin", *,
41
                criteria=None, get_query_payload: bool = False) -> Table:
42
    """
43
    Query SIMBAD for objects within a sky region.
44
    
45
    Parameters:
46
    - coordinates: Center coordinates as SkyCoord or string
47
    - radius: Search radius (default: 2 arcmin)
48
    - criteria: Dictionary specifying query criteria/fields
49
    - get_query_payload: Return query parameters instead of executing
50
    
51
    Returns:
52
    Table with objects found in the specified region
53
    """
54

55
def query_objectids(object_name: str) -> Table:
56
    """
57
    Get all known identifiers for an astronomical object.
58
    
59
    Parameters:
60
    - object_name: Name or identifier of the object
61
    
62
    Returns:
63
    Table with all known identifiers and their sources
64
    """
65

66
def query_tap(query: str, **kwargs) -> Table:
67
    """
68
    Execute direct TAP/ADQL queries against SIMBAD database.
69
    
70
    Parameters:
71
    - query: ADQL query string
72
    - **kwargs: Additional TAP service parameters
73
    
74
    Returns:
75
    Table with query results
76
    """
77

78
# Configuration
79
from astroquery.simbad import conf
80
conf.server: List[str]        # SIMBAD mirror servers
81
conf.timeout: int = 60        # Connection timeout in seconds  
82
conf.row_limit: int = -1      # Maximum rows (-1 for unlimited)
83
```
84

85
Usage examples:
86

87
```python
88
from astroquery.simbad import Simbad
89
import astropy.units as u
90
from astropy.coordinates import SkyCoord
91

92
# Query basic object information
93
result = Simbad.query_object('M1')
94
print(result['main_id', 'ra', 'dec'])
95

96
# Query with wildcard matching
97
result = Simbad.query_object('NGC 1*', wildcard=True)
98

99
# Region query around coordinates
100
coords = SkyCoord('05h35m17.3s -05h23m28s', frame='icrs')
101
result = Simbad.query_region(coords, radius=2*u.arcmin)
102

103
# Get all identifiers for an object
104
ids = Simbad.query_objectids('M1')
105
print(ids['id'])
106

107
# Custom SIMBAD fields
108
Simbad.add_votable_fields('flux(B)', 'flux(V)', 'sptype')
109
result = Simbad.query_object('Vega')
110
```
111

112
### VizieR - Catalog Access Service
113

114
VizieR provides access to the most complete library of published astronomical catalogs and data tables available online, with standardized search capabilities across thousands of catalogs.
115

116
```python { .api }
117
from astroquery.vizier import Vizier
118

119
def query_object(object_name: str, radius: Union[Quantity, str] = None, 
120
                catalog: Union[str, List[str]] = None) -> TableList:
121
    """
122
    Query VizieR catalogs around a named object.
123
    
124
    Parameters:
125
    - object_name: Name of the astronomical object
126
    - radius: Search radius around object (default: 2 arcmin)
127
    - catalog: Specific catalog(s) to query (default: all)
128
    
129
    Returns:
130
    TableList containing results from matching catalogs
131
    """
132

133
def query_region(coordinates: Union[SkyCoord, str], radius: Union[Quantity, str] = None,
134
                catalog: Union[str, List[str]] = None) -> TableList:
135
    """
136
    Query VizieR catalogs in a sky region.
137
    
138
    Parameters:
139
    - coordinates: Center coordinates as SkyCoord or string
140
    - radius: Search radius (default: 2 arcmin)
141
    - catalog: Specific catalog(s) to query
142
    
143
    Returns:
144
    TableList with catalog entries in the specified region
145
    """
146

147
def query_constraints(**kwargs) -> TableList:
148
    """
149
    Query catalogs with column value constraints.
150
    
151
    Parameters:
152
    - **kwargs: Column constraints (e.g., Vmag='<10', BV='>0.5')
153
    
154
    Returns:
155
    TableList with entries matching the constraints
156
    """
157

158
def get_catalogs(keywords: Union[str, List[str]]) -> Table:
159
    """
160
    Search for catalogs by keywords.
161
    
162
    Parameters:
163
    - keywords: Keywords to search catalog descriptions
164
    
165
    Returns:
166
    Table with matching catalog information
167
    """
168

169
def find_catalogs(keywords: Union[str, List[str]]) -> Table:
170
    """
171
    Find available catalogs matching keywords.
172
    
173
    Parameters:
174
    - keywords: Search keywords
175
    
176
    Returns:
177
    Table with catalog names and descriptions
178
    """
179

180
# Configuration
181
from astroquery.vizier import conf
182
conf.server: str              # VizieR server URL
183
conf.timeout: int = 60        # Connection timeout
184
conf.row_limit: int = 50      # Default row limit per catalog
185
```
186

187
Usage examples:
188

189
```python
190
from astroquery.vizier import Vizier
191
import astropy.units as u
192
from astropy.coordinates import SkyCoord
193

194
# Set row limit and columns
195
Vizier.ROW_LIMIT = 100
196
Vizier.columns = ['_RAJ2000', '_DEJ2000', 'Vmag']
197

198
# Query around an object
199
result = Vizier.query_object('M1', radius=5*u.arcmin)
200
print(f"Found {len(result)} catalogs")
201

202
# Query specific catalogs
203
result = Vizier.query_object('Polaris', catalog=['2MASS', 'USNO-B1'])
204

205
# Region query with constraints
206
coords = SkyCoord('12h30m', '+41d16m', frame='icrs')
207
result = Vizier.query_region(coords, radius=1*u.deg, 
208
                           catalog='2MASS-PSC',
209
                           column_filters={'Kmag': '<10'})
210

211
# Find catalogs by keyword
212
catalogs = Vizier.find_catalogs('photometry')
213
print(catalogs['title'])
214
```
215

216
### Gaia - European Space Agency's Gaia Mission
217

218
Gaia provides access to the most precise stellar astrometry, photometry, and spectroscopy data available, revolutionizing our understanding of the Milky Way galaxy structure and stellar physics.
219

220
```python { .api }
221
from astroquery.gaia import Gaia
222

223
def query_object(coordinate: Union[SkyCoord, str], *, radius: Union[Quantity, str] = None,  
224
                width: Union[Quantity, str] = None, height: Union[Quantity, str] = None,
225
                verbose: bool = False, columns: tuple = ()) -> Table:
226
    """
227
    Query Gaia catalog around coordinates.
228
    
229
    Parameters:
230
    - coordinate: Center position as SkyCoord or string
231
    - radius: Search radius for circular region
232
    - width: Width for rectangular region
233
    - height: Height for rectangular region
234
    - verbose: Show detailed output
235
    - columns: Tuple specifying which columns to retrieve
236
    
237
    Returns:
238
    Table with Gaia sources in the specified region
239
    """
240

241
def cone_search(coordinate: Union[SkyCoord, str], *, radius: Union[Quantity, str] = None,
242
               table_name: str = None, ra_column_name: str = "ra", dec_column_name: str = "dec",
243
               output_file: str = None, output_format: str = "votable_gzip", 
244
               verbose: bool = False, dump_to_file: bool = False, columns: tuple = ()) -> Table:
245
    """
246
    Perform cone search in Gaia catalog.
247
    
248
    Parameters:
249
    - coordinate: Center coordinates
250
    - radius: Search radius (maximum 0.5 degrees)
251
    - table_name: Gaia table to query (uses default if not specified)
252
    - ra_column_name: Name of RA column in the table
253
    - dec_column_name: Name of DEC column in the table
254
    - output_file: Optional file to save results
255
    - output_format: Format for output file (votable_gzip, csv, etc.)
256
    - verbose: Show detailed output
257
    - dump_to_file: Save results to file
258
    - columns: Tuple specifying which columns to retrieve
259
    
260
    Returns:
261
    Table with Gaia sources within the cone
262
    """
263

264
def cone_search_async(coordinate: Union[SkyCoord, str], radius: Union[Quantity, str] = None) -> JobResults:
265
    """
266
    Submit asynchronous cone search job.
267
    
268
    Parameters:
269
    - coordinate: Center coordinates  
270
    - radius: Search radius
271
    
272
    Returns:
273
    JobResults object for retrieving results
274
    """
275

276
def launch_job(query: str, name: str = None, output_file: str = None, 
277
              output_format: str = 'votable', verbose: bool = False) -> JobResults:
278
    """
279
    Submit synchronous ADQL query job to Gaia TAP service.
280
    
281
    Parameters:
282
    - query: ADQL query string
283
    - name: Job name
284
    - output_file: File to save results
285
    - output_format: Output format ('votable', 'csv', 'fits')
286
    - verbose: Show detailed output
287
    
288
    Returns:
289
    JobResults with query results
290
    """
291

292
def launch_job_async(query: str, name: str = None, output_file: str = None,
293
                    output_format: str = 'votable', verbose: bool = False) -> JobResults:
294
    """
295
    Submit asynchronous ADQL query job.
296
    
297
    Parameters:
298
    - query: ADQL query string
299
    - name: Job name  
300
    - output_file: File to save results
301
    - output_format: Output format
302
    - verbose: Show detailed output
303
    
304
    Returns:
305
    JobResults object for monitoring and retrieving results
306
    """
307

308
def load_table(table_name: str, verbose: bool = False) -> Table:
309
    """
310
    Load Gaia data table schema information.
311
    
312
    Parameters:
313
    - table_name: Name of Gaia table to load
314
    - verbose: Show detailed output
315
    
316
    Returns:
317
    Table with schema information
318
    """
319

320
# Configuration  
321
from astroquery.gaia import conf
322
conf.server: str              # Gaia TAP server URL
323
conf.timeout: int = 60        # Connection timeout
324
```
325

326
Usage examples:
327

328
```python
329
from astroquery.gaia import Gaia
330
import astropy.units as u
331
from astropy.coordinates import SkyCoord
332

333
# Simple cone search
334
coords = SkyCoord(ra=280.161, dec=11.161, unit='deg', frame='icrs')
335
result = Gaia.cone_search(coords, radius=0.1*u.deg)
336
print(f"Found {len(result)} Gaia sources")
337

338
# Query with ADQL
339
query = '''
340
SELECT TOP 1000 source_id, ra, dec, phot_g_mean_mag, bp_rp
341
FROM gaiadr3.gaia_source 
342
WHERE CONTAINS(POINT('ICRS', ra, dec), 
343
               CIRCLE('ICRS', 280.161, 11.161, 0.1)) = 1
344
AND phot_g_mean_mag < 15
345
ORDER BY phot_g_mean_mag
346
'''
347
job = Gaia.launch_job(query)
348
result = job.get_results()
349

350
# Asynchronous job for large queries  
351
job = Gaia.launch_job_async(query, name="bright_stars_search")
352
print(f"Job status: {job.get_phase()}")
353
result = job.get_results()
354

355
# Get table schema
356
schema = Gaia.load_table('gaiadr3.gaia_source')
357
print(schema['column_name', 'datatype', 'description'])
358
```
359

360
## Common Types
361

362
```python { .api }
363
from astropy.table import Table, TableList
364
from astropy.coordinates import SkyCoord
365
from astropy.units import Quantity
366
from typing import Union, List, Optional
367

368
# Input coordinate types
369
coordinates: Union[SkyCoord, str]     # Sky coordinates
370
radius: Union[Quantity, str, None]    # Search radius with units
371

372
# Query parameters
373
object_name: str                      # Astronomical object name
374
catalog: Union[str, List[str], None]  # Catalog identifier(s)
375
get_query_payload: bool = False       # Return parameters only
376
cache: bool = True                    # Enable caching
377
verbose: bool = False                 # Detailed output
378

379
# Return types
380
Table                                 # Single table result
381
TableList                            # Multiple catalog results
382
JobResults                           # Asynchronous job results
383
```