0
# Virtual Observatory Services
1

2
Services implementing Virtual Observatory (VO) standards for interoperability, cross-matching, and standardized data access protocols. These services enable seamless integration between different astronomical databases and tools.
3

4
## Capabilities
5

6
### VO Cone Search - Virtual Observatory Cone Search
7

8
VO Cone Search provides standardized access to astronomical catalogs using the Simple Cone Search protocol, enabling uniform queries across participating data centers worldwide.
9

10
```python { .api }
11
from astroquery.vo_conesearch import conesearch, list_catalogs
12
from astroquery.vo_conesearch.validator.validate import cs_validate
13

14
def conesearch(center: Union[SkyCoord, str], radius: Union[Quantity, str],
15
              catalog_db: str = None, pedantic: bool = None, 
16
              verbose: bool = False, cache: bool = True) -> Table:
17
    """
18
    Perform cone search on Virtual Observatory catalogs.
19
    
20
    Parameters:
21
    - center: Search center coordinates
22
    - radius: Search radius
23
    - catalog_db: Specific catalog database to query
24
    - pedantic: Strict VO compliance checking
25
    - verbose: Show detailed output
26
    - cache: Enable result caching
27
    
28
    Returns:
29
    Table with sources within the search cone
30
    """
31

32
def list_catalogs(**kwargs) -> List[str]:
33
    """
34
    List available VO cone search catalogs.
35
    
36
    Parameters:
37
    - **kwargs: Filtering criteria for catalogs
38
    
39
    Returns:
40
    List of available catalog identifiers
41
    """
42

43
def cs_validate(url: str, verbose: bool = True) -> Dict:
44
    """
45
    Validate a cone search service for VO compliance.
46
    
47
    Parameters:
48
    - url: Cone search service URL
49
    - verbose: Show detailed validation results
50
    
51
    Returns:
52
    Dictionary with validation results
53
    """
54

55
# Configuration
56
from astroquery.vo_conesearch import conf
57
conf.pedantic: bool = False   # Strict VO compliance
58
conf.timeout: int = 60        # Connection timeout
59
```
60

61
Usage examples:
62

63
```python
64
from astroquery.vo_conesearch import conesearch, list_catalogs
65
from astropy.coordinates import SkyCoord
66
import astropy.units as u
67

68
# Basic cone search
69
coords = SkyCoord('12h30m43s', '+12d23m28s', frame='icrs')
70
result = conesearch(coords, radius=2*u.arcmin)
71
print(f"Found {len(result)} sources in cone search")
72
print(result['RAJ2000', 'DEJ2000', 'Vmag'])
73

74
# List available catalogs
75
catalogs = list_catalogs()
76
print(f"Available VO catalogs: {len(catalogs)}")
77

78
# Search specific catalog
79
specific_result = conesearch(coords, radius=1*u.arcmin, 
80
                           catalog_db='2MASS All-Sky Catalog of Point Sources')
81

82
# Validate cone search service
83
validation = cs_validate('http://example.com/conesearch')
84
print(f"Service valid: {validation['valid']}")
85
```
86

87
### Cross-match Service - CDS X-Match
88

89
CDS X-Match service provides cross-matching capabilities between astronomical catalogs, enabling identification of the same sources across different surveys and databases.
90

91
```python { .api }
92
from astroquery.xmatch import XMatch
93

94
def query(cat1: Union[Table, str], cat2: str, max_distance: Union[Quantity, str],
95
         colRA1: str = None, colDec1: str = None, colRA2: str = None, colDec2: str = None,
96
         area: str = 'allsky') -> Table:
97
    """
98
    Cross-match two catalogs.
99
    
100
    Parameters:
101
    - cat1: First catalog (Table object or VizieR catalog name)
102
    - cat2: Second catalog (VizieR catalog name)
103
    - max_distance: Maximum matching distance
104
    - colRA1: RA column name in first catalog
105
    - colDec1: Dec column name in first catalog  
106
    - colRA2: RA column name in second catalog
107
    - colDec2: Dec column name in second catalog
108
    - area: Sky area constraint ('allsky' or region specification)
109
    
110
    Returns:
111
    Table with cross-matched sources
112
    """
113

114
def query_async(cat1: Union[Table, str], cat2: str, max_distance: Union[Quantity, str],
115
               **kwargs) -> JobResults:
116
    """
117
    Submit asynchronous cross-match query.
118
    
119
    Parameters:
120
    - cat1: First catalog
121
    - cat2: Second catalog
122
    - max_distance: Maximum matching distance
123
    - **kwargs: Additional cross-match parameters
124
    
125
    Returns:
126
    JobResults object for retrieving results
127
    """
128

129
# Configuration
130
from astroquery.xmatch import conf
131
conf.server: str              # X-Match server URL
132
conf.timeout: int = 300       # Connection timeout
133
```
134

