Treasure Map

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
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

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

NOT REQUIRED

pos_angle

Position angle of telescope exposure

depth_err

(decimal) error in the depth, can be a rough estimation

If you are posting a pointing that has already been COMPLETED

All of the same requirements for a planned pointing are the same EXCEPT pos_angle is now required

You can update an already planned pointing to be completed

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

To request a DOI

(Only for completed pointings)

You must pass in fields:

request_doi=true
creators=[{'name':'name1', 'affiliation':'affiliation1'}]

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)",
                "band":"U",
                "instrumentid":"instrumentname1",
                "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&param2=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'

band=band1
bands=[band1, band2, band3...]

Valid bands are in [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]

instrument=inst1
instruments=[inst1, inst2, inst3...]

Can be a list of instrument ids or a list of instrument names

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)

REST API METHOD: GET Instructions

Usage

/api/v0/instruments?param1=value1&param2=value2…

Parameters

api_token=abcdefghijkl
id=id1
ids=[id1, id2, id3...]
name=name1
names=[name1, name2, name3...]
type=type1

Instrument types are spectroscopic, photometric

GET Examples

GET all photometric instruments:

                        
        import requests
        import urllib.parse

        BASE = 'http://treasuremap.space/api/v0'
        TARGET = 'instruments'

        params = {
            "api_token":"abcdefghijkl",
            "type":"photometric"
        }

        url = "{}/{}?{}".format(BASE, TARGET, urllib.parse.urlencode(params))

        r = requests.get(url = url)

        print(r.text)

REST API METHOD: POST Instructions

Requesting a Batch DOI for completed pointings

Usage

/api/v0/request_doi

Notes

This endpoint will ideally be utilized as an end of the night routine as you are uploading your completed pointings as they are taken in real time

You will request your DOI Url from a list of completed pointings, or just a GW Event GraceID for completed pointings that do not have a DOI yet.

This endpoint will validate:

whether the pointings have a status completed
whether the pointings were submitted by the user associated with the api_token
whether the pointings were taken for the same GW event. They must be associated with the same graceid

JSON Parameters

graceid=graceid1
api_token=api_token1

this will ensure only your completed pointings are queried

creators=json list of creator objects

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
also accepts orcid and gnd for each creator

doi_group_id=groupid1

if you have created a doi author list through the website, you just reference its name or id here to link to the list

ids=[id1, id2, id3....]

List of INTs

POST Examples

Request a DOI for your completed pointings for a GW Event

                        
        import requests

        BASE = 'http://treasuremap.space/api/v0/'
        TARGET = 'request_doi'

        json_data = {
            "api_token":"abcdefghijkl",
            "graceid":"graceid1",
            "creators":[
                {"name":"Name1", "affiliation":"affil_1"},
                {"name":"Name2", "affiliation":"affil_2"}
            ]
        }

        r = requests.post(url = BASE+TARGET, json = json_data)

        print(r.text)

Request a DOI for individual pointing IDs

                    
        import requests

        BASE = 'http://treasuremap.space/api/v0/'
        TARGET = 'request_doi'

        json_data = {
            "api_token":"abcdefghijkl",
            "ids":"[id1, id2, id3, ...]",
            "creators":[
                    {"name":"Name1", "affiliation":"affil_1"},
                    {"name":"Name2", "affiliation":"affil_2"}
            ]
        }

        r = requests.post(url = BASE+TARGET, json = json_data)

        print(r.text)

Documentation

API Endpoints:

REST API METHOD: POST Instructions

Valid pointing class parameters

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)

JSON example

Updating completed pointings

REST API METHOD: GET Instructions

GET Examples

REST API METHOD: POST Instructions

UPDATE Examples

Updating Planned Pointings to be cancelled

REST API METHOD: POST Instructions

UPDATE Examples

Updating Planned Pointings to be cancelled

REST API METHOD: GET Instructions

GET Examples

REST API METHOD: POST Instructions

POST Examples