Lasair and Sherlock API

The Lasair-Sherlock API allows developers to run queries and cone-searches, to see outputs from streaming queries, and to query the Sherlock sky-context system.

Ways to use the API

The Lasair API uses either HTTP GET or POST. Arguments can be passed in the query string, as JSON or form encoded. Responses are JSON. There is a throttling system in the backend: if you use the authprisation token shown below, it will only accept 10 requests in an hour.

The examples below show how to drive the API with either GET URL, POST curl or python with the 'lasair' package. The URL should be pasted into a web browser. The curl script pasted into a terminal window, and the python code copied into a file and executed as a python program.

Throttling of API Usage

The Lasair API counts numbers of calls on a per-user basis, and restricts the number that can be executed in any hour time period. There are also restrictions on the number of rows that can be returned by the 'query' method. The token shown below is just to show you how the API services work, it is not intended for real work. To use the API with less throttling, please get your own token from your Lasair account, as explained below "Get Your Token". If you would like to use the system for serious work, please Email Lasair-help, explain what you are doing, and you will be put into the "Power Users" category. The limits for these three categories of user are: Note: WE ASK YOU TO PLEASE NOT SHARE THESE TOKENS. If you share code that uses the Lasair API, please put the token in a separate, imported file or environment variable, that you do not share, and is not put in github.

Authorisation Token
Request authentication is via authentication tokens. For GET queries, the token can go in the parameter string, and for POST queries, the token goes in the headers. An example of a token is: 
4b762569bb349bd8d60f1bc7da3f39dbfaefff9a
This "starter" token can be used for experiments with the API. However, this key is throttled and restricted, and should only be used for discovery and play, not serious use.
Get Your Token
 We recommend that users request their own key by running the following script: 
curl --data "username=u&password=p" https://lasair-iris.roe.ac.uk/api/auth-token/
where u and p are replaced with username and password for your Lasair account, which you can obtain here. Each key can only do a certain number of requests before the server responds with status code 429 and will not do more until an hour has passed.

Methods

Click on the method name to jump to documentation in the reference below.

Reference

/api/cone/
Description

This method runs a cone search on all the objects in the Lasair database. The arguments are:

  • ra: (float) the right ascension in decimal degrees,
  • dec: (float) the declination in decimal degrees,
  • radius: (float) the angular radius of the cone in arcseconds, the maximum being 1000 arcseconds.
  • requestType: (string) the type of request, which can be:
    • nearest: returns only the nearest objects within the cone
    • all: returns all the objects within the cone
    • count: returns the number of objects within the cone

GET URL Example
https://lasair-iris.roe.ac.uk/api/cone/?&ra=194.494&dec=48.851&radius=240.0&requestType=all&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "ra=194.494&dec=48.851&radius=240.0&requestType=all" \
https://lasair-iris.roe.ac.uk/api/cone/
Python Example

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
c = L.cone(ra, dec, radius=240.0, requestType='all')
print(c)

and the return has object identifiers, and their separations in arcseconds, something like: 

[
    {
        "object": "ZTF17aaajmtw",
        "separation": 2.393511865261539
    }
]

/api/query/
Description

This method runs a query on the Lasair database. There is an interactive query builder, and a schema description. The arguments are:

  • selected: (string) the list of attributes to be returned,
  • tables: (string) the list of tables to be joined,
  • conditions: (string) the "WHERE" criteria to restrict what is returned
  • limit: (int) (not required) the maximum number of records to return (default is 1000)
  • offset: (int) (not required) offset of record number (default is 0)

GET URL Example
https://lasair-iris.roe.ac.uk/api/query/?selected=objectId%2Cgmag&tables=objects&conditions=gmag%3C12.0&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "selected=objectId,gmag&tables=objects&conditions=gmag<12.0&limit=3" \
https://lasair-iris.roe.ac.uk/api/query/
Python Example

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
selected    = 'objectId, gmag'
tables      = 'objects'
conditions  = 'gmag < 12.0'
c = L.query(selected, tables, conditions, limit=10)
print(c)

and the return is something like: 

