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.

Paginating Results

Any LCO api which returns a list of potentially many results will be paginated. The default limit is usually 100 but may vary based on the type of data being returned.

Results can be iterated on using the limit and offset query parameters. For example, if your query result count is 2200, you can make 3 queries to access all the results:

limit=1000&offset=0

limit=1000&offset=1000

limit=1000&offset=2000

New Observations API!

The release date of version 3 of the observations API is June 25, 2019!

Version 2 will be supported through the 2019B semester, which ends on November 30, 2019.

Observations v3

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

Overview

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

Observation requests cannot be edited once they are submitted, but they can be canceled. You may follow their statuses using endpoints outlined below.

Practical examples on how to use this API are provided by scripts linked from the code samples section.

Rate Limits

The observations API is rate limited in order to remain available to all users in the event that a single user attempts to make too many requests in too rapid a succession, causing denial of service to other clients.

Data Format Definition

Observation Request Model Structure

Observation requests follow a hierarchical structure as shown in the diagram below:

Request Model Image

RequestGroup

The top level entity in the LCO request language is the RequestGroup. A RequestGroup contains one or more Requests and acts as a logical grouping to help the end user keep track of a set of Requests. All observing requests are submitted within this top level struture.

A sample RequestGroup returned via the API:

{
    "id": 12345,
    "submitter": "austin_riba",
    "requests": [...],
    "name": "Test observation",
    "observation_type": "NORMAL",
    "operator": "SINGLE",
    "ipp_value": 1.05,
    "state": "PENDING",
    "proposal": "LCOEngineering"
}

Field	Read Only	Required	Options	Description
id	true	false		The id of this `RequestGroup`.
requests	false	true		The list of `Request`s to be observed for this `RequestGroup`.
submitter	true	false		The user that submitted the `RequestGroup`.
proposal	false	true		The `Proposal` under which this observation will be made.
name	false	true		A string placed in the FITS header as the GROUPID keyword value for all FITS frames originating from this `RequestGroup`.
observation_type	false	true	NORMAL, RAPID_RESPONSE, TIME_CRITICAL	The type of observation. A proposal must be granted time specifically for each observation type. More information can be found 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 `RequestGroup` and all of its child `Request`s. 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, see here. Note that ipp time only applies to NORMAL observation_type requests.
state	true	false	PENDING, WINDOW_EXPIRED, COMPLETED, CANCELED	The current state of this `RequestGroup`.

Request

A sample Request returned via the API:

{
    "id": 4,
    "location": {...},
    "configurations": [...],
    "windows": [...],
    "observation_note": "",
    "state": "PENDING",
    "acceptability_threshold": 90
}

A Request is a single independent set of observations to be scheduled in one contiguous block on a resource.

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.
configurations	false	true		A list of `Configuration`s.
windows	false	true		A list of `Window`s in which this `Request` should be considered for observation.
observation_note	false	false		Text describing this `Request`.
acceptability_threshold	false	false		The percentage of the observation that must be completed to mark the request as complete and avert rescheduling. The percentage should be set to the lowest value for which the amount of data is acceptable to meet the science goal of the request. Defaults to 100 for FLOYDS observations and 90 for all other observations.
state	true	false	PENDING, WINDOW_EXPIRED, COMPLETED, CANCELED	The current state of this `Request`.

Location

A sample location returned via the API:

{
    "telescope_class": "2m0"
}

A Location specifies a set of restrictions on which resources the Request can be scheduled.

Field	Read Only	Required	Options	Description
telescope_class	false	true	0m4, 0m8, 1m0, 2m0, 4m0	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.

Window

A sample window returned via the API:

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

A Window specifies one or more datetime intervals during which the Request can be observed. The visibility calculator might be helpful in deciding a window for your observation.

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.

Configuration

A sample configuration returned via API:

{
    "type": "EXPOSE",
    "instrument_type": "2M0-SCICAM-SPECTRAL",
    "instrument_configs": [...],
    "acquisition_config": {...},
    "guiding_config": {...},
    "constraints": {...},
    "target": {...}
}

A Configuration defines the configuration for a set of observations on a single Target.

