NAV
Python Javascript

Introduction

Example usage and code samples will appear on this column. Choose which language you’d like to view from the menu at the top.

Python examples assume requests is installed. Javascript assumes the use of jQuery

Welcome to the LCO Developer documentation!

Here you will find API documentation, sample code, tutorials and other resources to aid your development with LCO services.

A note about code formatting

An ellipses ... acts as a placeholder for additional data that would otherwise take up too much space. These will not appear in actual API requests or responses. For example, an endpoint that returns the data:

{ "target": { "type": "SIDEREAL", "name": "m42", "ra": 83.8220792, "dec": -5.3911111, "proper_motion_ra": 1.67, "proper_motion_dec": -0.3, "parallax": 0.0, "coordinate_system": "ICRS", "equinox": "J2000", "epoch": 2000.0, }, }

May be shortened in the documentation to:

{ "target": { ... "type": "SIDEREAL", "name": "m42", ... } }

Information relevant to the documentation being described will always be shown.

All dates are in UTC and all date fields are in the ISO 8601 format.

Deprecation Policy

LCO wants to make sure we provide a consistent, performant interface to our network services.

When a public API must undergo a breaking change, we will make our best effort to notify all consumers.

When applicable, APIs will be versioned to provide ample time for clients to adapt. Old versions will stay supported for at least 3 months and can be accessed using a different URL. Example:

https://observe.lco.global/api/v2/

LCO will provide documentation at developers.lco.global in order to make API transitions as easy as possible.

Observations

Api root: https://observe.lco.global/api

Overview

The observations API provides endpoints for submitting and querying observation requests.

A UserRequest is a named group of individual observation Requests.

A Request is a single unit of observation.

For example: You may submit a UserRequest with a group_id of “Color m51” that is comprised of 3 Requests, each with a different filter.

Once a UserRequest is submitted, it cannot be changed (however, it can be canceled). You may follow the status of the UserRequest using the query endpoints outlined below.

If you’d like some practical examples of how to use this API, the code samples section provides links to example scripts and an ipython notebook.

Rate Limits

The observations API is rate limited so that it remains available to all users in the event a single user makes too many requests in too rapid a succession, causing denial of service to other clients.

All users are limited to 5,000 HTTP calls in a 24 hour period. The exception is the validate endpoint which allows 10,000 in a 24 hour period.

Data Format Definition

UserRequest

The top level entity in the LCO request language is the UserRequest. A UserRequest is a container for Requests (described in the next section) whose main purpose is to bind all of its child Requests together.

A sample UserRequest returned via API:

{
    "id": 12345,
    "submitter": "austin_riba",
    "requests": [...],
    "group_id": "Test observation",
    "observation_type": "NORMAL",
    "operator": "SINGLE",
    "ipp_value": 1.05,
    "created": "2017-03-21T18:53:06.751369Z",
    "state": "PENDING",
    "modified": "2017-03-21T18:53:06.751417Z",
    "proposal": "LCOEngineering"
}
Field Read Only Required Options Description
id true false The id of this UserRequest.
requests false true The list of Requests to be observed for this UserRequest.
submitter true false The user that submitted the UserRequest.
proposal false true The Proposal under which this observation will be made.
group_id false true A string placed in the FITS header as the GROUPID keyword value for all FITS frames originating from this UserRequest.
observation_type false true NORMAL, TARGET_OF_OPPORTUNITY The type of observation. Requests submitted with TARGET_OF_OPPORTUNITY (ToO) bypass normal scheduling and are executed immediately. This mode is only available if a proposal was granted ToO time. More information on this mode is located here.
operator false true SINGLE, MANY Use SINGLE if you have only one Request, and MANY if you have more than one.
ipp_value false true A multiplier (from 0.5 to 2.0, generally set to 1.05) to your Proposal’s base priority value for this UserRequest and all of its child Requests. A value > 1.0 will raise your priority and debit your Proposal’s ipp_time_available upon submission. If a Request does not complete, the time debited for that Request is returned. A value < 1.0 will lower your priority and credit your Proposal’s ipp_time_available up to your ipp_limit on the successful completion of a Request. For more information on IPP, you can go here.
state true false PENDING, SCHEDULED, WINDOW_EXPIRED, COMPLETED, CANCELED The current state of this UserRequest.
created true false The time at which this UserRequest was created.
modified true false The time at which this UserRequest was last changed.

Request

A sample Request returned via API:

{
    "id": 4,
    "location": {},
    "constraints": {},
    "target": {},
    "molecules": [],
    "windows": [],
    "observation_note": "",
    "state": "PENDING",
    "modified": "2017-03-21T18:36:19.456710Z",
    "created": "2017-03-21T18:36:19.456761Z",
}

Requests are the language constructs used to describe an observation of a single target. A request has a Target, Location, list of Molecules, list of Windows describing when the observation can be made, and Constraints that limit the conditions under which the observation should be made.

Field Read Only Required Options Description
id true false The id of this Request.
location false true The Location from which this Request should be observed.
constraints false true The observation Constraints placed on this Request.
target false true The Target to observe.
molecules false true A list of Molecules.
windows false true A list of Windows in which this Request should be considered for observation.
observation_note false false Text describing this Request.
state true false PENDING, SCHEDULED, WINDOW_EXPIRED, COMPLETED, CANCELED The current state of this Request.
modified true false The last time this Request was modified in any way.
created true false The time when this Request was created.

A sample Location returned via API:

{
    "telescope_class": "2m0"
}

Location

A Location specifies which telescope class is used for this observation.

Field Read Only Required Options Description
telescope_class false true 1m0, 2m0, 0m4, 0m8 The telescope class which will be used for this observation. The class describes the aperture size, i.e. 1m0 is a 1m telescope, and 0m4 is a 0.4m telescope.

Constraints

A sample Constraints returned via API:

{
    "max_airmass": 2.0,
    "min_lunar_distance": 30.0,
}

Constraints define the conditions that must be met in order for a Request to be considered for scheduling.

Field Read Only Required Description
max_airmass false false Maximum acceptable airmass. The airmass=1 at zenith and increases with zenith distance. Assumes a plane-parallel atmosphere. Defaults to 1.6. You can read about the considerations of setting the airmass limit here.
min_lunar_distance false false Minimum acceptable angular separation between the target and the moon, in decimal degrees. Defaults to 30.

