The query pages of Simbad can be used directly in any application, or using standard tools like curl or wget. The result can be provided in HTML, ASCII or VOTable.
This documentation will describe how to write the URLs for querying Simbad and detail the required parameters. Be careful, some characters are not allowed in URLs. http://www.w3schools.com/tags/ref_urlencode.asp
The following urls can be used to query Simbad (each one is shown as a valid example):
This Url is the most recommended one as it allows fine tuning of the output.
The following URLs do specialized queries and require parameters to specify the data to output.
They are processed by the url
https://simbad.cds.unistra.fr/simbad/sim-script?script=...}
The script parameter consist of script commands separated by a newline char. All the script commands described in this help page can be used in an URL.
Main commands to consider for a URL query are:
Example: format object "%IDLIST(1) | %-27COO(A D) | %FLUX(B;F) | %SP(S)"
To define a votable output with a list of requested fields. All the available field names for the votable are described here.
Example:
votable v1 {
MAIN_ID
COO
SP
}
votable open v1
sirius
votable close
Example:
query id hd 100
m31
Radius, frame, epoch and equinox can be factorized in global commands:
set radius=... set frame=... set equi=... set epoch=...
Example:
output console=off script=off
format object "%-35IDLIST(1) | %-27COO(s;A D) | %6.3FLUXLIST(B;F) | "+
"%6.3FLUXLIST(V;F) | %-15SP(S) | nbref=%#BIBCODELIST"
set epoch 1950
query coo 12 30 +10 20 radius=10m
echodata ===================
query coo 13 29 52.37 +47 11 40.8 radius=30s
Example:
format object "%-35IDLIST(1) | %-27COO(s;A D) | %MEASLIST(ubv)[%*(F)]"
query sample dec > 85 & ubv.b < 6
URLs for specialized queries are:
Each of them have their own set of parameters, but share also a set of output definition
parameters which are described later.
All the parameters are case sensitive.
Url example : https://simbad.cds.unistra.fr/simbad/sim-id?Ident=m31
The parameters are:
name | values | description | |||||||||
Ident= | Identifier, wildcard expression or catalogue name | Identifier or acronym to query | |||||||||
NbIdent= | [1|around|wildcard|cat] |
| |||||||||
Radius= | a decimal radius value | Radius for 'around' query. See also Radius.unit parameter | |||||||||
Radius.unit= | [arcsec|arcmin|deg] |
| |||||||||
|
See below for the output definition parameters
Url example : https://simbad.cds.unistra.fr/simbad/sim-coo?Coord=10h30+%2B12d20&Radius=15&Radius.unit=arcmin
The parameters are:
name | values | description | ||||||||||||
Coord= | right ascension declination longitude latitude | Coordinates which van be written in several formats:
| ||||||||||||
Radius= | a decimal radius value | Radius for 'around' query. See also Radius.unit parameter | ||||||||||||
Radius.unit= | [arcsec|arcmin|deg] |
| ||||||||||||
CooFrame= | [ICRS|FK5|FK4|GAL|SGAL|ECL | Coordinate frame:
| ||||||||||||
CooEpoch= | Epoch of the submitted coordinates (default: 2000) | |||||||||||||
CooEqui= | Equinox of the submitted coordinates (default: 2000) |
See below for the output definition parameters
Url example : https://simbad.cds.unistra.fr/simbad/sim-sam?Criteria=dec>86%26ra>22%26Bmag<8%26cat=%27HIP%27&OutputMode=LIST&maxObject=100 The parameters are:
name | values | description | ||||||
Criteria= | a criteria expression | All the possible criteria names and the corresponding operators are described in the query by criteria page. | ||||||
OuputMode= | [COUNT|LIST|REF] | Defines the expected output:
| ||||||
maxObject= | Maximum number of objects to return (abs. maximum: currently 50000) |
See below for the output definition parameters
Reference queries can be of two types, distinguished by the submit parameter:
Url example : https://simbad.cds.unistra.fr/simbad/sim-ref?submit=submit+bibcode&bibcode=2003AN.324.61M
Such a query can be performed either by giving a complete bibcode (parameter bibcode), or by giving elements of a bibcode. Any part(s) among the year (byear), the journal (bjournal), the volume(bvolume) and/or the page (bpage) can be defined to retrieve the corresponding list of references.
name | values | description |
submit= | submit bibcode | written like this |
bibcode= | bibcode | A bibcode. It can be written shorter than the normalized bibcode (19 chars) as long as a dot ('.') separates each item after the journal abbreviation. |
simbo= | on | display the list of objects in the reference. This parameter can be used only with a complete bibcode |
byear= | year | a bibcode year (4 digits) |
bjournal= | journal abbreviation | a journal abbreviation |
bvolume= | volume | a volume number |
bpage= | page number | a page number |
Url example : https://simbad.cds.unistra.fr/simbad/sim-ref?submit=submit+criteria&fromyear=2005&toyear=2006&words=xmm
These parameters allow to find a list of references in SIMBAD based on criteria on journals (journal), year range (fromyear and toyear), author names (authors) and/or words in the title (words).
name | values | description |
submit= | submit criteria | written like this |
journal= | list of journal abbreviations | the list |
fromyear= | lower year limit | first year to search for references |
toyear= | upper year limit | last year (inclusive) to search for references |
authors= | author names | list of authors separated by operators '|' (or) or '&' (and) |
words= | title words | list of words in the title separated by operators '|' (or) or '&' (and) |
SIMBAD has two kind of outputs:
Output parameters can be global (usable for all kind of output) or relevant of only one particular kind.
The remaining of this section will describe all output parameters grouped by data type. Default value, if any, is written in boldface.
These output definition parameters are common to all kind of outputs:
name | values | description |
output.format= | HTML|VOTable|ASCII | Defines the output format (HTML page, only ASCII or VOTable) |
output.max= | max # of objects | Maximum number of objects to display. This number is in any case limited currently to 50,000 |
The object type is always displayed with an astronomical object.
name | values | description |
list.otypesel= | on|off | display or not the main object type in a list |
otypedisp= | S|V|3|N | display format for the object type: S = standard (6 chars max), V = verbose description, 3 = short abbreiviation on 3 chars max (default), N = numeric display (NN.NN.NN.NN) |
Four coordinates can be displayed for an astronomical object.
name | values | description |
obj.cooN= | on|off | display for an object the N-th coordinate (N=1..4). See below how to specify the frame 4 coordinates are displayed for an astronomical object |
list.cooN= | on|off | display in a list the N-th coordinate (N=1..4). See below how to specify the frame Only list.coo1 is on by default |
frameN= | ICRS|FK5|FK4|GAL|SGAL|ECL | define the frame for the N-th (N=1..4) coordinates |
epochN= | [B|J]year | define the epoch for the N-th (N=1..4) coordinates |
equiN= | year | define the equinox for the N-th (N=1..4) coordinates |
coodispN= | [s|d][2] | define the coordinates format for the N-th (N=1..4) coordinates: s = sexagesimal, d = decimal, 2 = space insertion between ra and dec |
name | values | description |
obj.pmsel= | on|off | display or not the proper motions in an astronomical object |
list.pmsel= | on|off | display or not the proper motions in a list |
name | values | description |
obj.plxsel= | on|off | display or not the parallaxes in an astronomical object |
list.plxsel= | on|off | display or not the parallaxes in a list |
name | values | description |
obj.rvsel= | on|off | display or not the radial velocities in an object |
list.rvsel= | on|off | display or not the radial velocities in a list |
rvDisplay= | R|Z|V | define which value will be displayed: R = the radial velocity or the redshift, as stored in the database, Z = force a redshift display, V = force a radial velocity display |
name | values | description |
obj.spsel= | on|off | display or not the spectral type in an astronomical object |
list.spsel= | on|off | display or not the spectral type in a list |
name | values | description |
obj.mtsel= | on|off | display or not the morphological type in an astronomical object |
list.mtsel= | on|off | display or not the morphological type in a list |
name | values | description |
obj.sizesel= | on|off | display or not the size of an astronomical object (extended objects) |
list.sizesel= | on|off | display or not the size in a list |
name | values | description |
obj.fluxsel= | on|off | display or not the fluxes of an astronomical object. For an object, all the available fluxes are always displayed |
list.fluxsel= | on|off | display or not the fluxes in a list. They can be specified by the parameters filtername=on. |
filtername= | on|off | display the flux value of the given filters set to 'on'. Please, check the list of available filter names in the corresponding combobox on the Output options web page. |
In an astronomical object display, the identifiers are always displayed.
name | values | description |
list.idsel= | on|off | display or not an identifier in a list. Only one identifier will be displayed in a list. It can be defined with the other parameters in this section. |
list.idopt= | FIRST|CATLIST | identifier display option: FIRST = first identifier, CATLIST = display the first identifier present in the list of acronyms specified in the list.idcat parameter |
list.idcat= | list of catalog names | list of comma separataed acronyms. The displayed identifier is the first one found in this list. if none is found, the first identifier will be displayed |
name | values | description | ||||||||||||
obj.bibsel= | on|off | display or not the bibliographic data of an astronomical object, according to the other parameters | ||||||||||||
list.bibsel= | on|off | display or not the number of bibliographic references in a list. The number is computed according to some other parameters | ||||||||||||
bibyear1= | year | select references from this given year up (inclusive lower limit) | ||||||||||||
bibyear2= | year | select references up to the given year (inclusive upper limit) | ||||||||||||
bibjnls= | list of journals | select only the journals belonging to the comma separated list of journal abbreviations | ||||||||||||
bibdisplay= | display type | For astronomical object full display, choose the kind of reference display.
All these display take in account the restrictions imposed by bibyearN and bibjnls.
| ||||||||||||
bibcom= | on|off | display or not the comments when the reference summary is displayed | ||||||||||||
bibtabular= | on|off | if on, the main reference data are displayed in a tabular format |
In a list, only the number of measurements for a specified list of catalogs can be displayed. The display in an astronomical object depends on the mesdisp parameter.
name | values | description |
obj.messel= | on|off | display or not the measurements of an astronomical object. The display is done according to the mesdisplay parameter |
list.messel= | on|off | display or not the number of measurements in a list. The catalogs for which the number of measurements is displayed are defined in the list.mescat parameter. |
mesdisplay= | N|A|M|F | display option: N = number of measurements, A = all measurements, F = first measurement, M = mean value (when it exists) |
list.mescat= | list of meas. catalogs | list of measurements catalogs to display. in a list, only the number of measurements for these catalogs will be displayed |
In a list, only the number of notes can be displayed.
name | values | description |
obj.notesel= | on|off | display or not the notes of an astronomical object |
list.notesel= | on|off | display or not the number of notes in a list |
notedisplay= | N|S|A | display option: N = number of notes (imposed in a list), S = only essential (short) notes (default for objects), A = all notes |