GET, POST, and UPDATE your telescope pointings
REST API METHOD: POST Instructions
USAGE:
/api/v0/pointings
Notes
- Upon successful entry, you will be returned a list of pointing ids
- Warnings will be successfully entered, and will notify you of the warning and json object
- Errors will not be successfully entered, and will notify you of the error and json object
JSON Parameters
- graceid - string value of the gw_alert graceid
- api_token - authentication api token
- pointings - list of JSON objects for valid pointing class
- request_doi - [default=false] to request a Digital Object Identifier. This is only valid for posting completed pointing observations
- doi_url - associate the submitted pointings to an already existing DOI (I.E. a URL to a Publication). creators and doi_group_id are not needed for this
- creators - json list of names and affiliations for authors in the DOI. Not required, will default to the user's information associated with the api_token
- doi_group_id - if you have created an authors list through the website, you can link either the name of the group or the id
Valid pointing class parameters
If you are posting a PLANNED pointing Observation
REQUIRED
- position: two acceptable formats
- geometry type: POINT(RA DEC)
- simply pass two json fields that are RA and DEC which must be decimal
- instrumentid
- Can be ID or name of valid instrument
- time
- Mid-point time of planned/completed pointing
- Must be %Y-%m-%dT%H:%M:%S format; e.g. 1991-12-23T19:15:11
- status=completed
- planned
- depth
- 5-sigma limiting flux of exposure decimal
- depth_unit
- units for depth. Can be: ab_mag, vega_mag, flux_erg, or flux_jy
- Bandpass Information: is required can be passed in by stating the band, or the range of wavelengths, energies, or frequencies the pointing covers. If your pointing is associated with a bandpass, we will calculate the wavelength range from a generic set of filters from SVO
- Method 1: Bandpass List
- band
- Must be one of U, B, V, R, I, J, H, K, u, g, r, i, z, UVW1, UVW2, XRT, clear, open, UHF, VHF, L, S, C, X, other, TESS, BAT, HESS, WISEL
- Method 2: Central Wavelength and Bandwidth
- central_wave
- bandwidth
- both must be floats
- Method 3: Spectrum Regimes There are 3 ways to submit a spectrum regime for your associated pointing. By stating the wavelength, energy, or frequency regimes along with their associated units
- wavelength_regime: must be a list of '[low,high]'
- wavelength_unit: valid inputs are: angstrom, nanometer or micron
- energy_regime: must be a list of '[low, high]'
- energy_unit: valid inputs are: eV, keV, MeV, GeV, and TeV
- frequency_regime: must be a list of '[low, high]'
- frequency_unit: cvalid inputs are:Hz, kHz, MHz, GHz and THz
- pos_angle
- Position angle of telescope exposure
- depth_err
- (decimal) error in the depth, can be a rough estimation
- All of the same requirements for a planned pointing are the same EXCEPT pos_angle is now required
- Inside the valid pointing class you can pass:
- id
- can only be for your planned pointings
- time
- status
- pos_angle
- depth and depth_err
- If those values are to be updated
- You must pass in fields:
- request_doi=true
- doi_url=my_doi_url.com
- creators=[{'name':'name1', 'affiliation':'affiliation1'}]
NOT REQUIRED
If you are posting a pointing that has already been COMPLETED
You can update an already planned pointing to be completed
To request a DOI
(Only for completed pointings)
OR to request through Zenodo
JSON example
import requests
BASE = 'http://treasuremap.space/api/v0/'
TARGET = 'pointings'
json_data = {
"graceid":"graceid1",
"api_token":"abcdefghijkl",
"pointings":[
{
"ra":42,
"dec":42.0,
"band":"V",
"instrumentid":"20",
"depth":"19.5",
"depth_unit":"ab_mag",
"time":"2019-05-22T12:30:59",
"pos_angle":"45.0",
"status":"completed"
},
{
"position":"POINT(42 42)",
"central_wave":6500,
"bandwidth":1200,
"wavelength_unit":"angstrom",
"instrumentid":"instrumentname1",
"depth":"5e-12",
"depth_unit":"flux_erg"
"time":"2019-05-22T12:30:59",
"status":"planned"
},
{
"position":"POINT(42 42)",
"energy_regime":[0.39,1.1],
"energy_unit":"keV",
"instrumentid":"Swift/XRT",
"depth":"19.5",
"depth_unit":"ab_mag"
"time":"2019-05-22T12:30:59",
"status":"planned"
}]
}
r = requests.post(url = BASE+TARGET, json = json_data)
print(r.text)
Updating completed pointings
import requests
BASE = 'http://treasuremap.space/api/v0/'
TARGET = 'pointings'
json_data = {
"graceid":"graceid1",
"api_token":"abcdefghijkl",
"request_doi":true,
"creators":[
{"name":"Name1", "affiliation":"affil_1"},
{"name":"Name2", "affiliation":"affil_2"}
],
"pointings":[
{
"id":"42"
"depth":"19.5",
"depth_err":"0.1"
"time":"2019-05-22T12:33:59",
"pos_angle":"45.0",
"status":"completed"
},
{
"id":"43"
"depth":"19.3",
"depth_err":"0.2"
"time":"2019-05-22T12:35:59",
"pos_angle":"45.0",
"status":"completed"
}]
}
r = requests.post(url = BASE+TARGET, json = json_data)
print(r.text)
REST API METHOD: GET Instructions
Usage
/api/v0/pointings?param1=value1¶m2=value2…
Parameters
- api_token=abcdefghijkl
- graceid=gid1
- id=id1
- ids=[id1, id2, id3...]
- status=status1
- statuses=[status1, status2...]
- status are planned, completed, and cancelled
- completed_after=datetime1
- completed_before=datetime1
- planned_after=datetime1
- planned_before=datetime1
- All datetimes should be in %Y-%m-%dT%H:%M:%S. e.g. 1991-12-23T19:15:11
- group=group1
- Can be group id or group name
- groups=[group1, group2...]
- Can be a list of group ids or a list of group names
- user=user1
- Can be user id, or username, or user's 'firstname lastname'
- users=[user1, user2...]
- Can be a list user ids, list of usernames, or a list of user's 'firstname lastname'
- Bandpass: pointings can be queried and filtered in the same manner they are posted to the database.
- Method 1: Bandpass List
- band
- Must be one of U, B, V, R, I, J, H, K, u, g, r, i, z, UVW1, UVW2, XRT, clear, open, UHF, VHF, L, S, C, X, other, TESS, BAT, HESS, WISEL
- Method 2: Spectrum Regimes There are 3 ways to filter a pointing based off of spectrum regime: stating the wavelength, energy, or frequency regimes along with their associated units
- wavelength_regime: must be a list of '[low,high]'
- wavelength_unit: valid inputs are: angstrom, nanometer or micron
- energy_regime: must be a list of '[low, high]'
- energy_unit: valid inputs are: eV, keV, MeV, GeV, and TeV
- frequency_regime: must be a list of '[low, high]'
- frequency_unit: valid inputs are:Hz, kHz, MHz, GHz and THz
- instrument=inst1
- instruments=[inst1, inst2, inst3...]
- Can be a list of instrument ids or a list of instrument names
- Notes
GET Examples
GET all planned pointings taken in XRT for graceid gw170817:
import requests
import urllib.parse
BASE = 'http://treasuremap.space/api/v0'
TARGET = 'pointings'
params = {
"api_token":"abcdefghijkl",
"band":XRT,
"status":"planned",
"graceid":"gw170817"
}
url = "{}/{}?{}".format(BASE, TARGET, urllib.parse.urlencode(params))
r = requests.get(url = url)
print(r.text)
REST API METHOD: POST Instructions
NOTES
- Will simply cancel all pointings' statuses
USAGE
/api/v0/update_pointings?param=value1
Parameters
- api_token=abcdefghijkl
- status=status1
- must be updated from planned to cancelled
- id=id1
- ids=[id1, id2, id3...]
UPDATE Examples
Updating Planned Pointings to be cancelled
import requests
import urllib.parse
BASE = 'http://treasuremap.space/api/v0'
TARGET = 'update_pointings'
params = {
"api_token":"abcdefghijkl",
"ids":[42,43,44,45],
"status":"cancelled"
}
url = "{}/{}?{}".format(BASE, TARGET, urllib.parse.urlencode(params))
r = requests.post(url = url)
print(r.text)
REST API METHOD: POST Instructions
NOTES
- Will simply cancel all instruments' planned pointings' statuses for a given GW event
USAGE
/api/v0/cancel_all?param=value1
Parameters
- api_token=abcdefghijkl
- graceid=graceid1
- instrumentid=instrumentid1
UPDATE Examples
Updating Planned Pointings to be cancelled
import requests
import urllib.parse
BASE = 'http://treasuremap.space/api/v0'
TARGET = 'cancel_all'
params = {
"api_token":"abcdefghijkl",
"graceid":"TEST_EVENT",
"instrumentid":1
}
url = "{}/{}?{}".format(BASE, TARGET, urllib.parse.urlencode(params))
r = requests.post(url = url)
print(r.text)