Target

Targets describe what will be observed during an observation and can be sidereal or non-sidereal. Sidereal targets are specified using right ascension and declination. Non-sidereal targets are specified using orbital elements. The following fields are common to both sidereal and non-sidereal targets.

Field Read Only Required Options Description
type false true SIDEREAL, NON_SIDEREAL Type of Target.
name false true The name of this Target.
rot_mode false false SKY, VFLOAT (Spectrograph only) How the slit is positioned on the sky. If set to VFLOAT, atmospheric dispersion is along the slit.
rot_angle false false (Spectrograph only) If rot_mode is set to SKY, this is the position angle of the slit in degrees east of north.

A sample sideral Target returned via API:

{
    "type": "SIDEREAL",
    "name": "m42",
    "ra": 83.8220792,
    "dec": -5.3911111,
    "proper_motion_ra": 1.67,
    "proper_motion_dec": -0.3,
    "parallax": 0.0,
    "coordinate_system": "ICRS",
    "equinox": "J2000",
    "epoch": 2000.0,
    "rot_mode": "VFLOAT",
    "rot_angle": 0.0
}

Sidereal Targets

Sidereal targets are used to observe targets that appear to move at or near the sidereal rate, and have the following additional fields.

Field Read Only Required Options Description
ra false true Right ascension in decimal degrees.
dec false true Declination in decimal degrees.
epoch false false In modified Julian days (MJD). Defaults to 2000.
proper_motion_ra true false Right ascension proper motion ±33 mas/year. Defaults to 0, max 20000.
proper_motion_dec true false Declination proper motion ±33 mas/year. Defaults to 0, max 20000.
parallax false false ±0.45 mas, max 2000. Defaults to 0.
coordinate_system false false Defaults to ICRS.
equinox false false Defaults to J2000.

Non Sidereal Targets

Non-sidereal targets are used to observe objects that can be described using various orbital element schemes. Two schemes are available: MPC_MINOR_PLANET and MPC_COMET, each of whose associated fields are described as follows.

A sample non sidereal target returned via API:

{
    "name": "Doomsday Asteroid",
    "type": "NON_SIDEREAL",
    "epochofel": 50000,
    "scheme": "MPC_MINOR_PLANET",
    "orbinc": 0,
    "longascnode": 0,
    "argofperih": 0,
    "meandist": 0,
    "eccentricity": 0,
    "meananom": 0
}

MPC_MINOR_PLANET

Field Read Only Required Options Description
scheme false true MPC_MINOR_PLANET The target scheme to use, in this case MPC_MINOR_PLANET.
epochofel false true The epoch of the orbital elements in MJD.
orbinc false true Orbital inclination (angle in degrees).
longascnode false true Longitude of ascending node (angle in degrees).
argofperih false true Argument of perihelion (angle in degrees).
eccentricity false true Eccentricity ranges from 0 to 0.99.
meananom false true Mean anomaly (angle in degrees).
meandist false true Mean distance (au).

MPC_COMET

Field Read Only Required Options Description
scheme false true MPC_COMET The target scheme to use, in this case MPC_COMET.
epochofel false true The epoch of the orbital elements in MJD.
orbinc false true Orbital inclination (angle in degrees).
longascnode false true Longitude of ascending node (angle in degrees).
argofperih false true Argument of perihelion (angle in degrees).
eccentricity false true Eccentricity ranges from 0 to 0.99.
perihdist false true Perihelion distance (au).
epochofperih false true Epoch of perihelion in MJD.

Molecule

A sample molecule returned via API:

{
    "type": "EXPOSE",
    "instrument_name": "2M0-SCICAM-SPECTRAL",
    "filter": "v",
    "exposure_time": 30.0,
    "exposure_count": 1,
    "bin_x": 2,
    "bin_y": 2,
    "defocus": 0.0,
    "ag_mode": "OPTIONAL",
    "acquire_mode": "OFF",
    "acquire_radius_arcsec": 0.0,
}

A Molecule represents the configuration of the instrument. To read about instruments and possible configurations, you can go here. For more information of de-focus and guiding, you can look though the “Getting Started” guide linked here.

Field Read Only Required Options Description
type false true EXPOSE, SPECTRUM, LAMP_FLAT, ARC, STANDARD The type of exposure.
instrument_name false true 1M0-SCICAM-SINISTRO, 2M0-SCICAM-SPECTRAL, 0M4-SCICAM-SBIG, 2M0-FLOYDS-SCICAM The type of instrument.
filter false true The filter to use.
spectra_slit false true slit_6.0as, slit_1.6as, slit_2.0as, slit_1.2as The slit to use (spectrograph only)
exposure_time false true Exposure time in seconds. A tool to aid in deciding on an exposure time is located here.
exposure_count false true The number of exposures to take. This field must be set to a value greater than 0, but optionally you can add a boolean fill_window field to the Molecule upon submission with a value of true. If this is set, the exposure_count is set to the number of exposures (including overheads) that will fit in the observing window.
bin_x false false Binning in the x dimension, defaults to the instrument default.
bin_y false false Binning in the y dimension, defaults to the instrument default.
defocus false false Observations may be de-focused by offsetting the secondary mirror from its focused position to prevent the CCD from saturating on bright targets. Limits of the offset are ±3mm.
ag_mode false false OPTIONAL, ON, OFF Guiding mode. Guiding keeps the field stable during long exposures. If OPTIONAL is selected, guiding is attempted but the observations are carried out even if guiding fails. If ON is selected, observations are aborted if guiding fails.
acquire_mode false false WCS, BRIGHTEST (Spectrograph only) The method for positioning the slit. If BRIGHTEST is selected, the slit is placed on the brightest object near the target coordinates.
acquire_radius_arcsec false false (Spectrograph only) The radius in arcseconds in which to search for the brightest object. Used if acquire_mode is BRIGHTEST.

Window

A sample window returned via API:

{
    "start": "2017-3-22 14:26:08",
    "end": "2017-3-22 14:26:08"
}

A Window defines the time-span in which the Request must be observed. The visibility calculator might be helpful in deciding a window for your target.

Field Read Only Required Description
start false true The time when the observing window starts.
end false true The time when the observing window ends.

Migration from V1

The release of the new observing portal and API (codename “Valhalla”) brings with it some backwards incompatible API changes. Those changes are listed here.

Authorization token is required

The API will no longer accept username/password as authentication credentials. All requests (besides the api-token-auth endpoint) must use the Authorization header. Read more about authentication here.

This also means the proposal data structure that was present in the V1 API is now deprecated.

POST requests must use JSON payloads

The new API expects form data to be sent as JSON with a content type of application/json. Previously in V1 the API accepted a form encoded JSON string. If you are using the Python requests library this means using json=<data> instead of data=<data> when sending your POST dictionary.

Data format definition changes

The main difference between the V1 and current API is the removal of the Compound Requests data structure. It has been possible to submit observations without Compound Requests for a long time, so if you don’t know what a Compound Request is, you can ignore this completely.

New Required fields

The following fields are now required:

In a UserRequest:

  1. group_id
  2. ipp_value
  3. observation_type

In a Target:

  1. type

You can read more about these fields in the Data format definition.

Authentication

requests.post(
    'https://observe.lco.global/api/api-token-auth/',
    data = {
        'username': 'bilbo@lco.global',
        'password': 'myprecious'
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/api-token-auth/',
    type: 'post',
    data: {username: 'bilbo', password: 'myprecious'},
    dataType: 'json',
    success: function(data){
        console.log(data.token)
    }
});

Returns the response:

{ "token": "3d46d6b98edef947402e032e73eca7b54661c666" }

The returned token must be set in the Authorization header for all API requests.

requests.get('https://observe.lco.global/api', headers={'Authorization': 'Token <token>'})

$.ajax({
    url: 'https://observe.lco.global/api',
    headers: {'Authorization': 'Token <token>'}
})

All authenticated endpoints require the use of an API token. Once a token is obtained, it must be sent in the Authorization header for each API request:

Authorization: Token <token>

This header must be set for each API request. See the opposite panel for examples on how this may be accomplished.

You may obtain your API token on your profile page.

You may also obtain a token using the api-token-auth endpoint:

Http Request

POST https://observe.lco.global/api/api-token-auth/

Query Parameters

Parameter Required Default Description
username true Account username.
password true Account password.

Submit UserRequest

requests.post(
    'https://observe.lco.global/api/userrequests/',
     json={
        'group_id': 'Submit me',
        'proposal': 'Test Proposal',
        'ipp_value': 1.05,
        'operator': 'SINGLE',
        'observation_type': 'NORMAL',
        'requests': [...]
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/userrequests/',
    type: 'post',
    data: {
        'group_id': 'Submit me',
        'proposal': 'Test Proposal',
        'ipp_value': 1.05,
        'operator': 'SINGLE',
        'observation_type': 'NORMAL',
        'requests': [...]
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the response:

{
    "id": 12345,
    "group_id": "Submit me",
    "proposal": "Test Proposal",
    "ipp_value": 1.05,
    "operator": "SINGLE",
    "observation_type": "NORMAL",
    "state": "PENDING",
    "requests": [...]
}

Authentication Required

Submit a UserRequest to be observed.

Http Request

POST https://observe.lco.global/api/userrequests/

Query Parameters

Parameter Required Default Description
* true A well formed UserRequest in JSON format.

Get All UserRequests

Authentication Required

Returns a list of UserRequests submitted under proposals of which you are a member.

requests.get('https://observe.lco.global/api/userrequests/?state=PENDING&user=austin_riba').json()

$.getJSON('https://observe.lco.global/api/userrequests/?state=PENDING&user=austin_riba')

Returns the response:

{
    "count": 18,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 4,
            "requests": [...],
            "submitter": "austin_riba",
            "group_id": "testhis",
            "observation_type": "NORMAL",
            "operator": "SINGLE",
            "ipp_value": 1.05,
            "created": "2017-03-21T18:36:19.454879Z",
            "state": "PENDING",
            "modified": "2017-03-21T18:36:19.454930Z",
            "proposal": "LCOEngineering"
        }
    ]
}

Http Request

GET https://observe.lco.global/api/userrequests/

Query Parameters

Parameter Required Default Options Description
created_after false Result includes UserRequests created after the given date.
created_before false Result includes UserRequests created before the given date.
state false PENDING, SCHEDULED, CANCELED, COMPLETED, WINDOW_EXPIRED Result includes UserRequests matching the given state.
title false Result includes UserRequests with a group_id that contains or matches the given value.
user false Result includes UserRequests submitted by users whose usernames contain the given value.
proposal false Result includes UserRequests submitted under the specified proposal.
observation_type false NORMAL, TARGET_OF_OPPORTUNITY Results include UserRequests with the specified observation type.
ipp_value false Results include UserRequests with the specified IPP value.
ordering false -id Order results by a specific field e.g. modified. Prefix with - for descending order.

Get Single UserRequest

Authentication Required

Returns a single instance of a UserRequest.

requests.get('https://observe.lco.global/api/userrequests/3456/').json()

$.getJSON('https://observe.lco.global/api/userrequests/3456/')

Returns the response:

{
    "id": 3456,
    "requests": [...],
    "submitter": "austin_riba",
    "group_id": "testhis",
    "observation_type": "NORMAL",
    "operator": "SINGLE",
    "ipp_value": 1.05,
    "created": "2017-03-21T18:36:19.454879Z",
    "state": "PENDING",
    "modified": "2017-03-21T18:36:19.454930Z",
    "proposal": "LCOEngineering"
}

Http Request

GET https://observe.lco.global/api/userrequests/<id>/

Query Parameters

Parameter Required Default Description
id true The id of the UserRequest.

Cancel UserRequest

Authentication Required

UserRequests can not be deleted, however they can be canceled. Once canceled, a UserRequest is no longer considered for scheduling.

requests.post('https://observe.lco.global/api/userrequests/3456/cancel/').json()

$.ajax({
    url: 'https://observe.lco.global/api/userrequests/3456/cancel/',
    type: 'post',
    success: function(data){
        console.log(data)
    }
});

Returns the response:

{
    "id": 3456
    ...
    "state": "CANCELED"
}

Http Request

POST https://observe.lco.global/api/userrequests/<id>/cancel/

Query Parameters

Parameter Required Default Description
id true The id of the UserRequest.

Validate a UserRequest

requests.post(
    'https://observe.lco.global/api/userrequests/validate/',
    json={
        'group_id': 'Validate me',
        'proposal': 'Test Proposal',
        'requests': [...]
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/userrequests/validate/',
    type: 'post',
    data: {
        "group_id": "Validate me",
        "proposal": "Test Proposal",
        "requests": [...]
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the response:

{
    "request_durations": {},
    "errors": {
        "requests":{ ... }
}

Authentication Required

This endpoint is used to check if a UserRequest is valid before submission. The response contains the duration of the each Request which is debited from the proposal’s allocated time upon completion.

Http Request

POST https://observe.lco.global/api/userrequests/validate/

Query Parameters

Parameter Required Default Description
* true A well formed UserRequest in JSON format.

Get Max Allowable IPP

requests.post(
    'https://observe.lco.global/api/userrequests/max_allowable_ipp/',
    json={
        "group_id": "Check Ipp",
        "proposal": "Test Proposal",
        "requests": [...]
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/userrequests/max_allowable_ipp/',
    type: 'post',
    data: {
        "group_id": "Check Ipp",
        "proposal": "Test Proposal",
        "requests": [...]
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the result:

{
    "2016B": {
        "1m0": {
            "ipp_time_available": 1.0,
            "ipp_limit": 10.0,
            "request_duration": 1.54,
            "max_allowable_ipp_value": 1.649,
            "min_allowable_ipp_value": 0.5
        }
    }
}

Authentication Required

Returns miscellaneous information pertaining to IPP per semester and telescope class.

HTTP Request

POST https://observe.lco.global/api/userrequests/max_allowable_ipp/

Query Parameters

Parameter Required Default Description
* true A well formed UserRequest in JSON format.

Generate Cadence

requests.post(
    'https://observe.lco.global/api/userrequests/cadence/',
    json={
        'group_id': 'generate cadence',
        'proposal': 'Test Proposal',
        'requests': [{
            'cadence': {
                'start': '2016-09-01T21:12:18Z',
                'end': '2016-09-03T22:12:19Z',
                'period': 24.0,
                'jitter': 12.0
            },
            ...
        }]
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/userrequests/cadence/',
    type: 'post',
    data: {
        "group_id": "generate cadence",
        "proposal": "Test Proposal",
        "requests": [{
            "cadence": {
                "start": "2016-09-01T21:12:18Z",
                "end": "2016-09-03T22:12:19Z",
                "period": 24.0,
                "jitter": 12.0
            },
            ...
        }]
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the response:

{
    "id": 3456
    ...
    "requests":[{
        "windows":[{
            "start": "2016-09-01T21:12:18Z",
            "end": "2016-09-02T03:12:18Z"
        }],
        ...
        },{
        "windows":[{
            "start": "2016-09-02T15:12:18Z",
            "end": "2016-09-03T03:12:18Z"
        }],
        ...
    }]
}

Authentication Required

Given a well formed UserRequest containing a single Request that has a cadence key, this endpoint returns a new UserRequest with multiple Requests generated by the cadence function.

HTTP Request

POST https://observe.lco.global/api/userrequests/cadence/

Query Parameters

Parameter Required Default Description
* true A well formed UserRequest in JSON format containing a single Request with a cadence key.
start true The UTC date that marks the beginning of the window in which to generate the cadenced Requests.
end true The UTC date that marks the end of the window in which to generate the cadenced Requests.
period true The fractional hours between observations. A 24 hour window with a period of 6 hours should have 3-4 Requests created within it (if they are all visible).
jitter true The fractional hours +/- of each Request window. A 24 hour window with a period of 6 hours and a jitter of 3 hours will create Requests with Windows centered every 6 hours, with their start and end times +/- 1.5 hours from those centers.

Airmass

requests.get('https://observe.lco.global/api/requests/12345/airmass/').json()

$.getJSON('https://observe.lco.global/api/requests/12345/airmass/')

Returns the response:

{
    "airmass_data": {
        "cpt": {
            "times": [
                "2017-03-10T00:00",
                "2017-03-10T00:10",
                "2017-03-10T00:20",
            ],
            "airmasses": [
                1.1742551260332688,
                1.1956410351734084,
                1.2190628569952935,
            ]
        },
        "lsc": {
            "times": [
                "2017-03-10T00:00",
                "2017-03-10T00:10",
                "2017-03-10T00:20",
            ],
            "airmasses": [
                1.4136946116338753,
                1.374117740986236,
                1.3379014027310017,
            ]
        }
    },
    "airmass_limit": 2.0
}

Authentication Required

For a specific Request, return the airmasses of the Target from the sites for which it is visible in 10 minute intervals. The max_airmass in the Request’s Constraints is used to determine visibility from a site.

HTTP Request

GET https://observe.lco.global/api/requests/<id>/airmass/

Query Parameters

Parameter Required Default Description
id true The id of the Request.

Code Samples

Observation API Examples

This is a collection of scripts that demonstrate various functions of the API.

View on Github

Observation API Example iPython Notebook

Rachel Street has authored an ipython notebook that demonstrates how to use the Observations API.

View in online notebook viewer or Download.

Proposals

Api root: https://observe.lco.global/api/proposals

The proposals API provides endpoints for retrieving information pertaining to proposals such as time used, time allocated, principal investigators (PIs), co-investigators (CoIs), etc.

Proposal Definition

A sample Proposal returned via API:

    {
        "id": "LCOTest-001",
        "timeallocation_set": [
            {
                "std_allocation": 25.0,
                "std_time_used": 14.3253,
                "ipp_limit": 0.0,
                "ipp_time_available": 0.0,
                "too_allocation": 0.0,
                "too_time_used": 0.0,
                "telescope_class": "1m0",
                "semester": "2017AB",
                "proposal": "LCOTest-001"
            }
        ],
        "users": [
            "isaac_newton",
            "ggalileo@lco.global"
        ],
        "pi": "isaac_newton",
        "active": false,
        "title": "Study fun things",
        "abstract": "This work is to ...",
        "tac_priority": 1000,
        "tac_rank": 0,
        "public": false,
        "tag": "LCO"
    }
Field Description
id The id of this Proposal.
timeallocation_set Time allocation information associated with this Proposal.
users The set of users (PIs and CoIs) associated with this Proposal.
pi The PI for this Proposal.
active Boolean field indicating whether UserRequests can currently be submitted with this Proposal.
title The title of the Proposal.
abstract The abstract of the Proposal.
tac_priority The priority of the Proposal as awarded by the TAC.
tac_rank The numerical ranking given to the Proposal by the TAC.
tag The group of which this Proposal is a part.

Authentication

Authentication for the proposals API is exactly the same as the Observations API.

Get all Proposals

requests.get('https://observe.lco.global/api/proposals/')

$.getJSON('https://observe.lco.global/api/proposals/')

Returns the response:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "LCOEPO1",
            "timeallocation_set": [
                {
                    "std_allocation": 15.0,
                    "std_time_used": 4.754,
                    "ipp_limit": 1.5,
                    "ipp_time_available": 0.75,
                    "too_allocation": 0.0,
                    "too_time_used": 0.0,
                    "telescope_class": "1m0",
                    "semester": "2016A",
                    "proposal": "WhiteFuzzies"
                },
            ],
            "users": [
                "bilbo@baggins.com",
                "darth.vader@empire.uk",
                "mario@plumbers.com"
            ],
            "pi": "darth.vader@empire.uk",
            "active": true,
            "title": "Observations of Stuff in the Sky",
            "abstract": "We want pretty pictures",
            "tac_priority": 1,
            "tac_rank": 1,
            "public": false,
            "tag": "LCO"
        },
        {
            "id": "LCOEPO2",
            "timeallocation_set": [
                {
                    "std_allocation": 63.0,
                    "std_time_used": 21.0,
                    "ipp_limit": 0.0,
                    "ipp_time_available": 0.0,
                    "too_allocation": 2.0,
                    "too_time_used": 0.0,
                    "telescope_class": "1m0",
                    "semester": "2014B",
                    "proposal": "LCOEPO2"
                }
            ],
            "users": [
                "steve.pete@downhill.eu",
                "aaron.gwin@fast.com"
            ],
            "pi": "aaron.gwin@fast.com",
            "active": false,
            "title": "Observing Mars",
            "abstract": "Mars observations",
            "tac_priority": 2,
            "tac_rank": 2,
            "public": false,
            "tag": "LCO"
        },
    ]
}

Authentication Required

Returns a list of Proposals that belong to the authenticated user. Time allocation information contains the observing time in hours granted to a proposal for a single semester and telescope class.

HTTP Request

GET https://observe.lco.global/api/proposals/

Query Parameters

See Proposal Definition for parameters

Get Single Proposal

requests.get('https://observe.lco.global/api/proposals/LCOEPO1/')

$.getJSON('https://observe.lco.global/api/proposals/LCOEPO1/')

Returns the response:

 {
    "id": "LCOEPO1",
    "timeallocation_set": [
        {
            "std_allocation": 15.0,
            "std_time_used": 4.754,
            "ipp_limit": 1.5,
            "ipp_time_available": 0.75,
            "too_allocation": 0.0,
            "too_time_used": 0.0,
            "telescope_class": "1m0",
            "semester": "2016A",
            "proposal": "WhiteFuzzies"
        },
    ],
    "users": [
        "bilbo@baggins.com",
        "darth.vader@empire.uk",
        "mario@plumbers.com"
    ],
    "pi": "darth.vader@empire.uk",
    "active": true,
    "title": "Observations of Stuff in the Sky",
    "abstract": "We want pretty pictures",
    "tac_priority": 1,
    "tac_rank": 1,
    "public": false,
    "tag": "LCO"
}

Authentication Required

Return information on a single Proposal.

HTTP Request

GET https://observe.lco.global/api/proposals/<id>/

Query Parameters

Parameter Required Default Description
id true The id of the Proposal.

Semesters

LCO organizes time into Semesters which are not all of uniform length. This API provides a convenient way to see when semesters start and end.

Semesters Definition

Field Description
id The id of this Semester.
start The start time of the Semester.
end The end time of the Semester.

API root: https://observe.lco.global/api/semesters/

Get All Semesters

requests.get('https://observe.lco.global/api/semesters/').json()

$.getJSON('https://observe.lco.global/api/semesters/')

Returns the response:

{
    "count": 9,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "2016B",
            "start": "2016-10-01T00:00:00Z",
            "end": "2017-03-31T23:59:59Z"
        },
        {
            "id": "2016A",
            "start": "2016-04-01T00:00:00Z",
            "end": "2016-09-30T23:59:59Z"
        },
        ...
    ]
}

Requesting the semester that contains the date 4-10-2017:

requests.get('https://observe.lco.global/api/semesters/?semester_contains=2017-04-10').json()

$.getJSON('https://observe.lco.global/api/semesters/?semester_contains=2017-04-10')

Returns the response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "2017AB",
            "start": "2017-04-01T00:00:00Z",
            "end": "2017-11-30T23:59:59Z"
        }
    ]
}

Returns a list of all Semesters.

HTTP Request

GET https://observe.lco.global/api/semesters/

Query Parameters

Parameter Required Default Description
id false The id of the Semester.
semester_contains false Result is the a single Semester that contains the given date.
start false Get only Semesters that start on or after this date.
end false Get only Semesters that end on or before this date.

Get Single Semester

requests.get('https://observe.lco.global/api/semesters/2016B/')

$.getJSON('https://observe.lco.global/api/semesters/2016B/')

Returns the response:

{
    "id": "2016B",
    "start": "2016-10-01T00:00:00Z",
    "end": "2017-03-31T23:59:59Z"
}

Return a single Semester.

HTTP Request

GET https://observe.lco.global/api/semesters/<id>/

Query Parameters

Parameter Required Default Description
id true The id of the Semester.

Telescope States

Get Telescope States

requests.get('https://observe.lco.global/api/telescope_states/?start=2017-03-23&end=2017-03-24&site=lsc&site=coj&telescope=1m0a').json()

$.getJSON('https://observe.lco.global/api/telescope_states/?start=2017-03-23&end=2017-03-24&site=lsc&site=coj&telescope=1m0a')

Returns the response:

{
     "lsc.domb.1m0a": [
        {
            "telescope": "lsc.domb.1m0a",
            "event_type": "AVAILABLE",
            "event_reason": "Available for scheduling",
            "start": "2017-03-23T00:00:00Z",
            "end": "2017-03-23T01:27:51Z"
        },
        {
            "telescope": "lsc.domb.1m0a",
            "event_type": "SEQUENCER_DISABLED",
            "event_reason": "Sequencer in MANUAL state",
            "start": "2017-03-23T01:27:51Z",
            "end": "2017-03-23T01:36:38Z"
        },
        ...
    ],
    "lsc.domc.1m0a": [
      ...
    ],
    "coj.domb.1m0a": [
      ...
    ],
    ...
}

Returns the states of telescopes in the LCO network.

HTTP Request

GET https://observe.lco.global/api/telescope_states/

Query Parameters

Parameter Required Default Description
start false now Start time.
end false now End time.
site false all Sites by which to filter (3-letter site code, e.g. lsc).
telescope false all Telescopes by which to filter (e.g. 1m0a).

Telescope Availability

Get Telescope Availability

requests.get('https://observe.lco.global/api/telescope_availability/?start=2017-03-23&end=2017-03-24&site=lsc&site=ogg').json()

$.getJSON('https://observe.lco.global/api/telescope_availability/?start=2017-03-23&end=2017-03-24&site=lsc&site=ogg')

Returns the response:

{
    "lsc.domb.1m0a": [
        [
            "2017-03-23",
            1.0
        ]
    ],
    "ogg.clma.0m4b": [
        [
            "2017-03-23",
            1.0
        ]
    ]
}

Returns the percentage that telescopes were available over the given time range.

HTTP Request

GET https://observe.lco.global/api/telescope_availability/

Query Parameters

Parameter Required Default Description
start false 24 hours ago Start time.
end false now End time.
site false all Sites by which to filter (3-letter site code, e.g. lsc).
telescope false all Telescopes by which to filter by (e.g. 1m0a).

Archive

Api Root: https://archive-api.lco.global

The archive API is a web service which provides a RESTful interface to the data stored in the archive.

To access it, use any library or program which can understand HTTP: for example, a web browser. Visiting https://archive-api.lco.global in your browser will take you to the browseable API. Here you can explore the various endpoints available, craft queries and view the JSON that will be returned. The exact URLs you visit in the browseable API can be used to return JSON to other programs, so it is a useful tool to explore the API.

The API can also be accessed using a variety of programmatic interfaces, such as curl:

curl https://archive-api.lco.global/frames/ > results.json

Which will get the metadata for the last 100 data products in the archive, and store that information in results.json

Rate Limits

The archive API is rate limited so that it remains available to all users in the event a single user makes too many requests in too rapid a succession, causing denial of service to other clients.

All logged in users are limited to 5,000 HTTP calls in a 24 hour period. Anonymous users are limited to 3,500 calls in a 24 hour period.

Authentication

requests.post(
    'https://archive-api.lco.global/api-token-auth/',
    data = {
        'username': 'bilbo@lco.global',
        'password': 'myprecious'
    }
).json()

$.ajax({
    url: 'https://archive-api.lco.global/api-token-auth/',
    type: 'post',
    data: {username: 'bilbo', password: 'myprecious'},
    dataType: 'json',
    success: function(data){
        console.log(data.token)
    }
});

Returns the response:

{ "token": "3d46d6b98edef947402e032e73eca7b54661c666" }

The returned token must be set in the Authorization header for all api requests.

requests.get('https://archive-api.lco.global/frames/', headers={'Authorization': 'Token <token>'})

$.ajax({
    url: 'https://archive-api.lco.global/frames/',
    headers: {'Authorization': 'Token <token>'}
})

The archive API is authenticated and will only return results the user is authorized to view. For a non logged in user, this is all public data. For a logged in user, this is public data and data which belongs to proposals that the user is a part of.

A user can authenticate by posting a username and password to the /api-token-auth/ endpoint which will return an API token. The token must then be placed in the Authorization header of subsequent requests in the the following form:

Token <token>

An example of obtaining a token using curl:

curl --data "username=bilbo@lco.global&password=myprecious" https://archive-api.lco.global/api-token-auth/

returns:

{"token":"3d46d6b98edef947402e032e73eca7b54661c968"}

The token can now be used in resulting requests:

curl --header "Authorization: Token 3d46d6b98edef947402e032e73eca7b54661c968" https://archive-api.lco.global/frames/

Data Format Definition

A sample frame returned via API:

{
    "id": 42120,
    "basename": "ogg2m001-fs02-20160202-0133-e91",
    "area": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    135.12548613998868,
                    36.53399918890214
                ],
                [
                    135.12571388933247,
                    36.701867589076244
                ],
                [
                    134.91633784602044,
                    36.70186763472167
                ],
                [
                    134.91656548197224,
                    36.53399923426909
                ],
                [
                    135.12548613998868,
                    36.53399918890214
                ]
            ]
        ]
    },
    "related_frames": [
        1375,
        42119,
        42078,
        42040,
        42039
    ],
    "version_set": [
        {
            "id": 44713,
            "created": "2016-02-03T22:27:59.236409Z",
            "key": "dtxW9DM0lwKNpsPYlnhEzDt41OCp7q0i",
            "md5": "e1836a49b573ac50ccddba7e54661564",
            "extension": ".fits",
            "url": "https://lcogtarchivetest.s3.amazonaws.com/44f2/ogg2m001-fs02-20160202-0133-e90?versionId=dtxW9DM0lwKNpsPYlnhEzDt41OCp7q0i&Expires=1454542848&AWSAccessKeyId=AKIAIZBYNSZZGYN3EAQQ&Signature=T3XtzW8bTYqI48haJZFvEMdqb6M%3D"
        }
    ],
    "url": "https://lcogtarchivetest.s3.amazonaws.com/44f2/ogg2m001-fs02-20160202-0133-e90?versionId=dtxW9DM0lwKNpsPYlnhEzDt41OCp7q0i&Expires=1454542848&AWSAccessKeyId=AKIAIZBYNSZZGYN3EAQQ&Signature=T3XtzW8bTYqI48haJZFvEMdqb6M%3D",
    "filename": "ogg2m001-fs02-20160202-0133-e90.fits",
    "RLEVEL": 91,
    "DATE_OBS": "2016-02-03T09:05:57.414000Z",
    "PROPID": "FTPEPO2014A-003",
    "INSTRUME": "fs02",
    "OBJECT": "P 2010 v1",
    "SITEID": "ogg",
    "TELID": "2m0a",
    "EXPTIME": "60.000",
    "FILTER": "R",
    "L1PUBDAT": "2016-02-03T09:05:57Z",
    "OBSTYPE": "EXPOSE",
    "BLKUID": 54321,
    "REQNUM": 12345
}

The archive endpoints return metadata formatted in json. An example of a typical entry corresponding to a single data product is given on the right.

Much of the meta-data matches values from the file’s FITS headers:

Field Description
DATE_OBS The UTC time at the start of exposure.
PROPID The name of the proposal for which this frame was taken.
INSTRUME The instrument that produced this frame.
OBJECT The name of the object given by the user as the target of the observation. Note this is not the same as searching by on sky position - the OBJECT header is free-form text which may or may not match the actual contents of the file.
SITEID The site that produced this frame.
TELID The telescope that produced this frame.
EXPTIME The exposure time of the frame.
FILTER The filter used to produce this frame.
L1PUBDAT The date this frame become public.
OBSTYPE The type of exposure: EXPOSE, BIAS, SPECTRUM, CATALOG, etc.
BLKUID The Block ID of the frame
REQNUM The Request number of the frame
RLEVEL The reduction level of the frame. Currently, there are 3 reduction levels: Some of the meta-data fields are derived and not found in the FITS headers. 0 (Raw), 11 (Quicklook), 91 (Final reduced).
Field Description
basename is the base of the filename without a file extension.
area is a WKT Polygon which represents the frame’s coverage of the sky. Each point in the polygon is a RA Dec pair in degrees.
related_frames is a list of ids of other frames that are related to this one. These can include calibration files, catalog files, final data products, etc.
version_set is a list of versions for this frame. Each version contains a url to download the file, a file extension, an md5 checksum, and a datetime.
url is the URL to download the frame, from the latest version.

Aggregate

requests.get('https://archive-api.lco.global/aggregate/').json()

$.getJSON('https://archive-api.lco.global/aggregate/')

Returns the response:

{
  "filters": [
      "ip",
      "LL",
      "zs",
  ],
  "instruments": [
      "fl04",
      "fs02",
      "en05",
  ],
  "telescopes": [
      "2m0a",
      "1m0a",
      "0m4a",
  ],
  "obstypes": [
      "SKYFLAT",
      "BIAS",
      "EXPOSE",
  ],
  "sites": [
      "ogg",
      "tfn",
      "bpl",
  ]
}

Returns the unique values shared across all fits files for site, telescope, instrument, filter and obstype.

HTTP Request

GET https://archive-api.lco.global/aggregate/

Query Parameters

None

List Frames

requests.get('https://archive-api.lco.global/frames/').json()

$.getJSON('https://archive-api.lco.global/frames/')

Returns the response:

{
  "count": 9000,
  "next": "https://archive-api.lco.global/frames/?limit=100&offset=100",
  "previous": null,
  "results": [
    {
      ... Frame Payload ...
    }
  ]
}

Return a list of frames.

HTTP Request

GET https://archive-api.lco.global/frames/

Query Parameters

All parameters are optional

Parameter Type Description
basename string Frames which contain this value in their basename
DATE OBS datetime Frames taken exactly on this date
PROPID string Frames which belong to this proposal
SITEID string Frames produced at this site
TELID string Frames produced from this telescope
Filter string Frames produced using this filter
OBSTYPE string Frames which match this OBSTYPE
INSTRUME string Frames taken with this instrument
OBJECT string Frames which contain this value in their OBJECT header
start datetime Frames with a DATE-OBS later than this date
end datetime Frames with a DATE-OBS earlier than this date
public boolean Frames that are public. Default: true
RLEVEL integer Frames at this reduction level
L1PUBDAT datetime Frames that go public on this date
covers POINT Frames which cover this specific point.

Note about the POINT datatype: The value is a WKT point of RA and DEC in degrees. Example /frames/?covers=POINT(34.4 -20.9)

Get Single Frame

requests.get('https://archive-api.lco.global/frames/42/').json()

$.getJSON('https://archive-api.lco.global/frames/42/')

Returns the response:

{
    "id": 32,
  ... frame payload ...
}

Returns details about a specific frame.

HTTP Request

GET https://archive-api.lco.global/frames/<id>/

Query Params:

Parameter Type Description
id integer The id of this frame 
requests.get('https://archive-api.lco.global/frames/42/related/').json()

$.getJSON('https://archive-api.lco.global/frames/42/related/')

Returns the response:

[
  {
    ... List of frames ...
  }
]

Returns calibration, raw/reduced frames associated with this frame.

HTTP Request

GET https://archive-api.lco.global/frames/<id>/related/

Query Params:

Parameter Type Description
id integer The id of this frame

Get Headers

requests.get('https://archive-api.lco.global/frames/42/headers/').json()

$.getJSON('https://archive-api.lco.global/frames/42/headers/')

Returns the response:

{
    "data": {
        "AZIMUTH": 180.3819459,
        "OBSGEO_Y": -5213920.079,
        "M1COVER": "DEPLOYED",
        "SCHEDSEE": "",
        "FOCOBOFF": 0.0,
        "FILTER1": "air",
        "NAXIS2": 4096,
        ...
    }
}

Retrieve the FITS headers for this frame.

HTTP Request

GET https://archive-api.lco.global/frames/<id>/headers/

Query Params:

