SimbadClass

class astroquery.simbad.SimbadClass(ROW_LIMIT=None)[source]

Bases: BaseVOQuery

The class for querying the SIMBAD web service.

Note that SIMBAD suggests submitting no more than 6 queries per second; if you submit more than that, your IP may be temporarily blacklisted (https://simbad.cds.unistra.fr/guide/sim-url.htx)

Attributes Summary

ROW_LIMIT

SIMBAD_URL

columns_in_output

A list of _Column.

hardlimit

The maximum number of lines for SIMBAD's output.

server

The SIMBAD mirror to use.

tap

A TAPService service for SIMBAD.

Methods Summary

add_votable_fields(*args)

Add columns to the output of a SIMBAD query.

clear_cache()

Clear the cache of SIMBAD.

get_field_description(field_name)

Displays a description of the VOTable field.

get_votable_fields()

Display votable fields.

list_columns(*tables[, keyword, ...])

Get the list of SIMBAD columns.

list_linked_tables(table, *[, get_query_payload])

Expose the tables that can be non-obviously linked with the given table.

list_tables(*[, get_query_payload])

List the names and descriptions of the tables in SIMBAD.

list_votable_fields()

List all options to add columns to SIMBAD's output.

list_wildcards()

Displays the available wildcards that may be used in SIMBAD queries and their usage.

query_bibcode(bibcode, *[, wildcard, ...])

Query the references corresponding to a given bibcode.

query_bibobj(bibcode, *[, criteria, ...])

Query all the objects mentioned in an article.

query_catalog(catalog, *[, criteria, ...])

Query a whole catalog.

query_criteria(*args[, get_query_payload])

query_object(object_name, *[, wildcard, ...])

Query SIMBAD for the given object.

query_objectids(object_name, *[, verbose, ...])

Query SIMBAD with an object name.

query_objects(object_names, *[, wildcard, ...])

Query SIMBAD for the specified list of objects.

query_region(coordinates[, radius, ...])

Query SIMBAD in a cone around the specified coordinates.

query_tap(query, *[, maxrec, get_query_payload])

Query SIMBAD TAP service.

reset_votable_fields()

Reset the output of the query_*** methods to default.

Attributes Documentation

ROW_LIMIT
SIMBAD_URL = 'https://simbad.cds.unistra.fr/simbad/sim-script'
columns_in_output

A list of _Column.

They will be included in the output of the following methods:

hardlimit

The maximum number of lines for SIMBAD’s output.

server

The SIMBAD mirror to use.

tap

A TAPService service for SIMBAD.

Methods Documentation

add_votable_fields(*args)[source]

Add columns to the output of a SIMBAD query.

The list of possible arguments and their description for this method can be printed with list_votable_fields.

The methods affected by this:

Parameters:
argsstr

The arguments to be added.

Examples

>>> from astroquery.simbad import Simbad
>>> simbad = Simbad()
>>> simbad.add_votable_fields('sp_type', 'sp_qual', 'sp_bibcode') 
>>> simbad.get_votable_fields() 
['basic.main_id', 'basic.ra', 'basic.dec', 'basic.coo_err_maj', 'basic.coo_err_min', ...
static clear_cache()[source]

Clear the cache of SIMBAD.

get_field_description(field_name)[source]

Displays a description of the VOTable field.

This can be replaced by the output of list_votable_fields.

Examples

>>> from astroquery.simbad import Simbad
>>> options = Simbad.list_votable_fields() 
>>> description_dimensions = options[options["name"] == "dimensions"]["description"] 
>>> description_dimensions.data.data[0] 
'all fields related to object dimensions'
get_votable_fields()[source]

Display votable fields.

list_columns(*tables: str, keyword=None, get_query_payload=False)[source]

Get the list of SIMBAD columns.

Add tables names to restrict to some tables. Call the function without any parameter to get all columns names from all tables. The keyword argument looks for columns in the selected SIMBAD tables that contain the given keyword. The keyword search is not case-sensitive.

Parameters:
*tablesstr, optional

Add tables names as strings to restrict to these tables columns. This is not case-sensitive.

keywordstr, optional

A keyword to look for in column names, table names, or descriptions.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

get_adqlbool, optional

Deprecated since ‘0.4.8’. This is replaced by get_query_payload that contain more information than just the ADQL string

Returns:
Table

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.list_columns("ids", "ident") 
<Table length=4>
table_name column_name datatype ...  unit    ucd
  object      object    object  ... object  object
---------- ----------- -------- ... ------ -------
     ident          id  VARCHAR ...        meta.id
     ident      oidref   BIGINT ...
       ids         ids  VARCHAR ...        meta.id
       ids      oidref   BIGINT ...

>>> from astroquery.simbad import Simbad
>>> Simbad.list_columns(keyword="filter") 
<Table length=5>
 table_name column_name   datatype  ...  unit           ucd
   object      object      object   ... object         object
----------- ----------- ----------- ... ------ ----------------------
     filter description UNICODECHAR ...        meta.note;instr.filter
     filter  filtername     VARCHAR ...                  instr.filter
     filter        unit     VARCHAR ...                     meta.unit
       flux      filter     VARCHAR ...                  instr.filter
mesDiameter      filter        CHAR ...                  instr.filter

>>> from astroquery.simbad import Simbad
>>> Simbad.list_columns("basic", keyword="object") 
<Table length=4>
table_name column_name datatype ...  unit          ucd
  object      object    object  ... object        object
---------- ----------- -------- ... ------ -------------------
     basic     main_id  VARCHAR ...          meta.id;meta.main
     basic   otype_txt  VARCHAR ...                  src.class
     basic         oid   BIGINT ...        meta.record;meta.id
     basic       otype  VARCHAR ...                  src.class
list_linked_tables(table: str, *, get_query_payload=False)[source]

Expose the tables that can be non-obviously linked with the given table.

This list contains only the links where the column names are not the same in the two tables. For example every oidref column of any table can be joined with any other oidref. The same goes for every otype column even if this is not returned by this method.

Parameters:
tablestr

One of SIMBAD’s tables name

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

Returns:
Table

The information necessary to join the given table to an other.

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.list_linked_tables("otypes") 
<Table length=2>
from_table from_column target_table target_column
  object      object      object        object
---------- ----------- ------------ -------------
  otypedef       otype       otypes         otype
    otypes      oidref        basic           oid
list_tables(*, get_query_payload=False)[source]

List the names and descriptions of the tables in SIMBAD.

Parameters:
get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

get_adqlbool, optional

Deprecated since ‘0.4.8’. This is replaced by get_query_payload that contain more information than just the ADQL string

Returns:
Table
list_votable_fields()[source]

List all options to add columns to SIMBAD’s output.

They are of four types:

  • “column of basic”: a column of the basic table. There fields can also be explored with list_columns.

  • “table”: a table other than basic that has a declared direct join

  • “bundle of basic columns”: a pre-selected bundle of columns of basic. Ex: “parallax” will add all columns relevant to parallax

  • “filter name”: an optical filter name

Examples

>>> from astroquery.simbad import Simbad
>>> options = Simbad.list_votable_fields() 
>>> # to print only the available bundles of columns
>>> options[options["type"] == "bundle of basic columns"][["name", "description"]] 
<Table length=8>
    name                         description
    object                           object
------------- ----------------------------------------------------
  coordinates                  all fields related with coordinates
          dim          major and minor axis, angle and inclination
   dimensions              all fields related to object dimensions
    morphtype         all fields related to the morphological type
     parallax                     all fields related to parallaxes
propermotions           all fields related with the proper motions
           sp            all fields related with the spectral type
     velocity all fields related with radial velocity and redshift
static list_wildcards()[source]

Displays the available wildcards that may be used in SIMBAD queries and their usage.

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.list_wildcards()
*: Any string of characters (including an empty one)
?: Any character (exactly one character)
[abc]: Exactly one character taken in the list. Can also be defined by a range of characters: [A-Z]
[^0-9]: Any (one) character not in the list.
query_bibcode(bibcode, *, wildcard=False, abstract=False, get_query_payload=False, criteria=None, verbose=None, cache=None)[source]

Query the references corresponding to a given bibcode.

Wildcards may be used to specify bibcodes.

Parameters:
bibcodestr

The bibcode of the article to be queried

wildcardbool, defaults to False

When it is set to True it implies that the object is specified with wildcards.

abstractbool, defaults to False

When this is set to True, the abstract of the article is also included to the result.

criteriastr

Criteria to be applied to the query. These should be written in the ADQL syntax in a single string. See example.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

cacheDeprecated since 0.4.8. The cache is now automatically emptied at the

end of the python session. It can also be emptied manually with clear_cache but cannot be deactivated.

Returns:
tableTable

Query results table

Examples

>>> from astroquery.simbad import Simbad
>>> simbad = Simbad()
>>> simbad.ROW_LIMIT = 5
>>> simbad.query_bibcode("2016PhRvL.*", wildcard=True,
...                      criteria="title LIKE '%gravitational wave%coalescence.'") 
<Table length=1>
      bibcode                    doi               journal ... volume  year
       object                   object              object ... int32  int16
------------------- ------------------------------ ------- ... ------ -----
2016PhRvL.116x1103A 10.1103/PhysRevLett.116.241103   PhRvL ...    116  2016
query_bibobj(bibcode, *, criteria=None, get_query_payload=False, verbose=False)[source]

Query all the objects mentioned in an article.

Parameters:
bibcodestr

the bibcode of the article

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

Returns:
tableTable

Query results table

query_catalog(catalog, *, criteria=None, get_query_payload=False, verbose=False, cache=True)[source]

Query a whole catalog.

Parameters:
catalogstr

The name of the catalog. This is case-dependant.

criteriastr

Criteria to be applied to the query. These should be written in the ADQL syntax in a single string. See example.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

cacheDeprecated since 0.4.8. The cache is now automatically emptied at the

end of the python session. It can also be emptied manually with clear_cache but cannot be deactivated.

Returns:
tableTable

The result of the query to SIMBAD.

Notes

Catalogs can be very large. Configuring SimbadClass.ROW_LIMIT allows to restrict the output.

Examples

>>> from astroquery.simbad import Simbad
>>> simbad = Simbad()
>>> simbad.ROW_LIMIT = 5
>>> simbad.query_catalog("GSC", criteria="pmra > 50 and pmra < 100") 
<Table length=5>
    main_id            ra       ...     coo_bibcode        catalog_id
                      deg       ...
     object         float64     ...        object            object
--------------- --------------- ... ------------------- ---------------
      HD  26053  61.84326890626 ... 2020yCat.1350....0G GSC 04725-00973
TYC 8454-1081-1 345.11163189562 ... 2020yCat.1350....0G GSC 08454-01081
      HD  10158  24.86286094434 ... 2020yCat.1350....0G GSC 00624-00340
    CD-22  1862  73.17988827324 ... 2020yCat.1350....0G GSC 05911-00222
    BD+02  4434 327.90220788982 ... 2020yCat.1350....0G GSC 00548-00194
query_criteria(*args, get_query_payload=False, **kwargs)[source]

Deprecated since version v0.4.8: ‘query_criteria’ is deprecated. It uses the former sim-script (SIMBAD specific) syntax (see https://simbad.cds.unistra.fr/simbad/sim-fsam). Possible replacements are the ‘criteria’ argument in the other query methods or custom ‘query_tap’ queries. These two replacements use the standard ADQL syntax.

Query SIMBAD based on any criteria [deprecated].

This method is deprecated as it uses the former SIMBAD-specific sim-script syntax. There are two possible replacements that have been added with astroquery v0.4.8 and that use the standard ADQL syntax. See the examples section.

Parameters:
args:

String arguments passed directly to SIMBAD’s script (e.g., ‘region(box, GAL, 10.5 -10.5, 0.5d 0.5d)’)

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

kwargs:

Keyword / value pairs passed to SIMBAD’s script engine (e.g., {‘otype’=’SNR’} will be rendered as otype=SNR)

Returns:
tableTable

Query results table

Examples

Can be replaced by the criteria argument that was added in the other query_*** methods

>>> from astroquery.simbad import Simbad
>>> Simbad(ROW_LIMIT=5).query_region('M1', '2d', criteria="otype='G..'") 
<Table length=5>
  main_id            ra        ... coo_wavelength     coo_bibcode
                    deg        ...
   object         float64      ...      str1             object
------------ ----------------- ... -------------- -------------------
LEDA  136099 85.48166666666667 ...                1996A&AS..117....1S
LEDA  136047 83.66958333333332 ...                1996A&AS..117....1S
LEDA  136057 84.64499999999998 ...                1996A&AS..117....1S
LEDA 1630996 83.99208333333333 ...              O 2003A&A...412...45P
  2MFGC 4574 84.37534166666669 ...              I 2006AJ....131.1163S

Or by custom-written ADQL queries

>>> from astroquery.simbad import Simbad
>>> Simbad.query_tap("SELECT TOP 5 main_id, sp_type"
...                  " FROM basic WHERE sp_type < 'F3'") 
<Table length=5>
  main_id   sp_type
   object    object
----------- -------
 HD  24033B     (A)
 HD  70218B     (A)
 HD 128284B   (A/F)
CD-34  5319   (A/F)
  HD  80593   (A0)V
query_object(object_name, *, wildcard=False, criteria=None, get_query_payload=False, verbose=False)[source]

Query SIMBAD for the given object.

Object names may also be specified with wildcards. See examples below.

Parameters:
object_namestr

name of object to be queried.

wildcardboolean, optional

When it is set to True it implies that the object is specified with wildcards. This parameter will render the query case-sensitive. Defaults to False.

criteriastr

Criteria to be applied to the query. These should be written in the ADQL syntax in a single string. See example.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

Returns:
tableTable

The result of the query to SIMBAD.

Examples

Get the dimensions of a specific galaxy

>>> from astroquery.simbad import Simbad
>>> simbad = Simbad()
>>> simbad.add_votable_fields("dim") 
>>> result = simbad.query_object("m101") 
>>> result["main_id", "ra", "dec", "galdim_majaxis", "galdim_minaxis", "galdim_bibcode"] 
<Table length=1>
main_id         ra           dec    ... galdim_minaxis    galdim_bibcode
               deg           deg    ...     arcmin
 object      float64       float64  ...    float32            object
------- ------------------ -------- ... -------------- -------------------
  M 101 210.80242916666668 54.34875 ...          20.89 2003A&A...412...45P

Get 5 NGC objects that are clusters of stars

>>> from astroquery.simbad import Simbad
>>> simbad = Simbad()
>>> simbad.ROW_LIMIT = 5
>>> ngc_clusters = simbad.query_object("NGC*", wildcard=True, criteria="otype='Cl*..'") 
>>> ngc_clusters  
<Table length=5>
 main_id          ra        ...     coo_bibcode     matched_id
                 deg        ...
  object       float64      ...        object         object
--------- ----------------- ... ------------------- ----------
NGC  2024 85.42916666666667 ... 2003A&A...397..177B  NGC  2024
NGC  1826 76.39174999999999 ... 2011AJ....142...48W  NGC  1826
NGC  2121 87.05495833333332 ... 2011AJ....142...48W  NGC  2121
NGC  2019 82.98533333333333 ... 1999AcA....49..521P  NGC  2019
NGC  1777             73.95 ... 2008MNRAS.389..678B  NGC  1777
query_objectids(object_name, *, verbose=None, cache=None, get_query_payload=False, criteria=None)[source]

Query SIMBAD with an object name.

This returns a table of all names associated with that object.

Parameters:
object_namestr

name of object to be queried

criteriastr

an additional criteria to constrain the result. As the output of this method has only one column, these criteria can only be imposed on the column ident.id.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

cacheDeprecated since 0.4.8. The cache is now automatically emptied at the

end of the python session. It can also be emptied manually with clear_cache but cannot be deactivated.

Returns:
tableTable

The result of the query to SIMBAD.

Examples

Get all the names of the Bubble Nebula

>>> from astroquery.simbad import Simbad
>>> Simbad.query_objectids("bubble nebula") 
<Table length=8>
              id
            object
------------------------------
[ABB2014] WISE G112.212+00.229
                     LBN   548
                     NGC  7635
                     SH  2-162
          [KC97c] G112.2+00.2b
         [L89b] 112.237+00.226
            GRS G112.22 +00.22
            NAME Bubble Nebula

Get the NGC name of M101

>>> from astroquery.simbad import Simbad
>>> Simbad.query_objectids("m101", criteria="ident.id LIKE 'NGC%'") 
<Table length=1>
    id
  object
---------
NGC  5457
query_objects(object_names, *, wildcard=False, criteria=None, get_query_payload=False, verbose=False, cache=False)[source]

Query SIMBAD for the specified list of objects.

Object names may be specified with wildcards. If one of the object_names is not found in SIMBAD, the corresponding line is returned empty in the output (see Giga Cluster in the example). In the output, the column user_specified_id is the input object name.

Parameters:
object_namessequence of strs

names of objects to be queried

wildcardboolean, optional

When True, the names may have wildcards in them. Defaults to False.

criteriastr

Criteria to be applied to the query. These should be written in the ADQL syntax in a single string. See example.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

cacheDeprecated since 0.4.8. The cache is now automatically emptied at the

end of the python session. It can also be emptied manually with clear_cache but cannot be deactivated.

Returns:
tableTable

The result of the query to SIMBAD.

Examples

>>> from astroquery.simbad import Simbad
>>> clusters = Simbad.query_objects(["Boss Great Wall", "Great Attractor",
...                                  "Giga Cluster", "Coma Supercluster"]) 
>>> clusters[["main_id", "ra", "dec", "user_specified_id"]] 
<Table length=4>
       main_id            ra     dec   user_specified_id
                         deg     deg
        object         float64 float64       object
---------------------- ------- ------- -----------------
  NAME Boss Great Wall   163.0    52.0   Boss Great Wall
  NAME Great Attractor   158.0   -46.0   Great Attractor
                            --      --      Giga Cluster
NAME Coma Supercluster  170.75    23.9 Coma Supercluster
query_region(coordinates, radius=<Quantity 2. arcmin>, *, criteria=None, get_query_payload=False, equinox=None, epoch=None, cache=None)[source]

Query SIMBAD in a cone around the specified coordinates.

Parameters:
coordinatesstr or astropy.coordinates object

The identifier or coordinates around which to query.

radiusstr or Quantity

the radius of the region. Defaults to 2 arcmin.

criteriastr

Criteria to be applied to the query. These should be written in the ADQL syntax in a single string.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

cacheDeprecated since 0.4.8. The cache is now automatically emptied at the

end of the python session. It can also be emptied manually with clear_cache but cannot be deactivated.

Returns:
tableTable

The result of the query to SIMBAD.

Notes

It is very inefficient to call this within a loop. Creating an SkyCoord object with a list of coordinates will be way faster.

Examples

Look for large galaxies in two cones

>>> from astroquery.simbad import Simbad
>>> from astropy.coordinates import SkyCoord
>>> simbad = Simbad()
>>> simbad.ROW_LIMIT = 5
>>> simbad.add_votable_fields("otype") 
>>> coordinates = SkyCoord([SkyCoord(186.6, 12.7, unit=("deg", "deg")),
...                         SkyCoord(170.75, 23.9, unit=("deg", "deg"))])
>>> result = simbad.query_region(coordinates, radius="2d5m",
...                              criteria="otype = 'Galaxy..' AND galdim_majaxis>8") 
>>> result.sort("main_id") 
>>> result["main_id", "otype"] 
<Table length=5>
  main_id    otype
   object    object
------------ ------
LEDA   40577    GiG
LEDA   41362    GiC
       M  86    GiG
       M  87    AGN
   NGC  4438    LIN
query_tap(query: str, *, maxrec=10000, get_query_payload=False, **uploads)[source]

Query SIMBAD TAP service.

Parameters:
querystr

A string containing the query written in the Astronomical Data Query Language (ADQL).

maxrecint, default: 10000

The number of records to be returned. Its maximum value is given by hardlimit.

uploadsTable | VOTableFile | DALResults

Any number of local tables to be used in the query. In the query, these tables are referred as TAP_UPLOAD.table_alias where TAP_UPLOAD is imposed and table_alias is the keyword name you chose. The maximum number of lines for the uploaded tables is 200000.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters without querying SIMBAD. The ADQL string is in the ‘QUERY’ key of the payload. Defaults to False.

Returns:
Table

The response returned by Simbad.

See also

list_tables

The list of SIMBAD’s tables.

list_columns

SIMBAD’s columns list, can be restricted to some tables and some keyword.

list_linked_tables

Given a table, expose non-obvious possible joins with other tables.

Notes

A TAP (Table Access Protocol) service allows to query data tables with queries written in ADQL (Astronomical Data Query Language), a flavor of the more general SQL (Structured Query Language). For more documentation about writing ADQL queries, you can read its official documentation (ADQL documentation) or the Simbad ADQL cheat sheet. See also: a graphic representation of Simbad’s tables and their relations.

Examples

To see the five oldest papers referenced in SIMBAD

>>> from astroquery.simbad import Simbad
>>> Simbad.query_tap("SELECT top 5 bibcode, title "
...                  "FROM ref ORDER BY bibcode") 
<Table length=5>
      bibcode       ...
       object       ...
------------------- ...
1850CDT..1784..227M ...
1857AN.....45...89S ...
1861MNRAS..21...68B ...
1874MNRAS..34...75S ...
1877AN.....89...13W ...

Get the type for a list of objects

>>> from astroquery.simbad import Simbad
>>> Simbad.query_tap("SELECT main_id, otype"
...                  " FROM basic WHERE main_id IN ('m10', 'm13')") 
<Table length=2>
main_id otype
 object object
------- ------
  M  10    GlC
  M  13    GlC

Upload a table to use in a query

>>> from astroquery.simbad import Simbad
>>> from astropy.table import Table
>>> letters_table = Table([["a", "b", "c"]], names=["alphabet"])
>>> Simbad.query_tap("SELECT TAP_UPLOAD.my_table_name.* from TAP_UPLOAD.my_table_name",
...                  my_table_name=letters_table) 
<Table length=3>
alphabet
 object
--------
       a
       b
       c
reset_votable_fields()[source]

Reset the output of the query_*** methods to default.

They will be included in the output of the following methods: