Developer’s corner


The Python cdsclient package gather scripts to query large tables : wise, 2mass, sdss, Gaia, … It needs no special installation (except that python version 2 or 3 must be installed).

  1. Install :
 tar -xzvf python-cdsclient.tar.gz
 cd python-cdsclient
and test:
 ./ -h

the package includes:

  • a generic script which enables to query VizieR using the VizieR identifiers (ex 2mass=II/246)
 List big catalogues : -l
 Get columns information for 2mass (=II/246) : -source=II/246 -i
 Query Gaia (I/337/gaia) around M1 (10arcsec) : -source=I/337/gaia -c=M1 
 Get hipparcos (HIP=1) in votable : -source=I/239/hip_main -mime=votable -out.max=50 "HIP=1"
 Query 2mass arround M1: M1
 Query sdss12 arround '217.488910+36.086880': "217.488910+36.086880"

You can also query with constraints (see –help to list the constraints available (case sensitive))

 Query 2mass with jamg constraint: --Jmag="<11"
 Query sdss using identifier:  --objID=1237662225689281592  --mime=tsv
  • API (needs astropy) and dedicated scripts can also to be used as API:

import find_sdss9 as sdss
process = sdss.QueryCatVizieR()
process.position = "217.091350+35.985222"
process.radius = 120
data = process.get()
print (data)


The cdsclient package is a set of C and csh routines which can be built on Unix stations or PCs running Linux, which once compiled allow to query some databases located at CDS or on mirrors over the network.

The cdsclient package includes two generic query programs:

  • vizquery, a program to remotely query VizieR. It connects the VizieR server via the HTTP protocol (requires an access to the port 80)
  • find_cats, a program for fast access to large surveys from a list of positions, via a dedicated client (requires an access to the port 1660)

vizquery Package Installation

The tar file is available at or as the file cdsclient.tar.gz in the directory.

  1. Once the file is copied e.g. as the file cdsclient.tar.gz in your home directory, untar the file :
    tar xvfz cdsclient.tar.gz

    the z option is available in the GNU tar; if your installation doesn't know the z option, execute

    gzip -cd cdsclient.tar.gz | tar xvf -

    A subdirectory cdsclient-V.vv (where V.vv represents the version number) is created; move to that directory by

    cd cdsclient-V.vv
  2. To configure the package for your system, type

    on some old versions of System V, you might need to type

    sh configure

    If you wish a final installation (executables, libraries, and manpages) in a non-standard directory tree structure (the default is /usr/local), specify the preferred prefix, e.g.

    ./configure --prefix=$HOME

    to prepare an installation of executables in your ~/bin directory — an installation which does not require any root privilege.

  3. Type

    to compile the package.

  4. Type
    make install

    moves the various pieces to the standard directories (/usr/local/bin by default for the executables, see item 2 above to reconfigure, or just modify the value of PREFIX in the Makefile)

There are several query programs; as a rule, each program can be executed with the -help option to list the basic available options, e.g.

findgsc -help

A -HELP option is also available for details on the column contents for the programs that return data, like findgsc or findpmm

Package Contents