135
Usage examples:
136

137
```python
138
from astroquery.xmatch import XMatch
139
from astroquery.vizier import Vizier
140
import astropy.units as u
141
from astropy.coordinates import SkyCoord
142

143
# Cross-match with VizieR catalogs
144
result = XMatch.query(cat1='vizier:2MASS-PSC', cat2='vizier:SDSS-DR12',
145
                     max_distance=2*u.arcsec, area='allsky')
146
print(f"Cross-matched {len(result)} sources between 2MASS and SDSS")
147

148
# Cross-match user catalog with reference catalog
149
# First, get a sample catalog
150
coords = SkyCoord('12h30m43s', '+12d23m28s', frame='icrs')
151
my_sources = Vizier.query_region(coords, radius=10*u.arcmin, 
152
                                catalog='2MASS-PSC')[0]
153

154
# Cross-match with Gaia
155
gaia_matches = XMatch.query(cat1=my_sources, cat2='vizier:I/350/gaiaedr3',
156
                           max_distance=1*u.arcsec,
157
                           colRA1='RAJ2000', colDec1='DEJ2000')
158
print(f"Found {len(gaia_matches)} Gaia matches")
159

160
# Large area cross-match (async)
161
job = XMatch.query_async(cat1='vizier:HIPPARCOS', cat2='vizier:Gaia-EDR3',
162
                        max_distance=3*u.arcsec, area='allsky')
163
large_xmatch = job.get_results()
164
```
165

166
### Table Access Protocol (TAP) Services
167

168
TAP services provide standardized SQL-like query access to astronomical databases using ADQL (Astronomical Data Query Language).
169

170
```python { .api }
171
from astroquery.utils.tap import TapPlus
172

173
def launch_job(query: str, name: str = None, output_file: str = None,
174
              output_format: str = 'votable', verbose: bool = False,
175
              dump_to_file: bool = False, background: bool = False) -> JobResults:
176
    """
177
    Execute ADQL query on TAP service.
178
    
179
    Parameters:
180
    - query: ADQL query string
181
    - name: Job name for identification
182
    - output_file: File to save results
183
    - output_format: Output format ('votable', 'csv', 'fits')
184
    - verbose: Show detailed output
185
    - dump_to_file: Save query results to file
186
    - background: Submit as background job
187
    
188
    Returns:
189
    JobResults with query results
190
    """
191

192
def launch_job_async(query: str, **kwargs) -> JobResults:
193
    """
194
    Submit asynchronous ADQL query.
195
    
196
    Parameters:
197
    - query: ADQL query string
198
    - **kwargs: Additional job parameters
199
    
200
    Returns:
201
    JobResults object for monitoring and retrieving results
202
    """
203

204
def get_tables(only_names: bool = False, verbose: bool = False) -> List:
205
    """
206
    Get available tables in TAP service.
207
    
208
    Parameters:
209
    - only_names: Return only table names
210
    - verbose: Show detailed table information
211
    
212
    Returns:
213
    List of table information or names
214
    """
215

216
def get_columns(table_name: str) -> Table:
217
    """
218
    Get column information for a specific table.
219
    
220
    Parameters:
221
    - table_name: Name of the table
222
    
223
    Returns:
224
    Table with column descriptions
225
    """
226

227
# Configuration for TAP services
228
conf.timeout: int = 600       # Query timeout
229
```
230

231
Usage examples:
232