Parameter Type Description
id integer The id of this frame

Profile

requests.get('https://archive-api.lco.global/profile/').json()

$.getJSON('https://archive-api.lco.global/profile/')

Returns the response:

{
  "username": "bilbo@lco.global",
  "profile": {
    "proposals": [
      "FellowshipProposal",
      "Hobbits2015A",
      "Quests"
    ]
  }
}

Returns details about the currently authenticated user.

HTTP Request

GET https://archive-api.lco.global/profile/

Query Params:

None

Code Samples

lcogtDD

Nestor Espinoza has written a command line script to download files from the LCO archive.

View on Github

Thumbservice

The Thumbnail API is a flask script which takes advantage of the LCO Archive API.

View on Github

Thumbnails

API Root: https://thumbnails.lco.global

The thumbnail service provides a simple api to generate images from data stored on the archive. This api is useful for creating interfaces or education material.

Authentication

The thumbnail api passes through the value of the Authorization HTTP header through to the archive api. For proprietary data it is necessary to provide this header, public data needs no authentication. Thus, to authenticate with the thumnail api, you must first obtain an authentication key from the archive api. Then make requests to the thumbnail api, using the Authorization header as you would on the archive.

Generate Thumbnail

requests.get('https://thumbnails.lco.global'/<frame_id>/').json()

$.getJSON('https://thumbnails.lco.global/<frame_id>/')

Returns the response:

{

    "propid": "FTPEPO2014A-003",
    "url": "https://s3-us-west-2.amazonaws.com/thumbnails.lcogt.net/6124256.4163566684581698428.jpg?AWSAccessKeyId=AKIAIIXJI2IT23CSF2RA&Expires=1493352936&Signature=x%2B5b8ZHZTW850dVVx%2ByyYiLIGbY%3D"

}

Generates a thumbnail from the frame identified by frame_id. The url to the jpg will be returned in the url key of the response.

To obtain the frame id, use the archive api.

HTTP Request

GET https://thumbnails.lco.global/<frame_id>/

Query Parameters

Parameter Required Description
frame_id true The id of the frame to be thumbnailed
width false The width (in pixels) of the generated image
label false Place text on the thumbnail
color false Generate a color image. note: this only works for frames where there are R,V and B filter versions of the same observation.

Pressure

Get Network Pressure

requests.get('https://observe.lco.global/api/pressure/?site=lsc').json()

$.getJSON('https://observe.lco.global/api/pressure/?site=lsc')

Returns the response:

{
    "pressure_data": [
        {},
        {},
        ...
        {
            "All Proposals": 0.00019054754269455878,
        },
        {
            "All Proposals": 0.00019054754269455878,
        },
        {
            "All Proposals": 0.00019054754269455878,
        },
        {
            "All Proposals": 0.00019054754269455878,
        },
        ...
        {},
        {},
    ],
    "time_bins": [
        "2017-05-19T00:50:14.537278Z",
        "2017-05-19T01:05:14.537278Z"
        ...
        "2017-05-20T00:20:14.537278Z",
        "2017-05-20T00:35:14.537278Z"
    ],
    "site_nights": [
        {
            "name": "lsc",
            "start": 2.691666666666667,
            "stop": 14.288055555555555
        }
    ],
    "site": "lsc",
    "instrument_name": "all",
    "time_calculated": "2017-05-19T00:50:14.537278Z"
}

The pressure of a Request is defined as its duration divided by the total length of time for which it is visible. For each time bin, this value is further divided by the number of telescopes from which the Request is visible during that time bin. An overall pressure of 1 means the network is perfectly subscribed on average (> 1 is over-subscription, < 1 is under-subscription).

The returned data structure has the following keys: pressure, time_bins, site_nights, site, instrument_name, and time_calculated.

pressure is an array of 15 minute time buckets whose value is the pressure in that bucket. The first bucket begins now and the last bucket ends 24 hours from now.

time_bins is an array that holds the start time of each bucket.

site_nights shows start and end times of local nights at sites in the next 24 hours, in hours from now.

site is the site for which the pressure data is calculated. This is either ‘all’ or a single site.

instrument_name is the instrument for which the pressure data is calculated. This is either ‘all’ or a specific instrument.

time_calculated is the time at which the pressure was calculated, i.e. now.

HTTP Request

GET https://observe.lco.global/api/pressure/

Query Parameters

Parameter Required Default Description
site false all Set to a 3-letter site code to return pressure for that site only, e.g. ‘lsc’.
instrument false all Set to a specific instrument to show pressure for that instrument only, e.g. ‘1M0-SCICAM-SINISTRO’.

Contention

Get Contention

requests.get('https://observe.lco.global/api/contention/1M0-SCICAM-SINISTRO/').json()

$.getJSON('https://observe.lco.global/api/contention/1M0-SCICAM-SINISTRO/')

Returns the response:

{
    "contention_data": [
        {
            "All Proposals": 0
        },
        {
            "All Proposals": 0
        },
        {
            "All Proposals": 584
        },
        ...
        {
            "All Proposals": 0
        },
        {
            "All Proposals": 4360
        },
        {
            "All Proposals": 16890
        },
    ],
    "ra_hours": [
        0,
        1,
        ...
        22,
        23
    ],
    "instrument_name": "1M0-SCICAM-SINISTRO",
    "time_calculated": "2017-05-19T00:50:14.606194Z"
}

The contention of the network is the total amount of telescope time requested by right ascension (RA) and instrument. Observations requested where contention is high are more likely to incur scheduling conflicts.

The returned data structure contains the keys contention_data, ra_hours, instrument_name, and time_calculated.

contention_data is an array of 1 hour bins in RA where the value of each bin is the contention at that RA in total seconds.

ra_hours is an array of the RAs of each bin.

instrument_name is the instrument for which the contention data is calculated. This is either ‘all’ or a specific instrument.

time_calculated is the time at which the contention data was calculated, i.e. now.

HTTP Request

GET https://observe.lco.global/api/contention//<instrument>/

Query Parameters

Parameter Required Default Description
instrument false all Set to a specific instrument to show contention for that instrument only, e.g. ‘1M0-SCICAM-SINISTRO’.
Python Javascript