Field	Read Only	Required	Options	Description
type	false	true	EXPOSE, SPECTRUM, LAMP_FLAT, ARC, STANDARD	The type of exposure.
instrument_type	false	true	1M0-SCICAM-SINISTRO, 2M0-SCICAM-SPECTRAL, 0M4-SCICAM-SBIG, 2M0-FLOYDS-SCICAM, 1M0-NRES-SCICAM, SOAR_GHTS_REDCAM, SOAR_GHTS_REDCAM_IMAGER	The type of instrument.
constraints	false	true		The observation `Constraints` placed on this `Configuration`.
target	false	true		The `Target` to observe.
instrument_configs	false	true		A list of `InstrumentConfig`s belonging to this `Configuration`. Note that at this time only one `InstrumentConfig` is allowed per `Configuration` for instruments that are not SOAR_GHTS_REDCAM or SOAR_GHTS_REDCAM_IMAGER.
acquisition_config	false	true		The `AcquisitionConfig` of this `Configuration`
guiding_config	false	true		The `GuidingConfig` of this `Configuration`

InstrumentConfig

A sample instrument configuration returned via API:

{
    "exposure_time": 30.0,
    "exposure_count": 1,
    "bin_x": 1,
    "bin_y": 1,
    "mode": "full_frame",
    "rotator_mode": "",
    "optical_elements": {
        "filter": "R"
    },
    "extra_params": {
        "defocus": 0.0
    }
}

An InstrumentConfig defines a set of exposures using certain instrument settings. To read about instruments and their possible configurations, you can go here. For information on the SOAR GHTS instrument specifically, go here.

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. De-focus may be specified as an InstrumentConfig extra parameter with the defocus field. For more information, you can look though the “Getting Started” guide linked from here.

Field	Read Only	Required	Options	Description
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 `InstrumentConfig` 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.
rotator_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. If the rotator_mode is set to SKY, a rotator_angle field must be passed in the extra_params. The rotator_angle is the position of the slit in degrees east of north
optical_elements	false	false		The optical elements to use for this `InstrumentConfig`. The fields slit, filter, grating, and/or lamp may be passed in here, depending on the available optical elements for the instrument type specified in the parent `Configuration`.
extra_params	false	false		Extra `InstrumentConfig` parameters

AcquisitionConfig

A sample acquisition configuration returned via the API:

{
    "mode": "BRIGHTEST",
    "extra_params": {
      "acquire_radius": 5.0    
    }
}

An AcquisitionConfig defines how to configure acquisition for a Configuration.

Field	Read Only	Required	Options	Description
mode	false	false	WCS, BRIGHTEST, MANUAL	The method for positioning the slit if there is a slit. If BRIGHTEST is selected, the slit is placed on the brightest object near the target coordinates, and `acquire_radius`, which is the radius in arcseconds in which to search for the brightest object, must be set in the extra parameters. This field will default to the instrument default if not set.
extra_params	false	false		Extra `AcquisitionConfig` parameters.

GuidingConfig

A sample guiding configuration returned via the API:

{
    "mode": "ON",
    "optional": true,
    "extra_params": {}
}

A GuidingConfig defines how to configure guiding for a Configuration.

Guiding keeps the field stable during long exposures. If the mode is set to ON and optional is set to true, guiding is attempted but the observations are carried out even if guiding fails. If the mode is set to ON and optional is set to false, observations are aborted if guiding fails. Guiding is not attempted if the mode is set to OFF.

For more information on guiding, you can look though the “Getting Started” guide linked here.

Field	Read Only	Required	Options	Description
mode	false	false	ON, OFF	Guiding mode.
optional	false	false	true, false	Whether guiding is optional.
extra_params	false	false		Extra `GuidingConfig` parameters.

Constraints

A sample Constraints returned via the API:

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

Constraints define conditions that must be met in order to schedule the observation.

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

A Target describes 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	ICRS, ORBITAL_ELEMENTS	Type of `Target`.
name	false	true		The name of this `Target`.

A sample sidereal Target returned via the API:

