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

Newly released is our python API wrapper: gwtm_api.

It fully encompasses the API endpoints, while also providing event tools to further aid in GW follow-up


API Use Cases

  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'
  • depth_gt=depth_value
    • will query for pointings with a depth brighter than or equal to the value (e.g. depth_unit = *mag it will query for pointings with a depth <= value)
  • depth_lt=depth_value
    • will query for pointings with a depth dimmer than or equal to the value (e.g. depth_unit = *mag it will query for pointings with a depth >= value)
  • depth_unit
    • units for depth comparisions. Can be: ab_mag, vega_mag, flux_erg, or flux_jy
  • 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)

Event Candidates

REST API METHOD: GET Instructions

Retrieving a list of posted candidates that are associated with a GW event.

Usage

/api/v1/candidate

Notes

This endpoint is for getting a list of candidates that are associated with a GW event.

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

Parameters

  • api_token (str; verified account API Token)
  • graceid (str; graceid associated with GW event)
  • id (int; id for single candidate)
  • ids (list[int]; list of ids for multiple candidates)
  • userid (int; user id associated with api_token that posted candidates)
  • submitted_date_after (str(datetime); filters candidates created after or on a specified datetime)
  • submitted_date_before (str(datetime); filters candidates created before or on a specified datetime)
  • discovery_date_after (str(datetime); filters candidates discovered after or on a specified datetime)
  • discovery_date_after (str(datetime); filters candidates discovered after or on a specified datetime)
  • discovery_magnitude_gt (float; filters candidates with magnitude greater than (or equal) specified value)
  • discovery_magnitude_lt (float; filters candidates with magnitude lesser than (or equal) specified value)
  • associated_galaxy (str; filters candidates that are submitted with an associated galaxy name)
  • associated_galaxy_redshift_gt (float; filters candidates with associated_galaxy_redshift greater than (or equal) specified value)
  • associated_galaxy_redshift_lt (float; filters candidates with associated_galaxy_redshift lesser than (or equal) specified value)
  • associated_galaxy_distance_gt (float; filters candidates with associated_galaxy_distance greater than (or equal) specified value)
  • associated_galaxy_distance_lt (float; filters candidates with associated_galaxy_distance lesser than (or equal) specified value)

Python Example

    
import requests

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

#get all candidates associated with GW event GW170817
json_params = {
    "api_token":API_TOKEN,
    "graceid":"GW170817"
}

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

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

print(r.text)

Python Example

    
import requests

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

#get all candidates associated with candidate ids
json_params = {
    "api_token":API_TOKEN,
    "ids": [id1, id2, id3...]
}

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

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

print(r.text)

Python Example

    
import requests

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

#get all candidates associated with multiple filters
json_params = {
    "api_token":API_TOKEN,
    "graceid": "GW170817",
    "associated_galaxy_redshift_gt": 0.05,
    "associated_galaxy_redshift_lt": 0.15,
    "discovery_date_after": "2017-08-18T12:30:00"
}

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

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

print(r.text)

REST API METHOD: POST Instructions

Posting transient Candidates that are potentially affiliated with a GW event.

Usage

/api/v1/candidate

Notes

This endpoint is for posting a candidate (or list of candidates) that coincides with a GW event.

JSON Parameters

  • api_token=api_token1
  • graceid=graceid1
  • candidates=candidates_list
Valid candidate class parameters

*parameters required unless otherwise specified as (optional)

  • position: two acceptable formats
    • geometry type: POINT(RA DEC)
    • simply pass two json fields that are RA and DEC which must be decimal
  • candidate_name (str)
  • tns_name (str; optional)
  • tns_url (str; optional)
  • associated_galaxy (str; optional)
  • associated_galaxy_redshift (float; optional)
  • associated_galaxy_distance (float; optional)
  • discovery_date (datetime: %Y-%m-%dT%H:%M:%S format; e.g. 1991-12-23T19:15:11)
    • datetime, must be after associated GW event T0
  • discovery_magnitude: (float)
  • magnitude_unit
    • units for magnitude. Can be: ab_mag, vega_mag, flux_erg, or flux_jy
  • Bandpass Information: is required and can be passed in by stating the band, the range of wavelengths, energies, or frequencies the pointing covers. If your candidate observation is associated with a bandpass, we will calculate the wavelength range from a generic set of filters from SVO
    • Method 1: Bandpass List
      • magnitude_bandpass
        • 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
      • magnitude_central_wave (float)
      • magnitude_bandwidth (float)
    • 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: valid inputs are:Hz, kHz, MHz, GHz and THz

Python Example

    
import requests

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

json_data = {
    "api_token":"API_TOKEN",
    "graceid":"graceid1",
    "candidates":[
        {
            "ra": 24.0,
            "dec": 48.0,
            "candidate_name": "AT2021fxy"
            "tns_name": "AT2021fxy",
            "tns_url": "https://www.wis-tns.org/object/2021fxy",
            "discovery_date": "2021-03-17T17:23:37.000",
            "discovery_magnitude": 18.0,
            "magnitude_unit": "ab_mag",
            "magnitude_bandpass": "r"
        },
    ]
}

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

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

print(r.text)

REST API METHOD: PUT Instructions

Alter your candidate records

Usage

/api/v1/candidate

Notes

This endpoint is for altering your posted candidates. You can only alter candidates associated with your API_TOKEN. You can only alter one at a time

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

Parameters

  • api_token (str; your verified account api_token)
  • id (int; candidate id you want to alter)
  • payload (dict; json object with fields that follow the candidate POST parameter guideline)

Python Example

    
import requests

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

#update your candidate with tns information
json_params = {
    "api_token":API_TOKEN,
    "id": candidate_id,
    "payload": {
        "tns_name": "AT2024xxx",
        "tns_url": "https://www.wis-tns.org/object/2024xxx"
    }
}

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

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

print(r.text)

REST API METHOD: DELETE Instructions

Deleting a candidate associated with a GW event

Usage

/api/v1/candidate

Notes

This endpoint is for deleting your candidate or candidates.

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

Parameters

  • api_token (str; your verified account api_token)
  • id (int; id for single candidate)
  • ids (list[int]; list of ids for multiple candidates)

Python Example

    
import requests

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

json_params = {
    "api_token":API_TOKEN,
    "id":candidate_id
}

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

r = requests.delete(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)