Documentation

Communicating with the Treasure Map to either report or get information is best done programmatically through the API using POST and GET methods (see below). However, one can also use the pages on this website to report and get the information. Below are examples of two use cases for the API methods.

You can find these API endpoints utilized in our Jupyter notebook tutorial.
We also point users to a Python script produced by a Treasure Map user, Dougal Dobie, and shared in the spirit of the Treasure Map community on Github here, that manages pointing uploads to Treasure Map using the API defined below.

  1. I am an observer and I would like to report my observations

    Great! Before you can start you must register an account through this website. Then you will be issued a token that you will use to post your reports.
    Once you have an account, also please check whether your imaging instrument is listed (either on the website or by using the instruments GET method - see below), and make a note of its ID. If it isn't listed, please submit it.

    Once you and your instrument are registered, here's a typical scenario to follow: (You may test your POST scripts using the graceid 'TEST_EVENT', and inspect the results here.)
    • A GW alert comes in, and you or your software decide on a list of pointings to observe with your telescope.
    • You send this list of pointings using the pointings POST method (see below), with a status of planned.
    • As you observe your pointings you send them (either one by one as they are observed, or in bulk) with the same POST method but this time with a status of completed.
      • For validation of your efforts you can request a DOI for your completed pointings as you post them in bulk, or after the fact through the api endpoint for a list of pointing IDs
      • To create an author list for your DOI, please visit your Profile page and follow the links to do so. Use the ID of your group in requesting the DOI. Otherwise you can still submit a json object via the API (described below). Authors do not have to be GWTM users
    • If there are pointings you had submitted as planned but then realize you will not get to, you can cancel them (so that others know that they won't be covered).

  2. I would like to see what others are observing in order to plan my observations accordingly

    You are required to register. Use your API token you receive upon registration along with the pointings GET method (see below) to retrieve reported planned or completed pointings for a specific GW alert, time window, instrument, and/or band.

API Endpoints:

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...]
    • Notes
    • 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)