status= 200
[
  {
    "objectId": "ZTF17aaagaie",
    "gmag": 11.4319
  },
  {
    "objectId": "ZTF18aaadvxy",
    "gmag": 11.8582
  },
.... ]

/api/streams/<topic>/ and /api/streams/
Description

This method returns a record of the output from a Lasair streaming query. It represents an alternative to using a Kafka client to fetch from the Kafka server.

If the topic URL is provided (with optional limit), the contents of the stream are returned. Alternatively, if the topic is not provided, a regex argument may be provided, and a list of matching topic names will be returned. A list of all topics can be obtained with the regex .* or by omitting the regex.

The arguments are:
  • limit: (int) (not required) the maximum number of records to return (default 1000)
  • regex: (str) (not required) an expression used to select from the set of topics (regular expression)
GET URL Example with Regex
https://lasair-iris.roe.ac.uk/api/streams/?regex=.%2ASN.%2A&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example with Regex

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "regex=.*SN.*" \
https://lasair-iris.roe.ac.uk/api/streams/

and the return is a list of topic names, and a URL to get more information: 

status= 200
[
  {
    "topic": "2SN-likecandidates",
    "more_info": "https://lasair-iris.roe.ac.uk/query/2/"
  },
... ]
GET URL Example with Topic
https://lasair-iris.roe.ac.uk/api/streams/2SN-likecandidates/?limit=1&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example with Topic

The authorization token goes in the header of the request, and the data in the data section. For more information about this stream, see here. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "2SN-likecandidates&limit=1" \
https://lasair-iris.roe.ac.uk/api/streams/

and the return is something like: 

status= 200
[
  {
    "objectId": "ZTF19abrokxg",
    "ramean": 35.82811567,
    "decmean": -27.79242059,
    "mjdmin": 59134.39827550016,
    "mjdmax": 59164.37175930012,
    "magrmin": 18.33,
    "rmag": 19.4124,
    "classification": "NT",
    "score": "Not Near PS1 star",
    "UTC": "2020-11-11 09:08:49"
  }
]
Python Example with Topic

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
print(L.streams_topics())
c = L.streams('2SN-likecandidates', limit=10)

and the return is as above with the curl example

/api/objects/
Description

This method returns a machine-readable version of the information on a list of objects, which replicates the information on the object page of the web server. The arguments are:

  • objectIds: a list of objectIds for which data is wanted

GET URL Example
https://lasair-iris.roe.ac.uk/api/objects/?objectIds=ZTF18abdphvf,ZTF21aapzzgf&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "objectIds=ZTF18abdphvf,ZTF21aapzzgf" \
https://lasair-iris.roe.ac.uk/api/objects/
Python Example

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
c = L.objects(objectIds)
print(c)

and the return is something like: 

