CDS xMatch service documentation: Calls

3.2 Calls

Calls to the API can be performed using either GET or POST methods.
However, if your request involves file uploads, you will be enforced to use the POST method.

Submitting a cross-match job

Compulsory parameters

REQUEST - only allowed value is xmatch (REQUEST=xmatch)
cat1 - identifier of the first table.
It can either be a URL, the payload of a local file being uploaded or a CDS table identifier (either simbad for a view of SIMBAD data, or to point out a given VizieR table. Examples: vizier:II/311/wise or vizier:II/246/out).
If the table is uploaded or accessed through a URL, it must be in VOTable or CSV format with the positions in J2000 equatorial frame and as decimal degrees numbers.
Here is an example of a CSV file to be uploaded:
```
ra,dec
267.22029,-20.35869
274.83971,-25.42714
275.92229,-30.36572
283.26621,-8.70756
306.01575,33.86756
322.493,12.16703
```
Total size of uploaded tables can not be larger than 100 MB.
cat2 - identifier of the second table.
Follows the same rules as cat1.
distMaxArcsec - maximum distance in arcsec to look for counterparts.
Maximum allowed value is 180.
RESPONSEFORMAT - format of the result.
Possible values are votable|json|csv|tsv.

If cat1 is an uploaded table or a pointer to a URL, the following parameters are also compulsory:

colRA1 - name of the column holding the right ascension. Example: colRA1=ra.
colDec1 - name of the column holding the declination. Example: colDec1=dec.

If cat2 is an uploaded table or a pointer to a URL, the following parameters are also compulsory:

colRA2 - name of the column holding the right ascension. Example: colRA2=ra.
colDec2 - name of the column holding the declination. Example: colDec2=dec.

Optional parameters

selection - match selection. Allowed values are best|all. Default selection mode is all.
all: all matches are kept. In this mode, the cross-match is symmetric.
best: keep best match in cat2 for each row of cat1. In this mode, the cross-match is not symmetric.
MAXREC - maximum number of rows to return. The server has a hard upper limit (currently set at $2\, 000\, 000$ records) which can not be overriden by the user.
cols1 - comma-separated list of columns of cat1 to be kept in output.
Example: cols1=ra,dec,main_id
cols2 - comma-separated list of columns of cat2 to be kept in output.
area - match in a geometrical area. Allowed values are allsky|cone|zone|hpx. Default selection mode is allsky.
allsky: allsky cross match cone: cross-match in a given cone. zone: cross-match in a given zone (i.e. an area defined by 2 meridian and 2 small circles). hpx: cross-mathc in a given HEALPix cell.

Remark: the area constraint is put on the cat1 sources. cat2 sources matching cat1 sources close to the area border may lie outside the area.

area=cone parameters

coneRA - right ascension of center of the cone, in decimal degrees. Example: coneRA=10.5457.
coneDec - declination of center of the cone, in decimal degrees. Example: coneDec=-45.8612.
coneRadiusDeg - radius of the cone, in degrees. Example: coneRadiusDeg=0.14.

area=zone parameters

raMin - zone lower right ascension, in decimal degrees. Example: raMin=0.0.
decMin - zone loxer declination, in decimal degrees. Example: decMin=0.0.
raMax - zone upper right ascension, in decimal degrees. Example: raMax=10.0.
decMax - zone upper declination, in decimal degrees. Example: decMax=10.0.

area=hpx parameters

order - order of the HEALPix cell. Example: order=9.
ipix - HEALPix cell number (NESTED scheme) at the given order. Example: ipix=125840.

Have a look at section 3.7 for some typical usage examples.

Retrieving the available VizieR tables

To get the list of the VizieR tables which are available in the service, make a call to:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?
action=getVizieRTableNames&RESPONSEFORMAT=txt

You can also get back this list formatted as a JSON document:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?
action=getVizieRTableNames&RESPONSEFORMAT=json

Optionally you can ask for all tables (default) or only large, notlarge, medium or small tables using option select. Example:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?
action=getVizieRTableNames&select=large&RESPONSEFORMAT=json

You can then retrieve more information about a specific table:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?
action=getInfo&tabName=TABLENAME

And the list of its columns:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?
action=getColList&tabName=TABLENAME&RESPONSEFORMAT=votable|json|csv|tsv|txt

You can also directly download the information of all tables with one call to:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables

Finally, you can also call:

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?action=getPrettyNames

http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync/tables?action=getAliases