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

    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
      • doi_url=my_doi_url.com

        • OR to request through Zenodo

      • 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)",
                "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&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'
  • 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

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
  • doi_url=doi_url1
    • if you have an existing DOI url (I.E. publication URL) it will associate the pointings to that
  • 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)

Submit 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, ...]",
            "doi_url":"my_doi_url.com"
        }

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

        print(r.text)

GET and POST Convolved Galaxy Information

REST API METHOD: POST Instructions

Posting a list of galaxies that are within the GW Event contour

Usage

/api/v0/event_galaxies

Notes

This endpoint is for posting a list of galaxies the lie within the GW contour. For each galaxy, it accepts position, score, rank, and name. You may also append a json list of parameters about the galaxy or your calculation.

JSON Parameters

  • api_token=api_token1
  • graceid=graceid1
  • timesent_stamp=event_timesent1
    • this is the timestamp for the alertype of the given event. I.E. whether the uploaded galaxy list refers to the Initial, Preliminary, Update, etc for the GW Event. This timestamp information can be found on the given alert page
  • groupname=groupname1
    • this can be the name of the group that did the calculation, or will default to the username associated with the api_token
  • reference=reference1
    • this can be a link to a paper/DOI that describes the methods that calculates the galaxy scores. Not mandatory
  • galaxies=galaxielist
    • json list of [name, position, score (decimal), rank (integer), and info (json list parameters)
  • request_doi=True/False - [default=False] to request a Digital Object Identifier for the list of galaxies
  • creators=creatorslist1 - 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=groupid - if you have created an authors list through the website, you can link either the name of the group or the id

POST Examples

Post a list of convolved galaxies

                        
    import requests

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

    json_data = {
        "api_token":"abcdefghijkl",
        "graceid":"graceid1",
        "timesent_stamp":"2019-05-22T12:33:59",
        "groupname":groupname1,
        "reference":"https://ui.adsabs.harvard.edu/abs/2020arXivNicePaper",
        "request_doi":True,
        "doi_group_id":groupID
        "galaxies":[
            {
                "position":"POINT(24.0 41.0)",
                "score":19.5,
                "rank":1,
                "name":"test galaxy",
                "info":{
                    "param1":"value1",
                    "param2":"value2",
                    "param3":"value3",
                    "param4":"value4"
                }
            },
        ]
    }

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

    print(r.text)

REST API METHOD: GET Instructions

Retrieving a list of posted galaxies that are within the GW Event contour

Usage

/api/v0/event_galaxies

Notes

This endpoint is for getting a list of galaxies the lie within the GW contour.

The parameters my be passed in via a json argument in the request or as URL querystring arguments (i.e. /api/v0/event_galaxies?param1=value1...)

Parameters

  • api_token=api_token1
  • graceid=graceid1
    • This is required
  • timesent_stamp=event_timesent1
    • Not required, but if sent in, it will filter the lists based on the alert type: Initial, Preliminary, Update.. etc
  • groupname=groupname1
  • score_gt=score1
    • (Greater than or equal to) If you want to filter by score >= score1
  • score_lt=score1
    • (Less than or equal to) If you want to filter by score <= score1

GET Examples

Get a list of convolved galaxies

                        
    import requests

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

    json_data = {
        "api_token":"abcdefghijkl",
        "graceid":"graceid1",
        "groupname":groupname1
        "score_lt":0.01
    }

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

    print(r.text)

REST API METHOD: GET MOC File

Returns a json object for the calculated MOC map for the given instrument and graceid

  • The Fermi/GBM moc file is calculated from taking the complement of the position of the earth at the GW Event Time of Signal.
  • The Fermi/LAT moc file is created from the estimated location of the instrument pointing via these data files at the GW Event Time of Signal
  • The Swift/BAT moc file is created upon ingestion of a BAT pointing submission

the MOC files are generated using MOCpy

Usage

/api/v0/grb_moc_file

Parameters

  • api_token=abcdefghijkl
  • graceid=gid1
  • instrument=inst1
    • Instruments are gbm, lat, and bat

GET Examples

GET BAT coverage from GW event S200316bj:

                        
        import requests
        import urllib.parse
        import json

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

        params = {
            "api_token":"abcdefghijkl",
            "graceid":"S200316bj",
            "instrument":"bat"
        }

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

        r = requests.get(url = url)
        moc_data = json.loads(r.text)