VizieR FAQ

Frequently Asked Questions about the VizieR service and data.

Updated: March 15, 2024 - 12:18 CET

VizieR contents

How can I submit data for ingestion in VizieR? See https://cdsarc.cds.unistra.fr/submit/
How can I find the catalogue I'm interested in via the Web interface/python?

There are many ways to do this:

Let's use the "Catalogue collection" search service. It allows you to combine terms from keywords or even descriptions of parameters in a table (tables.columns.desc) to search a catalogue from its ReadMe file.

Example: tables.columns.desc:"oxygen abundance" keyword:Surveys" displays 15 catalogues with at least one column containing "oxygen abundance" and "Surveys" in Keywords (specific CDS keywords and/or publication keywords).

Alternatively, you can use the VizieR home page to search a simple word among the titles, author's names and abstracts or query a position (for tables having coordinates)... More help for this search is available.

Note that:

  • The list of recently added catalogues is available on the dedicated CDS news page
  • The list of catalogues having associated data like spectra, images, time series, cubes or SED is weekly updated.

By script, you can see an example in the Jupyter notebook:

Using astroquery:

Where can I find a list of VizieR mirrors?

The list of the currently existing VizieR installations may be found:

I can't find my objects by position search in Gaia-DR3. What is going on? Gaia positions are at epoch J2000/2015.5, while many other resources (including SIMBAD) give position at epoch J2000/2000.0.

Usage of VizieR

I have a list of positions, and would like to query several catalogues around these positions
  1. Using the Web interface: You can submit a file containing your list of targets to VizieR (Web interface) within the tab "List Of Targets": https://vizier.cds.unistra.fr/vizier/vizHelp/file.htx

    Then in the 'Table' toolbar on the left, click "Add" to add another catalogue.

  2. Using astroquery: https://astroquery.readthedocs.io/en/latest/vizier/vizier.html

I would like to select sources in a catalogue, and find nearby sources in another catalogue

There are many ways to do this:

  1. Scripting via python/astroquery/pyvo. Tutorials for this can be found here: https://cds-astro.github.io/tutorials/intro.html, and we also recommend going through the examples of the astroquery documentation (https://astroquery.readthedocs.io/en/latest/vizier/vizier.html).
  2. This can also be done by uploading the list of sources, as explained in How to Query VizieR from a LIST saved in a file (Section 3).
  3. For a subset of curated catalogues, you can use the cross-match service, it is very efficient and asynchronous.
How can I provide a direct link to a VizieR result page? VizieR follows the ASU conventions, and it's (relatively) easy to compose a URL which executes a query on VizieR and presents the result in a Web page: the HTTP GET or POST method can be used (are equivalent); see the ASU summary to get some details about how to write a working URL. To have better visibility on the VizieR pages URLs, one may click on the "B" button at the top of the left toolbar (B for Bookmark). Your browser URL field will then display the full URLs being visited during your use of vizier. These can be copy/pasted, modified appropriately and reused.
How can I download a full large (or small) catalogue?

Retrieving an entire large catalogue (>~30 million records) through the html query interface of VizieR is not possible for a number of reasons, including connection stability, timeouts, and the necessity to keep the VizieR servers available for all users, precluding excessively large/heavy queries. Large catalogues, if applicable, can usually be downloaded in bulk from their producer consortium if the latter has so decided. Setting the bar in this respect, all the gaia DRs can be downloaded in bulk from ESA. Note that this is not always the case, as CDS may be allowed by a consortium to offer access to a dataset through VizieR queries but not necessarily to offer bulk download of it.

For smaller catalogues however, you can download full catalogue tables from the FTP page of the catalogue, accessible through the "ftp" link of the catalogue landing page (e.g. https://cdsarc.cds.unistra.fr/viz-bin/cat/J/ApJ/891/68 and https://cdsarc.cds.unistra.fr/ftp/J/ApJ/891/68/)

Output options

I would like to get the results in a specific format like CSV, FITS... How do I do? Choose the Tab-Separated-Values (TSV) as the Output layout in the Query Setup part of the pages. Many other formats are available (VOTable, XML, other separators, etc...)
How can I set my own limit for the number of rows to retrieve?

Again there are several ways around that:

  1. Python: The limit number of rows retrieved is set via the Vizier.ROW_LIMIT parameter of an astroquery VizieR instance. Default is 50 and -1 is unlimited. Note that retrieving full large catalogs (e.g. Gaia, 2MASS) will not work because even without a fixed ROW_LIMIT, the VizieR server will still time out after some time if the data volume is too large. Other methods must be used to recover full catalogs.

  2. Python asynchronous (astroquery / pyvo): To get around the time out issues, it is recommended to use the asynchronous features of VizieR through either astroquery or pyvo.

    It works in 3 steps:

    1. a query is sent by the user,
    2. the Python instance will keep checking the VizieR server for completion of the task,
    3. and finally once the task is complete, the results are fetched.

    A python code snippet using this method follows:

    from pyvo.dal.tap import TAPService
    tapvizier = TAPService("https://tapvizier.cds.unistra.fr/TAPVizieR/tap")
    one_gaia_line = tapvizier.run_async(r'select top 1 RA_ICRS, DE_ICRS, Source from "I/355/gaiadr3"')
    # check result
    print(one_gaia_line.infos)
    # convert to astropy.table
    one_gaia_line = one_gaia_line.to_table()
    # check metadata
    print(one_gaia_line.info)
    

    Note that the query is very simple. For more complex queries see the help and/or experiment with the TAPvizier service page

  3. In the HTML interface: There is a trick to set your limit: specify it in the HTTP location with the -out.max parameter, for instance -out.max=123456.

    Retrieving this large sample could be very slow – especially if you ask to sort the results – just be prepared to wait when asking very large bunches...

    And also better choose the ASCII table output format (or output for files like VOTable or FITS), the HTML tabular formatting can be very slow for large tables!

How can I sort my output by a certain column?

There are two ways:

  1. After you have made the query one can use the up and down buttons to sort by a specific column. This works well on small tables. Before the query in the interface there is an option to tick called "Sort" for each column. If this option is ticked one needs to also give a constraint on this column in the constraint box to receive a sorted output.
  2. You may also use TAP, which will also work for larger tables, asynchronously.
I would like to have my target name listed in a column of the output Please see details in How to Query VizieR from a LIST saved in a file (Section 3).

Credits and acknowledgements

How can I cite usage of VizieR?

The preferred reference for the usage of VizieR is the following paper:

See also: https://cds.unistra.fr/vizier-org/licences_vizier.html

How can I cite VizieR catalogs?
  1. See https://cds.unistra.fr/vizier-org/licences_vizier.html
  2. Use DOIs, as given in the landing page (top left of https://cdsarc.cds.unistra.fr/viz-bin/cat/I/355)
  3. Use the "cite" button right next to the DOI on the landing page.