233
```python
234
from astroquery.utils.tap import TapPlus
235
from astroquery.gaia import Gaia
236

237
# Direct TAP query to Gaia
238
gaia_tap = TapPlus(url="https://gea.esac.esa.int/tap-server/tap")
239

240
# Get bright stars near galactic center
241
query = """
242
SELECT TOP 1000 source_id, ra, dec, phot_g_mean_mag, bp_rp
243
FROM gaiadr3.gaia_source 
244
WHERE CONTAINS(POINT('ICRS', ra, dec), 
245
               CIRCLE('ICRS', 266.417, -29.008, 1.0)) = 1
246
AND phot_g_mean_mag < 15
247
ORDER BY phot_g_mean_mag
248
"""
249
job = gaia_tap.launch_job(query)
250
bright_stars = job.get_results()
251
print(f"Found {len(bright_stars)} bright stars")
252

253
# Asynchronous complex query
254
complex_query = """
255
SELECT g.source_id, g.ra, g.dec, g.phot_g_mean_mag, 
256
       g.pmra, g.pmdec, g.parallax,
257
       rv.radial_velocity, rv.radial_velocity_error
258
FROM gaiadr3.gaia_source AS g
259
JOIN gaiadr3.rvs_mean_spectrum AS rv ON g.source_id = rv.source_id
260
WHERE g.parallax > 10 AND g.parallax_error/g.parallax < 0.1
261
AND g.phot_g_mean_mag < 12
262
"""
263
async_job = gaia_tap.launch_job_async(complex_query, name="nearby_stars_rv")
264
nearby_rv = async_job.get_results()
265

266
# Get table information
267
tables = gaia_tap.get_tables(only_names=True)
268
print(f"Available tables: {len(tables)}")
269

270
# Get column info
271
columns = gaia_tap.get_columns('gaiadr3.gaia_source')
272
print(columns['column_name', 'datatype', 'description'][:10])
273
```
274

275
### Registry Services
276

277
VO Registry services for discovering available astronomical data services and their capabilities.
278

279
```python { .api }
280
from astroquery.vo_conesearch.vos_catalog import get_remote_catalog_db
281

282
def get_remote_catalog_db(cache: bool = True, verbose: bool = False) -> Dict:
283
    """
284
    Get remote catalog database from VO registry.
285
    
286
    Parameters:
287
    - cache: Enable catalog database caching
288
    - verbose: Show detailed output
289
    
290
    Returns:
291
    Dictionary with available VO services
292
    """
293

294
def search_registry(keywords: List[str], service_type: str = None) -> List:
295
    """
296
    Search VO registry for services matching criteria.
297
    
298
    Parameters:
299
    - keywords: Keywords to search for
300
    - service_type: Type of service ('conesearch', 'tap', 'sia')
301
    
302
    Returns:
303
    List of matching services
304
    """
305

306
# Configuration
307
conf.registry_timeout: int = 60  # Registry query timeout
308
```
309

310
Usage examples:
311

312
```python
313
from astroquery.vo_conesearch.vos_catalog import get_remote_catalog_db
314

315
# Get available VO services
316
catalog_db = get_remote_catalog_db(verbose=True)
317
print(f"Found {len(catalog_db)} VO cone search services")
318

319
# Filter for specific type of catalogs  
320
photometry_services = [svc for svc in catalog_db 
321
                      if 'photometry' in svc.lower()]
322
print(f"Photometry services: {len(photometry_services)}")
323
```
324

325
## Common Types
326

327
```python { .api }
328
from astropy.table import Table
329
from astropy.coordinates import SkyCoord
330
from astropy.units import Quantity
331
from typing import Union, List, Dict, Optional
332

333
# Input types
334
center: Union[SkyCoord, str]                # Search center
335
coordinates: Union[SkyCoord, str]           # Target coordinates
336
radius: Union[Quantity, str]                # Search radius  
337
max_distance: Union[Quantity, str]          # Cross-match distance
338

339
# Catalog specifications
340
cat1: Union[Table, str]                     # First catalog
341
cat2: str                                   # Second catalog (VizieR name)
342
catalog_db: str                             # Cone search catalog
343
table_name: str                             # TAP table name
344

345
# Query parameters
346
query: str                                  # ADQL query string
347
colRA1: str                                 # RA column name
348
colDec1: str                                # Dec column name
349
area: str = 'allsky'                        # Sky area constraint
350
pedantic: bool = False                      # VO compliance checking
351

352
# Service parameters
353
output_format: str = 'votable'              # Output format
354
background: bool = False                    # Background execution
355
verbose: bool = False                       # Detailed output
356

357
# Return types  
358
Table                                       # Query results
359
JobResults                                  # Asynchronous job results
360
List[str]                                   # Service/table names
361
Dict                                        # Service metadata/validation
362
```