SimbadClass

class astroquery.simbad.SimbadClass[source]

Bases: BaseVOQuery, SimbadBaseQuery

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

TIMEOUT

WILDCARDS

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)

Sets fields to be fetched in the VOTable.

get_field_description(field_name)

Displays a description of the VOTable field.

get_votable_fields()

Display votable fields

list_columns(*tables[, keyword, get_adql])

Get the list of SIMBAD columns.

list_linked_tables(table, *[, get_adql])

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

list_tables(*[, get_adql])

The names and descriptions of the tables in SIMBAD.

list_votable_fields()

Lists all the fields that can be fetched for a VOTable.

list_wildcards()

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

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

Queries the references corresponding to a given bibcode, and returns the results in a Table.

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

Serves the same function as query_bibcode, but only collects the response from the Simbad server and returns.

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

Query all the objects that are contained in the article specified by the bibcode, and return results as a Table.

query_bibobj_async(bibcode, *[, cache, ...])

Serves the same function as query_bibobj, but only collects the response from the Simbad server and returns.

query_catalog(catalog, *[, verbose, cache, ...])

Queries a whole catalog.

query_catalog_async(catalog, *[, cache, ...])

Serves the same function as query_catalog, but only collects the response from the Simbad server and returns.

query_criteria(*args, **kwargs)

Query SIMBAD based on any criteria.

query_criteria_async(*args[, cache])

Query SIMBAD based on any criteria.

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

Queries Simbad for the given object and returns the result as a Table.

query_object_async(object_name, *[, ...])

Serves the same function as query_object, but only collects the response from the Simbad server and returns.

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

Query Simbad with an object name, and return a table of all names associated with that object in a Table.

query_objectids_async(object_name, *[, ...])

Serves the same function as query_objectids, but only collects the response from the Simbad server and returns.

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

Queries Simbad for the specified list of objects and returns the results as a Table.

query_objects_async(object_names, *[, ...])

Same as query_objects, but only collects the response from the Simbad server and returns.

query_region(*args, **kwargs)

Queries the service and returns a table object.

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

Serves the same function as query_region, but only collects the response from the Simbad server and returns.

query_tap(query, *[, maxrec])

Query Simbad TAP service.

remove_votable_fields(*args[, strip_params])

Removes the specified field names from SimbadClass._VOTABLE_FIELDS

reset_votable_fields()

resets VOTABLE_FIELDS to defaults

Attributes Documentation

ROW_LIMIT = 0
SIMBAD_URL = 'https://simbad.cds.unistra.fr/simbad/sim-script'
TIMEOUT = 60
WILDCARDS = {'*': 'Any string of characters (including an empty one)', '?': 'Any character (exactly one character)', '[^0-9]': 'Any (one) character not in the list.', '[abc]': 'Exactly one character taken in the list. Can also be defined by a range of characters: [A-Z]'}
hardlimit

The maximum number of lines for Simbad’s output.

This property is cached to avoid calls to simbad’s capability webpage each time the getter is called.

server

The Simbad mirror to use.

tap

A TAPService service for Simbad.

Methods Documentation

add_votable_fields(*args)[source]

Sets fields to be fetched in the VOTable. Must be one of those listed by list_votable_fields.

Parameters:
list of field_names
get_field_description(field_name)[source]

Displays a description of the VOTable field.

Parameters:
field_namestr

the name of the field to describe. Must be one of those listed by list_votable_fields.

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.get_field_description('main_id')
main identifier of an astronomical object. It is the same as id(1)
>>> Simbad.get_field_description('bibcodelist(y1-y2)')
number of references. The parameter is optional and limit the count to
the references between the years y1 and y2
get_votable_fields()[source]

Display votable fields

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.get_votable_fields()
['main_id', 'coordinates']
list_columns(*tables: str, keyword=None, get_adql=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.

keywordstr, optional

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

get_adqlbool, optional

Returns the ADQL string instead of querying SIMBAD.

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_adql=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_adqlbool, optional

Returns the ADQL string instead of querying SIMBAD.

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_adql=False)[source]

The names and descriptions of the tables in SIMBAD.

Parameters:
get_adqlbool, optional

Returns the ADQL string instead of querying SIMBAD.

Returns:
Table
list_votable_fields()[source]

Lists all the fields that can be fetched for a VOTable.

Examples

>>> from astroquery.simbad import Simbad
>>> Simbad.list_votable_fields()
--NOTES--...
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)...

[^0-9] : Any (one) character not in the list.

? : Any character (exactly one character)

[abc]Exactly one character taken in the list.

Can also be defined by a range of characters: [A-Z]