status= 200
[
{"objectId":"ZTF18abdphvf",
"objectData":{
    "ncand":8,
    "ramean":293.54591006249996,
    "decmean":49.429229975,
    "glonmean":81.77021010499132,
    "glatmean":13.829346704017533,
.... }
]

/api/lightcurves/
Description

This method returns simple lightcurves for a number of objects. NOTE: these are difference magnitudes from a reference source, not apparent magnitudes. See this python code to convert the quantities below to apparent magnitude. Each lightcurve is a sequence of detections, or candidates, each of which has the quantities:

  • candid: the candidate ID for the detection
  • fid: The filter ID for the detection (1 = g and 2 = r)
  • magpsf: The difference magnitude
  • sigmapsf: the error in the difference magnitude.
  • isdiffpos:set to 't' if positive difference magnitude, 'f' for negative
  • magnr: Magnitude of the reference source
  • sigmagnr: the error in the reference magnitude
  • magzpsci: Zero-point magnitude of the science image
  • mjd: Modified Julain Day for the detection
The arguments are:
  • objectIds: (string) comma-separated string of objectIds to be fetched
  • There is a upper limit on the number of lightcurves that can be fetched, currently 50. If you need to do serious data mining on Lasair light curves, please write to contact the Lasair team.

GET URL Example
https://lasair-iris.roe.ac.uk/api/lightcurves/?objectIds=ZTF20acgrvqo%2CZTF19acylwtd%2CZTF18acmziob&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "objectIds=ZTF20acgrvqo,ZTF19acylwtd,ZTF18acmziob" \
https://lasair-iris.roe.ac.uk/api/lightcurves/
Python Example

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
c = L.lightcurves(['ZTF20acgrvqo','ZTF19acylwtd','ZTF18acmziob'])
print(c)

and the return is something like: 

{
  "objectId": "ZTF20acpwljl",
  "candidates":[
    {
      "candid": 1411435461415015019,
      "fid": 2,
      "magpsf": 19.739900588989258,
      "sigmapsf": 0.16019299626350403,
      "isdiffpos": "t",
      "mjd": 59165.43546300009
    },
    {
      "candid": 1411436860315015015,
      "fid": 2,
      "magpsf": 19.987899780273438,
      "sigmapsf": 0.18143899738788605,
      "isdiffpos": "t",
      "mjd": 59165.43686340004
    },
    ]
... snip ...

/api/sherlock/objects/
Description

This method returns Sherlock information for a collection of named objects, either the "lite" record that is also in the Lasair database, or the full record including many possible crossmatches. The arguments are:

  • objectIds: a comma-separated list of objectIds, maximum number is 10
  • lite: Set to 'true' to get the lite information only
GET URL Example with objects
https://lasair-iris.roe.ac.uk/api/sherlock/objects/?objectIds=ZTF20acpwljl%2CZTF20acqqbkl%2CZTF20acplggt&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&lite=true&format=json
Curl Example with list of objects

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "objectIds=ZTF20acpwljl,ZTF20acqqbkl,ZTF20acplggt&lite=True" \
https://lasair-iris.roe.ac.uk/api/sherlock/objects/
Python Example with list of objects

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
c = L.sherlock_objects(['ZTF20acgrvqo','ZTF19acylwtd','ZTF18acmziob'])
print(c)

and the return is something like: 

{
    "ZTF20acpwljl": {
        "classifications": {
            "ZTF20acpwljl": [
                "SN",
                "The transient is possibly associated with <em><a href=\"http://skyserver.sdss.org/dr12/en/tools/explore/Summary.aspx?id=1237673709862061782\">SDSS J081931-060114.9</a></em>; a J=17.01 mag galaxy found in the SDSS/2MASS/PS1 catalogues. It's located 1.09\" N, 1.11\" W from the galaxy centre."
            ]
        },
        "crossmatches": [
            {
                "catalogue_object_id": "1237673709862061782",
                "J": 17.007,
                "JErr": 0.215,
                "H": 15.974,
                "HErr": 0.179,
                "K": 15.389,
...snip...

/api/sherlock/position/
Description

This method returns Sherlock information for an arbitrary position in the sky, either the "lite" record that is also in the Lasair database, or the full record including many possible crossmatches. It is meant as an illustration of what Sherlock can do. If you would like to use Sherlock for high volume work, please Email Lasair-help. The arguments are:

  • ra: Right ascension of a point in the sky in degrees
  • dec: Declination of a point in the sky in degrees
  • lite: Set to 'true' to get the lite information only
GET URL Example
https://lasair-iris.roe.ac.uk/api/sherlock/position/?ra=16.851866&dec=34.53307&token=4b762569bb349bd8d60f1bc7da3f39dbfaefff9a&format=json
Curl Example

The authorization token goes in the header of the request, and the data in the data section. 

curl --header "Authorization: Token 4b762569bb349bd8d60f1bc7da3f39dbfaefff9a" \
--data "ra=16.851866&dec=34.53307" \
https://lasair-iris.roe.ac.uk/api/sherlock/position/
Python Example

This code requires the lasair library. 

import lasair
token = '4b762569bb349bd8d60f1bc7da3f39dbfaefff9a'
L = lasair.lasair_client(token)
c = L.sherlock_position(['ZTF20acgrvqo','ZTF19acylwtd','ZTF18acmziob'])
print(c)

and the return is something like: 

status= 200
{
  "classifications": {
    "query": [
      "VS",
      "The transient is synonymous with