APIs
eRODat has a set of APIs (Application Programming Interfaces), which allow its functionality to be used from your programs or scripts. These include a catalogue cone search, obtaining upper limits and code to find the sky tile associated with a position.
1. Simple cone search API
The eROSITA source catalogues can be access via a Simple Cone Search API, supported by many programs or libraries. The URL for accessing the catalogue follows
https://erosita.mpe.mpg.de/erodat/catalogue/SCS?CAT={CATALOGUE}&RA={RA}&DEC={DEC}&SR={RADIUS}&VERB={VERBOSITY}
In this URL change {CATALOGUE} to be one of DR2_Main, DR2_Hard, DR1_Main, DR1_Hard, DR1_Supp and DR1_Clusters.
{RA} and {DEC} give the position to search around (decimal degrees).
{RADIUS} is the search radius in degrees (maximum 5).
{VERBOSITY} selects which columns to return (1 gives the fewest, 3 all columns).
Please find an example URL here.
For TOPCAT, the URL https://erosita.mpe.mpg.de/erodat/catalogue/SCS?CAT=DR1_Main can be used to search the main catalogue.
2. Upper limit API
The following two APIs allow you to obtain upper limits for sky positions. One is intended for single positions, while the other can efficiently return limits for a large number of coordinates or for multiple bands.
Please note that the old API using sciserver will be retired soon. Please switch to using the following upper limit APIs on erosita.mpe.mpg.de.
2.1 Single position
This API is for returning the upper limit for a single position and band. The URL scheme for this API (example here) follows
https://erosita.mpe.mpg.de/erodat/upperlimit/service?ra={RA}&dec={DEC}&band={BAND}&dr_survey={DR_SURVEY}
The placeholders {RA} and {DEC} specify the equatorial coordinates in decimal degrees.
{BAND} gives the band, where the supported values for DR1_eRASS1 are 021, 022, 023, 024 and 02e.
For DR2_eRASSc3, only bands 023 and 024 are allowed.
The optional argument dr_survey specifies the data release and survey, where its supported options are DR1_eRASS1 (DR1 eRASS1, which is the default) and DR2_eRASSc3 (DR2 eRASS:3).
The output is in JSON. An example Python program is as follows (requires the requests module):
import requests
RA, DEC, BAND, DR_SURVEY = 194.0, -5.7, '024', 'DR1_eRASS1'
url = f'https://erosita.mpe.mpg.de/erodat/upperlimit/service?ra={RA}&dec={DEC}&band={BAND}&dr_survey={DR_SURVEY}'
req = requests.get(url)
assert req.status_code == 200
print(req.json())
This prints the Python dictionary:
{
"Count": 0,
"Bkg_counts": 0.817130982875824,
"Bkg_SourceMap": 0.8311792016029358,
"Exposure": 127.030517578125,
"UL_B": 6.48967912828674e-14,
"UL_S": 6.48967912828674e-14,
"Flag_pos": 0,
"de_sky": true,
"field": 194096,
"healpix": 27400491658,
"ra": 194.0,
"dec": -5.7,
"band": "024",
"dr_survey": "DR1_eRASS1"
}
2.2 Multiple positions and/or bands
This service supports looking up of limits of multiple positions and/or bands. This should be preferred for efficiency if looking up results for many objects. Currently there is a limit of 10000 lookups in one call. JSON data of a list of positions and bands should be POSTed to the server as in this example Python code (requires the requests module):
import requests
url = 'https://erosita.mpe.mpg.de/erodat/upperlimit/service_multi'
query = [
{
'ra': 180.0, 'dec': -45.0, 'band': '021',
},
{
'ra': 185.0, 'dec': -50.0, 'band': '024',
'dr_survey': 'DR1_eRASS1', # default value
},
{
# outside DE sky region
'ra': 180.0, 'dec': 45.0, 'band': '021',
},
]
req = requests.post(url, json=query)
assert req.status_code == 200
results = req.json()
The result of this is a Python dictionary containing the limits in the same order as the input values:
{'limits': [{'Count': 0,
'Bkg_counts': 0.234102264046669,
'Bkg_SourceMap': 0.2342136949300766,
'Exposure': 185.2670135498047,
'UL_B': 4.6609814125702156e-14,
'UL_S': 4.6609814125702156e-14,
'Flag_pos': 0,
'de_sky': True,
'field': 180135,
'healpix': 45779430016,
'ra': 180.0,
'dec': -45.0,
'band': '021',
'dr_survey': 'DR1_eRASS1'},
{'Count': 1,
'Bkg_counts': 1.0879173278808594,
'Bkg_SourceMap': 1.0886847972869873,
'Exposure': 203.35076904296875,
'UL_B': 5.029558651612094e-14,
'UL_S': 5.0293604459024366e-14,
'Flag_pos': 0,
'de_sky': True,
'field': 187141,
'healpix': 45647516908,
'ra': 185.0,
'dec': -50.0,
'band': '024',
'dr_survey': 'DR1_eRASS1'},
{'de_sky': False,
'field': 180045,
'healpix': 11470023359,
'ra': 180.0,
'dec': 45.0,
'band': '021',
'dr_survey': 'DR1_eRASS1'}],
'error': 'None'}
If the result in 'error' is not 'None', likely something was wrong in your input parameters.
3. Skytile search API
The eROSITA data are split into skytiles defined in a FITS file. To convert sky positions to a list of skytiles, you can also use this API:
https://erosita.mpe.mpg.de/erodat/skyview/skytile_search_api/?RA={RA}&DEC={DEC}&RAD={RAD}
{RA} and {DEC} give the position to search around (decimal degrees).
{RAD} is the optional maximum radius in decimal degrees (default 0 for a point).
The returned data is in a JSON format (use json.loads in Python).
An example is this sky position.
The tiles attribute returns a list of tiles.
Each tile has its number (srvmap), whether it is the eROSITA-DE sky (de_sky), the RA and Dec range (ra_min, ra_max, de_min, de_max), the RA and Dec of the tile centre (ra_cen and de_cen), and the distance of the tile centre to the position in degrees (dist_deg).
The result can be loaded in Python using the requests module, e.g. requests.get(URL).json().