query_bibcode(bibcode, *, wildcard=False, verbose=False, cache=True, get_query_payload=False)[source]

Queries the references corresponding to a given bibcode, and returns the results in a Table. Wildcards may be used to specify bibcodes.

Parameters:
bibcodestr

the bibcode of the article

wildcardboolean, optional

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

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
tableTable

Query results table

query_bibcode_async(bibcode, *, wildcard=False, cache=True, get_query_payload=False)[source]

Serves the same function as query_bibcode, but only collects the response from the Simbad server and returns.

Parameters:
bibcodestr

the bibcode of the article

wildcardboolean, optional

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

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server.

query_bibobj(bibcode, *, verbose=False, get_query_payload=False)[source]

Query all the objects that are contained in the article specified by the bibcode, and return results as a Table.

Parameters:
bibcodestr

the bibcode of the article

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

Returns:
tableTable

Query results table

query_bibobj_async(bibcode, *, cache=True, get_query_payload=False)[source]

Serves the same function as query_bibobj, but only collects the response from the Simbad server and returns.

Parameters:
bibcodestr

the bibcode of the article

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server.

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

Queries a whole catalog.

Results may be very large -number of rows should be controlled by configuring SimbadClass.ROW_LIMIT.

Parameters:
catalogstr

the name of the catalog.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
tableTable

Query results table

query_catalog_async(catalog, *, cache=True, get_query_payload=False)[source]

Serves the same function as query_catalog, but only collects the response from the Simbad server and returns.

Parameters:
catalogstr

the name of the catalog.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server.

query_criteria(*args, **kwargs)[source]

Query SIMBAD based on any criteria.

Parameters:
args:

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

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

query_criteria_async(*args, cache=True, **kwargs)[source]

Query SIMBAD based on any criteria.

Parameters:
args:

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

kwargs:

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

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server

query_object(object_name, *, wildcard=False, verbose=False, get_query_payload=False)[source]

Queries Simbad for the given object and returns the result as a Table. Object names may also be specified with wildcard. 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. Defaults to False.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

Returns:
tableTable

Query results table

query_object_async(object_name, *, wildcard=False, cache=True, get_query_payload=False)[source]

Serves the same function as query_object, but only collects the response from the Simbad server and returns.

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. Defaults to False.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server

query_objectids(object_name, *, verbose=False, cache=True, get_query_payload=False)[source]

Query Simbad with an object name, and return a table of all names associated with that object in a Table.

Parameters:
object_namestr

name of object to be queried

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
tableTable

Query results table

query_objectids_async(object_name, *, cache=True, get_query_payload=False)[source]

Serves the same function as query_objectids, but only collects the response from the Simbad server and returns.

Parameters:
object_namestr

name of object to be queried

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server.

query_objects(object_names, *, wildcard=False, verbose=False, get_query_payload=False)[source]

Queries Simbad for the specified list of objects and returns the results as a Table. Object names may be specified with wildcards if desired.

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.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

Returns:
tableTable

Query results table

query_objects_async(object_names, *, wildcard=False, cache=True, get_query_payload=False)[source]

Same as query_objects, but only collects the response from the Simbad server and returns.

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.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server

query_region(*args, **kwargs)

Queries the service and returns a table object.

Serves the same function as query_region, but only collects the response from the Simbad server and returns.

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.

equinoxfloat, optional

the equinox of the coordinates. If missing set to default 2000.0.

epochstr, optional

the epoch of the input coordinates. Must be specified as [J|B] <epoch>. If missing, set to default J2000.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
tableA Table object.
query_region_async(coordinates, radius=<Quantity 2. arcmin>, *, equinox=2000.0, epoch='J2000', cache=True, get_query_payload=False)[source]

Serves the same function as query_region, but only collects the response from the Simbad server and returns.

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.

equinoxfloat, optional

the equinox of the coordinates. If missing set to default 2000.0.

epochstr, optional

the epoch of the input coordinates. Must be specified as [J|B] <epoch>. If missing, set to default J2000.

get_query_payloadbool, optional

When set to True the method returns the HTTP request parameters. Defaults to False.

cachebool

Defaults to True. If set overrides global caching behavior. See caching documentation.

Returns:
responserequests.Response

Response of the query from the server.

query_tap(query: str, *, maxrec=10000, **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.

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
remove_votable_fields(*args, strip_params=False)[source]

Removes the specified field names from SimbadClass._VOTABLE_FIELDS

Parameters:
list of field_names to be removed
strip_params: bool, optional

If true, strip the specified keywords before removing them: e.g., ra(foo) would remove ra(bar) if this is True

reset_votable_fields()[source]

resets VOTABLE_FIELDS to defaults