4.1  General Overview

The cdsclient package is a set of C and shell 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:

Specific programs like find2mass or finducac3 are connecting directly to one of the very large surveys available from CDS (a very large survey has 107 or more rows). Using a specific program is faster than the generic vizquery program which has to locate and transport the data via data-base queries; but such progams exist only for the list of enumerated large surveys below.

4.2  Package Installation

The tar file is available at http://cdsarc.u-strasbg.fr/ftp/pub/sw/cdsclient.tar.gz or as the file cdsclient.tar.gz in the ftp://cdsarc.u-strasbg.fr/pub/sw/ 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 make 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

4.3  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

  • findcfhtd and findcfhtw allow to query the deep and wide CFHT-LS surveys (T0007 release, see Cat. II/317)

  • 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°.

  • findcmc15 (Apr. 2014) (Cat. I/327) The catalogue gather about 135million stars in the declination range –400° to +50°.

  • findigsl allows to query the Initial Gaia Source List (see I/324):

  • findgalex5a and findgalex5m allow to query the GALEX-DR5 catalogues (see II/312): the AIS (All-sky Imaging Survey,  65million sources), or the MIS (Medium-depth Imaging Survey,  12.5million sources).

  • findglimpse (May 2010) allows to query Sptizer's GLIMPSE catalog in the central regions of our Galaxy. The catalog gathers about 100 million sources in the 4–8µm wavelength region (see II/293).

  • 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).


    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.

  • findiphas2 ((2014), the Second Release of the INT Photometric Hα Survey in the Northern Galactic Plane (219million sources, Cat. II/321)

  • 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)

  • finducac4 (Sep. 2012) allows to query the UCAC4 catalog (Fourth U.S. Naval Observatory CCD Astrograph Catalog, Zacharias et al.) including about 114million sources (Cat. I/322)

  • findurat1 (Mar. 2015) allows to query the URAT1 catalog (Foutrh U.S. Naval Observatory CCD Astrograph Catalog, Zacharias et al.) including about 228million sources for δ>-15° (Cat. I/322)

  • findpmm allows to query the USNO-A2.0 Catalog (Dave Monnett et al., see http://psyche.usno.navy.mil/pmm) 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.

  • findppmxl (July 2010) allows to query the PPMXL Catalog (Röeser et al. 2010AJ....139.2440R, Catalog I/317), a catalogue of around 900million sources with positions and proper motions aiming to be complete down to about V=20 full-sky.

  • findusnob1 (Dec. 2002) allows to query the USNO-B1.0 Catalog (Dave Monnett et al., http://www.nofs.navy.mil/data/fchpix/; 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 ReadMe file of catalog I/284; we apologize for any inconvenience these changes might have introduced.

  • findkic (Sep. 2010) allows to query the Kepler Input Catalogue (Cat. V/133) about 13million stars

  • find2mass (Jul. 2003) allows to query the 2MASS Final Point Source Catalog (http://www.ipac.caltech.edu/2mass/ ; 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 (http://cdsweb.u-strasbg.fr/denis.html; 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.

  • findsdss3 (Oct. 2005) allows to query a subset of the SDSS 3rd release (see Catalog II/259, and http://www.sdss.org).

  • findsdss4 (Dec. 2006) allows to query a subset of the SDSS 4th release (see Catalog II/267, and http://www.sdss.org).

  • findsdss5 (Feb. 2007) allows to query a subset of the SDSS 5th release (see Catalog II/276, and http://www.sdss.org).

  • findsdss6 (Feb. 2008) allows to query a subset of the SDSS 6th release (see Catalog II/282, and http://www.sdss.org).

  • findsdss7 (Jun. 2009) allows to query a subset of the SDSS 7th release (see Catalog II/294, and http://www.sdss.org).

  • findsdss8 (Feb. 2012) allows to query a subset of the SDSS 8th release (see Catalog II/306, and http://www.sdss.org). Can be queried by Jname, objID, plate-mjd-fiber, run-rerun-camcol-field-object.

  • findsdss9 (Feb. 2013) allows to query a subset of the SDSS 9th release (see Catalog V/139, and http://www.sdss.org). Can be queried by Jname, objID, plate-mjd-fiber, run-rerun-camcol-field-object.

  • findnomad1 (Jul. 2006) allows to query the NOMAD1 catalog. (see Catalog I/297, and http://www.nofs.navy.mil/nomad/). The catalog merges USNO-B1, UCAC2, Tycho-2, 2MASS and contains over 1.1billion sources. Efficient queries available from position, magnitudes and colors.

  • findspm4 allows to query the astrometric Yale/San Juan Southern Proper Motion Catalog #4 ( 103million sources, see I/320)

  • findviking1 (Oct. 2014) VISTA Kilo-degree Infrared Galaxy Survey Data Release 1 ( 15million sources, Cat. II/329)

  • findwise (2014) allows to query the AllWISE release ( 748million sources, Cat. II/328) of the Wide-field Infrared Survey Explorer (bands centered around 3.35, 4.6, 11.6 and 22.1µm; more details on http://wise2.ipac.caltech.edu/docs/release/allsky/expsup/) Previous (2012) versions are findwise0 (all sky, 564million sources) and findwisep (preliminary catalogue).

  • UKIDSS catalogs:
    • findgps6: Galactic Plane Survey Release 6 ( 558million sources, II/316)
    • finddsx9: Deep Extragalactic Survey Release 9 ( 3million sources, II/319)
    • findgcs9: Galactic Clusters Survey Release 9 ( 54million sources, II/319)
    • findlas9: Large Area Survey Release Release 9 ( 82million sources, II/319)
    • older UKIDSS Release 8: finddsx8, findgcs8, and finddsx8

  • catalogs related to the Magellanic Clouds (Mar. 2012):
    • findmc2: Master Catalogue towards the Magellanic Clouds, Delmotte et al., Cat. IV/33
    • findsage, from the Spitzer results (Cat. II/305)
    • findmc_irsf: IRSF Magellanic Clouds Point Source Catalog, Kato et al., Cat. II/288

  • 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.

    Example: 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:

    \simOK{bibcode}   (reference known in Simbad), or

    \NOsim{text}   (not existing in SIMBAD)

4.4  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)
  • CDSCLIENT=axel.u-strasbg.fr; export CDSCLIENT
    defines an alternative server in the in the exceptional case where our main catalog server (cocat1.u-strasbg.fr = is unreachable. Another server could be available with CDSCLIENT=vizier.hia.nrc.ca; export CDSCLIENT

|Version 30-Dec-2009

|For any question or problem, please contact
Please send comments and questions to 

©UDS/CNRS  Contact: Question@simbad