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.

We have two versions of the API, as a consequence of my adolescence in API programming in 2019... We recommend using /api/v1 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 one of the test events graceids listed 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:

Pointings

Instructions

Usage

/api/v0/pointings

/api/v1/pointings

Parameters

  • api_token=abcdefghijkl
  • graceid=gid1
  • instrument=inst1
  • instruments=[inst1, inst2, inst3...]
    • Can be a list of instrument ids or a list of instrument names
  • 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
  • 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

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "pointings"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "band":"XRT",
    "status":"completed",
    "graceid":"GW190425"
}

url = "{}/{}".format(BASE, TARGET)

r = requests.get(url=url, json=json_params)

print(r.text)
    

Python Example

An example of querying for completed pointings based on their central_wave and bandwidth parameters

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "pointings"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "central_wave":5000,
    "bandwidth":500,
    "status":"completed",
    "graceid":"GW190425"
}

url = "{}/{}".format(BASE, TARGET)

r = requests.get(url=url, json=json_params)

print(r.text)
    

Python Example

An example of querying for completed pointings based on their wavelength_regime parameters. It filters all pointings based on their calculated central_wave and bandwidth, and tests whether or not they fall within the queried regime. This same concept can be applied for the frequency_regime and energy_regime parameters as well

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "pointings"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "wavelength_regime":[3500,7500],
    "wavelength_unit":'angstrom',
    "status":"completed",
    "graceid":"GW190425"
}

url = "{}/{}".format(BASE, TARGET)

r = requests.get(url=url, json=json_params)

print(r.text)
    

Instruments

REST API METHOD: GET Instructions

Usage

/api/v0/instruments

/api/v1/instruments

Parameters

  • api_token=abcdefghijkl
  • id=id1
  • ids=[id1, id2, id3...]
  • name=name1
  • names=[name1, name2, name3...]
  • type=type1
    • Instrument types are spectroscopic, photometric

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "instruments"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "type":"photometric"
}

url = "{}/{}".format(BASE, target)

r = requests.get(url=url, json=json_params)

print(r.text)
    

REST API METHOD: GET Instructions

Usage

/api/v0/footprints

/api/v1/footprints

NOTES

  • Returns a list of the footprints associated to an instrument. These are the polygons with dimensions in degrees centered around (0,0).

Parameters

  • api_token=abcdefghijkl
  • id=id1
  • name=name1

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "footprints"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "name":"ZTF"
}

url = "{}/{}".format(BASE, target)

r = requests.get(url=url, json=json_params)

print(r.text)
    

Convolved Galaxies

REST API METHOD: GET Instructions

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

Usage

/api/v0/event_galaxies

/api/v1/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

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "event_galaxies"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "graceid":"graceid1",
    "groupname":groupname1
    "score_lt":0.01
}

url = "{}/{}".format(BASE, target)

r = requests.get(url=url, json=json_params)

print(r.text)
    

REST API METHOD: POST Instructions

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

Usage

/api/v0/event_galaxies

/api/v1/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

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "event_galaxies"
API_TOKEN = "-your-verified-account-api-token-"

json_data = {
    "api_token":"API_TOKEN",
    "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"
            }
        },
    ]
}

url = "{}/{}".format(BASE, target)

r = requests.post(url=url, json=json_params)

print(r.text)
    

REST API METHOD: POST Instructions

Deleting a convolved galaxies list

Usage

/api/v0/event_galaxies

/api/v1/event_galaxies

Notes

This endpoint is for deleting your list of convolved galaxies.

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

Parameters

  • api_token=api_token1
  • listid=listid1
    • This is required

Python Example

    
import requests

BASE = "https://treasuremap.space/api/v1"
TARGET = "remove_event_galaxies"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "listid":"listid1"
}

url = "{}/{}".format(BASE, target)

r = requests.post(url=url, json=json_params)

print(r.text)
    

GRB Multi-Order Coverage (MOC) Maps

REST API METHOD: GET MOC File

Usage

/api/v0/grb_moc_file

/api/v1/grb_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

Parameters

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

Python Example

    
import requests
import json

BASE = "https://treasuremap.space/api/v1"
TARGET = "grb_moc_file"
API_TOKEN = "-your-verified-account-api-token-"

json_params = {
    "api_token":API_TOKEN,
    "graceid":"S200316bj",
    "instrument":"bat"
}

url = "{}/{}".format(BASE, target)

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