{
    "type": "ICRS",
    "name": "m42",
    "ra": 83.8220792,
    "dec": -5.3911111,
    "proper_motion_ra": 1.67,
    "proper_motion_dec": -0.3,
    "parallax": 0.0,
    "epoch": 2000.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	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.

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": "ORBITAL_ELEMENTS",
    "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.

Migration from V2

The release of V3 of the observing portal API brings with it some backwards incompatible API changes. Those changes are listed here.

Data format definition changes

UserRequest has been renamed to RequestGroup. Make sure to change the endpoint from /api/userrequests/ to /api/requestgroups/.
Molecule has been renamed to Configuration.
Within a RequestGroup, the group_id field has been renamed to name
A Configuration contains all of the necessary configuration for an observation just like a Molecule contained, but the data within has been restructured and some field names have changed. In addition, Constraints and Target have moved from the Request level to the Configuration level. Please refer to the descriptions in the Data Format Definition for the changes.
For Targets, the SIDEREAL type has been renamed to ICRS and the NON_SIDEREAL type has been renamed to ORBITAL_ELEMENTS. The equinox and coordinate_system fields have been removed.
Certain structures have a new extra_params field. This is a JSON field that takes arbitrary fields and is used for things like passing required parameters when a certain value for another field is set. For example, the BRIGHTEST acquisition mode needs to know within what radius of the target to search for the brightest object. This radius must be set in the extra_params of an AcquisitionConfig when the BRIGHTEST mode is selected.
The V2 defocus Molecule field must now be set as an extra param to an InstrumentConfig with the “defocus” key. The V2 acquire_radius_arcsec Molecule field must now be set as an AcquisitionConfig extra_param with the “acquire_radius” key.
The InstrumentConfig structure has a new optical_elements field. This is a JSON field in which the optical elements to be used for that instrument configuration must be set. Common optical element fields are filter and slit. Each instrument has different optical elements. Optical elements are validated against the list of schedulable elements for each instrument type.
The TARGET_OF_OPPORTUNITY observation type is now RAPID_RESPONSE.

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 RequestGroup

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

$.ajax({
    url: 'https://observe.lco.global/api/requestgroups/',
    type: 'post',
    data: {
        'name': '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,
    "name": "Submit me",
    "proposal": "Test Proposal",
    "ipp_value": 1.05,
    "operator": "SINGLE",
    "observation_type": "NORMAL",
    "state": "PENDING",
    "requests": [...]
}

Authentication Required

Submit a RequestGroup to be observed. Please refer to the introduction for date formatting help.

Http Request

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

Query Parameters

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

Get All RequestGroups

Authentication Required

Returns a list of RequestGroups submitted under proposals of which you are a member. Please refer to the introduction for date formatting help.

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

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

Returns the response:

{
    "count": 18,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 4,
            "requests": [...],
            "submitter": "austin_riba",
            "name": "testhis",
            "observation_type": "NORMAL",
            "operator": "SINGLE",
            "ipp_value": 1.05,
            "state": "PENDING",
            "proposal": "LCOEngineering"
        }
    ]
}

Http Request

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

Query Parameters

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

Get Single RequestGroup

Authentication Required

Returns a single instance of a RequestGroup.

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

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

Returns the response:

{
    "id": 3456,
    "requests": [...],
    "submitter": "austin_riba",
    "name": "testhis",
    "observation_type": "NORMAL",
    "operator": "SINGLE",
    "ipp_value": 1.05,
    "state": "PENDING",
    "proposal": "LCOEngineering"
}

Http Request

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

Query Parameters

Parameter	Required	Default	Description
id	true		The id of the `RequestGroup`.

Cancel RequestGroup

Authentication Required

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

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

$.ajax({
    url: 'https://observe.lco.global/api/requestgroups/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/requestgroups/<id>/cancel/

Query Parameters

Parameter	Required	Default	Description
id	true		The id of the `RequestGroup`.

Validate a RequestGroup

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

$.ajax({
    url: 'https://observe.lco.global/api/requestgroups/validate/',
    type: 'post',
    data: {
        "name": "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 RequestGroup is valid before submission. The response contains the duration of the each Request which is debited from the proposal’s allocated time upon completion. Please refer to the introduction for date formatting help.

Http Request

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

Query Parameters

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

Get Max Allowable IPP

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

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

Returns the result:

{
    "2016B": {
        "1m0": {
            "1M0-SCICAM-SINISTRO": {
                "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. Please refer to the introduction for date formatting help.

HTTP Request

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

Query Parameters

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

Generate Cadence

requests.post(
    'https://observe.lco.global/api/requestgroups/cadence/',
    json={
        'name': '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/requestgroups/cadence/',
    type: 'post',
    data: {
        "name": "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 RequestGroup containing a single Request that has a cadence key, this endpoint returns a new RequestGroup with multiple Requests generated by the cadence function. Please refer to the introduction for date formatting help.

HTTP Request

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

Query Parameters

Parameter	Required	Description
*	true	A well formed `RequestGroup` 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 `Request`s.
end	true	The UTC date that marks the end of the window in which to generate the cadenced `Request`s.
period	true	The fractional hours between observations. A 24 hour window with a period of 6 hours should have 3-4 `Request`s 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 `Request`s with `Window`s 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 in the first Configuration from the sites for which it is visible in 10 minute intervals. The max_airmass in the first Configuration’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 v3

Observation API Examples

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

View on Github

Observations v2

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.

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 `Request`s 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. `Request`s 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 `Request`s. 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",
    "acceptability_threshold": 90,
    "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 `Molecule`s.
windows	false	true		A list of `Window`s in which this `Request` should be considered for observation.
observation_note	false	false		Text describing this `Request`.
acceptability_threshold	false	false		The percentage of the observation that must be completed to mark the request as complete and avert rescheduling. The percentage should be set to the lowest value for which the amount of data is acceptable to meet the science goal of the request. Defaults to 100 for FLOYDS observations and 90 for all other observations.
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	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

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, 1M0-NRES-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:

group_id
ipp_value
observation_type

In a Target:

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. Please refer to the introduction for date formatting help.

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. Please refer to the introduction for date formatting help.

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 `UserRequest`s created after the given date.
created_before	false			Result includes `UserRequest`s created before the given date.
state	false		PENDING, SCHEDULED, CANCELED, COMPLETED, WINDOW_EXPIRED	Result includes `UserRequest`s matching the given state.
title	false			Result includes `UserRequest`s with a `group_id` that contains or matches the given value.
user	false			Result includes `UserRequest`s submitted by users whose usernames contain the given value.
proposal	false			Result includes `UserRequest`s submitted under the specified proposal.
observation_type	false		NORMAL, TARGET_OF_OPPORTUNITY	Results include `UserRequest`s with the specified observation type.
ipp_value	false			Results include `UserRequest`s 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. Please refer to the introduction for date formatting help.

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": {
            "1M0-SCICAM-SINISTRO": {
                "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. Please refer to the introduction for date formatting help.

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. Please refer to the introduction for date formatting help.

HTTP Request

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

Query Parameters

Parameter	Required	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 `Request`s.
end	true	The UTC date that marks the end of the window in which to generate the cadenced `Request`s.
period	true	The fractional hours between observations. A 24 hour window with a period of 6 hours should have 3-4 `Request`s 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 `Request`s with `Window`s 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 v2

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.

Migration from V2 to V3 of the Observations API

Note that there have been slight changes to time allocations with this change of the API. The TARGET_OF_OPPORTUNITY (TOO) type of time has been renamed to RAPID_RESPONSE (RR), and a TIME_CRITICAL (TC) type time has been added. In addition, within a timeallocation, the telescope_class field has been removed and the instrument_name field has been renamed to instrument_type.

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,
                "rr_allocation": 0.0,
                "rr_time_used": 0.0,
                "tc_allocation": 0.0,
                "tc_time_used": 0.0,
                "instrument_type": "1M0-SCICAM-SINISTRO",
                "semester": "2017AB",
                "proposal": "LCOTest-001"
            }
        ],
        "users": {
            "isaac_newton":{
                "first_name": "Issac",
                "last_name": "Newton",
                "time_limit": 3600
            },
            "ggalileo@lco.global":{
                "first_name": "Galileo",
                "last_name": "Galilei",
                "time_limit": -1,
            }
        },
        "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` and their associated time information (in seconds).
pi	The PI for this `Proposal`.
active	Boolean field indicating whether `UserRequest`s 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,
                    "rr_allocation": 0.0,
                    "rr_time_used": 0.0,
                    "tc_allocation": 0.0,
                    "tc_time_used": 0.0,
                    "instrument_type": "1M0-SCICAM-SINISTRO",
                    "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,
                    "rr_allocation": 2.0,
                    "rr_time_used": 0.0,
                    "tc_allocation": 2.0,
                    "tc_time_used": 0.0,
                    "instrument_type": "1M0-SCICAM-SINISTRO",
                    "semester": "2014B",
                    "proposal": "LCOEPO2"
                }
            ],
            "users": {
                "steve.pete@downhill.eu":{
                    "first_name": "Steve",
                    "last_name": "Pete",
                    "time_limit": 240,
                },
                "aaron.gwin@fast.com":{
                    "first_name": "Aaron",
                    "last_name": "Gwin",
                    "time_limit": 3400,
                }
            },
            "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 instrument type.

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,
            "rr_allocation": 0.0,
            "rr_time_used": 0.0,
            "tc_allocation": 0.0,
            "tc_time_used": 0.0,            
            "instrument_type": "1M0-SCICAM-SINISTRO",
            "semester": "2016A",
            "proposal": "WhiteFuzzies"
        },
    ],
    "users": {
        "bilbo@baggins.com": {
            "first_name": "Bilbo",
            "last_name": "Baggins",
            "time_limit": 454,
        },
        "darth.vader@empire.uk": {
            "first_name": "Anakin",
            "last_name": "Skywalker",
            "time_limit": 2100,
        }
    },
    "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. Please refer to the introduction for date formatting help.

HTTP Request

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

Query Parameters

Parameter	Required	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 `Semester`s that start on or after this date.
end	false	Get only `Semester`s 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. Please refer to the introduction for date formatting help.

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. Please refer to the introduction for date formatting help.

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).

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 Observation 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
id	is the ID of the frame.
filename	is the filename.
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.

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’.

Weather

Retrieve Weather

API Root: https://weather-api.lco.global

The weather API provides a method for querying the current and historical weather conditions at each site in the LCO network.

The data is returned in 15 minute binned averages over the specified time range. A maximum of 1000 buckets will be returned (about 12 days).

Please refer to the introduction for date formatting help.

requests.get('https://weather-api.lco.global'/query?site=<site>&datumname=<datumname>&start=<start>&end=<end>').json()

$.getJSON('/query?site=<site>&datumname=<datumname>&start=<start>&end=<end>')

Returns the response:

[
    {
        "TimeStamp": "2018/02/25 17:45:00",
        "Value":15.385715
    },{
        "TimeStamp":"2018/02/25 18:00:00",
        "Value":14.831818
    },{
        "TimeStamp":"2018/02/25 18:15:00",
        "Value":15.137931
    },{
        "TimeStamp":"2018/02/25 18:30:00",
        "Value":14.737931
    }
]

Authentication

The weather API does not require authentication.

Available Datums

The following weather datums are available:

Name	Description
Weather Air Temperature Value	Ambient temperature measured by HMP45C-L temperature probe at the site’s weather station.
Boltwood Sky Minus Ambient Temperature	Sky Temperature is inferred from 8-14µm irradiance measured by a Boltwood II cloud sensor at the site’s weather station.
Weather Humidity Value	Relative humidity measured by HMP45C-L humidity probe at the site’s weather station.
Weather Barometric Pressure Value	Barometric pressure measured by Vaisala PTB110 barometer at the site’s weather station.
Weather Wind Speed Value	Wind speed measured by Windsonic1-L wind sensor at the site’s weather station.
Weather Wind Direction Value	Wind direction, in degrees East of North, measured by Windsonic1-L wind sensor at the site’s weather station.
Weather Sky Brightness Value	Sky brightness, in magnitudes per square arcsecond, measured by Unihedron SQM-LE at the site’s weather station.

HTTP Request

GET https://weather-api.lco.global/query/

Query Parameters

Parameter	Required	Description
site	true	The LCO site code
datumname	true	The datum to retrieve
start	false	The datetime for the start of the time window. Defaults to 24 hours ago.
end	false	The datetime for the end of the time window. Defaults to now.

Parameter	Type	Description
PROPID	string	Unique values for frames which belong to this proposal
SITEID	string	Unique values for frames produced at this site
TELID	string	Unique values for frames produced from this telescope
FILTER	string	Unique values for frames produced using this filter
OBSTYPE	string	Unique values for frames which match this OBSTYPE
INSTRUME	string	Unique values for frames taken with this instrument
start	datetime	Unique values for frames with a DATE-OBS later than or equal to this date
end	datetime	Unique values for frames with a DATE-OBS earlier than or equal to this date

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
REQNUM	integer	Frames which belong to this Request
BLKUID	integer	Frames which belong to this observation ID
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
EXPTIME	integer	Frames where the exposure time is greater than or equal to this value, in seconds
L1PUBDAT	datetime	Frames that go public on this date
covers	POINT	Frames which cover this specific point.
intersects	POINT	Frames which intersect with this specific point.