The available programs are:

  • findcat allows to retrieve the existing catalogues in CDS Archive. Usage:
    findcat [key… | catalogue_number]
    keys are words to look for, e.g. RADIO, Author's name, etc…, or catalogue number e.g. 8059 B/hst J/A+AS/94/519
  • lscat displays a summary of the files making up a catalogue. Usage:
    lscat catalogue_number [catalogue_number…]
  • catcat allows to copy a catalogue or a file extracted from a catalogue, either in plain ascii, in tar format, or in FITS format. Usage:
    catcat [-#] [-fits[.Z|.gz]|-tar[.Z|.gz] catalog[/file]

    -#: Specify how many lines from each file (default all) are to be printed.
    -tar: Get catalogue file(s) in TAR format
    compressed versions as tar.Z (Unix compress) or tar.gz (gzip)
    -fits: Get catalogue file(s) as FITS tables
    compressed versions as fits.Z (Unix compress) or fits.gz (gzip)
    catalog: catalog designation, e.g. 8059, VIII/59, J/A+AS/94/519…

    Note : The description file is named ReadMe, which means that short explanations may be displayed with commands
    catcat VIII/59/ReadMe
    catcat J/A+AS/94/519/ReadMe
  • findgsc allows to query (by coordinates or from the GSC number) the Guide Star Catalogue (versions 1.1, 1.2 ot ACT — see the VizieR GSC pages).
    Usage :
    findgsc [1.2] J2000-center [-r radius_arcmin] [-n max_found_stars]
    findgsc [1.2] -g GSCfld[-number] [-n max_found_stars]
    findgsc [1.2] - [options] (centers in stdin)

    Described by A. Preite-Martinez & F. Ochsenbein in “Handling & Archiving Data from ground-based Telescopes”, Trieste April 21-23, 1993, Eds. M. Albrecht & F. Pasian, ESO Conference and Workshop Proceedings No. 50, p. 199

    Example: find out GSC stars within 5' of centers specified in file mycenters which contains:
    12 34 12.5 -34 23 12
    13 24 57.1 +61 12 34

    just execute

    findgsc - -r 5 < mycenters

    Note : in order to avoid congestions, the size of the file containing the list of centers (mycenters) is limited to a maximum of about 40Mbytes.

  • findgsc2.2 (2001) allows to query the GSC2.2 Catalog (Cat. I/271) in a similar way; this version of the GSC2 includes about 500 million sources.
  • findgsc2.3 (2006) allows to query the GSC2.3 Catalog (Cat. I/305) in a similar way; this version of the GSC2 includes about 945 million sources.
  • finducac1 (2000) allows to query the UCAC1 catalog (First U.S. Naval Observatory CCD Astrograph Catalog, Zacharias et al.) including about 27million sources (Cat. I/268)
  • finducac2 (Oct. 2003) allows to query the UCAC2 catalog (Second U.S. Naval Observatory CCD Astrograph Catalog, Zacharias et al.) including about 48million sources (Cat. I/289)
  • finducac3 (Aug. 2009) allows to query the UCAC3 catalog (Third U.S. Naval Observatory CCD Astrograph Catalog, Zacharias et al.) including about 100million sources (Cat. I/315)
  • findpmm allows to query the USNO-A2.0 Catalog (Dave Monnett et al., see which contains over 500,000,000 sources compiled from the blue/red overlaps of the detection lists generated from scans of POSS-I O and E, SRC-J and ESO-R plates. Usage similar to findgsc.

    Example: find out USNO-A2.0 stars within 3' of centers specified in file mycenters which contains, ordered by increasing distances from specified centers:
    12 34 12.5 -34 23 12
    13 24 57.1 +61 12 34

    just execute

    findpmm - -r 3 -sr < mycenters

    Note : the program findpmm1 allows to query the USNO-A1.0 catalogue

  • findppmx (Dec. 2008) allows to query the PPMX Catalog (Röeser et al. 2008A&A...488..401R, Catalog I/312), a catalogue of 18,088,919 stars containing astrometric and photometric information. Its limiting magnitude is about 15.2, and includes reliable proper motions.
  • findusnob1 (Dec. 2002) allows to query the USNO-B1.0 Catalog (Dave Monnett et al.,; see also Catalog I/284) which contains over 1 billion sources compiled from the blue/red/infrared plates of several surveys made over 50 years including the POSS-I and POSS-II. Besides the position and proper motions, magnitudes and star/galaxy extimators are provided. Note that the format of the catalog has changed slightly in November 2005, some edition problems were discovered near the poles, see details in the “History” section of the getReadMe,w I/284ReadMe file of catalog I/284; we apologize for any inconvenience these changes might have introduced.
  • find2mass (Jul. 2003) allows to query the 2MASS Final Point Source Catalog ( ; see also Catalog II/246) which contains 470,992,970 sources covering virtually the while sky in the infrared bands JHK.
  • findenis (Sep. 2005) allows to query the DENIS 3rd Release (; see also Catalog B/denis) which contains 355,220,325 sources in the infrared bands IJK. Older versions of DENIS can be queried with findenis1 (version 1), findenis2 (second version), etc.
  • findnomad1 (Jul. 2006) allows to query the NOMAD1 catalog. (see Catalog I/297, and The catalog merges USNO-B1, UCAC2, Tycho-2, 2MASS and contains over 1.1billion sources. Efficient queries available from position, magnitudes and colors.
  • findcmc14 (Dec. 2006) allows to query the Carlsberg Meridian Catalogue La Palma number 14 (see Catalog I/304). The catalogue gather about 100 million stars in the declination range -30° to +50°.
  • find_cats (Jan. 2008) is a program to query the large surveys (GSC, UCAC, USNO, 2MASS, SDSS …) from a list of positions. For each position given, find_cats returns the results from one or several of the large surveys. To minimize the number of bytes transferred on the network, the program find_cats.gz returns gzipped (compressed) output.

    find_cats my_file -r 0.5 GSC1.2 UCAC2: -r 0.3 2MASS: -lmJ 6,11

    to query around the positions (stored in the file my_file) on catalogues:

    • GSC1.2 within a target radius of 0.5arcmin
    • UCAC2 within a target radius of 0.3mrcmin
    • 2MASS within a target radius of 0.5arcmin and J mag in range 6-11.

      The rule is that, when a catalog is followed by a colon (:), the arguments following the catalog apply only to that catalog.
  • vizquery (Sep. 2003) a generic program to query VizieR (or any mirror) and get the results in one of the various available formats: ascii, HTML, TSV, XML, VOTable, FITS… A more complete description can be cound in the vizquery page.
  • sesame (Nov. 2008) supplies details about astronomical sources (outside the Solar System). It operates by querying Simbad, NED, and VizieR databases – more details on the sesame documentation
  • simref allows to retrieve bibliographical references (authors & title) from SIMBAD data-base. Usage:
    simref bibcode
    (Note that the bibcode need not to be complete, full volumes are listed when the page numbers are omitted. The year is not required for the most important journals)
  • simbib allows to retrieve bibliographical references from author's names or words from title. Usage:
    simbib [minimal_year] word(s)…
    Example :
    simbib 1990 white dwarf X-ray

    retrieves the references simce 1990 dealing about white dwarfs in X-ray domain.

  • abibcode adds, to an input file assumed to contain LaTeX references in the form
    \bibitem{label} …
    into one of the two macros:
    (reference known in Simbad), or
    \NOsim{text} (not existing in SIMBAD)

Proxys and firewall

Most programs are using the port 1660 which may be closed (more and more institutes are closing almost all ports except a dozen or so like http, ssh, https, …). It is possible to use alternative ports or servers via a CDSCLIENT environment variable:

  • CDSCLIENT=http; export CDSCLIENT

    will ask to make the connection via the port 80 (http port). This may solve your problem in the case the port 1660 is unreachable.

  • http_proxy=http//your_proxy:your_port; export http_proxy

    is the standard way to define a proxy for http; your_proxy and your_port are defined by your network administrators

  • both can be combined (in principle)
  •; export CDSCLIENT

    defines an alternative server in the in the exceptional case where our main catalog server ( = is unreachable. Another server could be available with; export CDSCLIENT
cdsclient.txt · Last modified: 2019/11/04 16:09 by Gilles Landais

Thanks for acknowledging the CDS developer’s resources (libraries, source code, etc.)

© Université de Strasbourg/CNRS

    • Contact