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

Observations

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 sample repeat configuration returned via API:

{
    "type": "REPEAT_EXPOSE",
    "instrument_type": "2M0-SCICAM-SPECTRAL",
    "repeat_duration": 1500.0,
    "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, REPEAT_EXPOSE, SPECTRUM, REPEAT_SPECTRUM, NRES_SPECTRUM, REPEAT_NRES_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.
repeat_duration	false	false		Duration in seconds. For any `REPEAT_` type exposure, this is the duration within which its `InstrumentConfig`s should be repeated in a loop. Only applicable for `REPEAT_` type `Configuration`s.
fill_window	false	false		You may optionally set the `fill_window` field to the `Configuration` upon submission with a value of `true`. If this is set, the `repeat_duration` is set to the maximum configuration duration that will fit in the observing window. Only applicable for `REPEAT_*` type `Configuration`s.
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`. When more than one `InstrumentConfig` is in the list, the first will run to completion, then the second, etc. It is recommended to only use a single `InstrumentConfig` in an NRES or FLOYDS `Configuration`. The target is not re-acquired from one `InstrumentConfig` to the next, so it may not remain optimally centered on the slit, if changed.
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,
    "mode": "full_frame",
    "rotator_mode": "",
    "optical_elements": {
        "filter": "R"
    },
    "extra_params": {
        "defocus": 0.0,
        "bin_x": 1,
        "bin_y": 1
    }
}

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.
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. When defining multiple `InstrumentConfig`s within a `Configuration`, the same rotator mode must be set in every `InstrumentConfig`.
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

MUSCAT instrument configuration

A sample MUSCAT instrument InstrumentConfig

{
    "exposure_time": 33.0,
    "exposure_count": 10,
    "mode": "MUSCAT_SLOW",
    "optical_elements": {
        "diffuser_g_position": "in",
        "diffuser_r_position": "out",
        "diffuser_i_position": "out",
        "diffuser_z_position": "in"
    },
    "extra_params": {
        "bin_x": 1,
        "bin_y": 1,
        "exposure_mode": "SYNCHRONOUS",
        "exposure_time_g": 33.0,
        "exposure_time_r": 31.0,
        "exposure_time_i": 30.0,
        "exposure_time_z": 28.7
    }
}

Requests using the 2M0-SCICAM-MUSCAT instrument_type must specify a few extra parameters in the extra_params section of each instrument config. A separate exposure time must be set for each of the 4 cameras within the MUSCAT instrument, and the exposure mode can be set to one of two values. The base instrument_config exposure_time will be overwritten with the longest of the 4 camera exposure_times. For more information on MUSCAT instrument and it’s parameters, go here.

Field	Read Only	Required	Options	Description
exposure_mode	false	false	SYNCHRONOUS, ASYNCHRONOUS	Exposure Mode. Default is SYNCHRONOUS.
exposure_time_g	false	true		Exposure time for the g-band camera in seconds.
exposure_time_r	false	true		Exposure time for the r-band camera in seconds.
exposure_time_i	false	true		Exposure time for the i-band camera in seconds.
exposure_time_z	false	true		Exposure time for the z-band camera in seconds.

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

Observation API Examples

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

View on Github

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

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.

Archive calls have a maximum limit parameter of 1000 to prevent slow queries. You can paginate through your result set using the offset field to retrieve more than the max limit.

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

Aggregate

requests.get('https://archive-api.lco.global/frames/aggregate/?SITEID=ogg&OBSTYPE=SKYFLAT&start=2019-09-01&end=2019-09-02').json()

$.getJSON('https://archive-api.lco.global/frames/aggregate/?SITEID=ogg&OBSTYPE=SKYFLAT&start=2019-09-01&end=2019-09-02')

Returns the response:

{
    "sites": [
        "ogg"
    ],
    "telescopes": [
        "0m4b",
        "0m4c",
        "2m0a"
    ],
    "filters": [
        "gp",
        "ip",
        "rp",
        "up",
        "V",
        "w",
        "Y"
    ],
    "instruments": [
        "fs02",
        "kb27",
        "kb82"
    ],
    "obstypes": [
        "SKYFLAT"
    ],
    "proposals": [
        "calibrate"
    ]
}

Returns the unique values shared across all fits files for site, telescope, instrument, filter, proposal, and obstype. Only proposals for which public data exists are included in the results.

HTTP Request

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

Query Parameters

All parameters are optional. If parameters are supplied, unique values are determined from frames filtered by those parameters.

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

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

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

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

Iterate over multiple pages of results

frame_collection = []

def fetch_frames(url, collection):
    response = requests.get(url).json()
    collection += response['results']
    if response.get('next'):
        fetch_frames(response['next'], collection)

fetch_frames('https://archive-api.lco.global/frames/?OBJECT=m42', frame_collection)
print(len(frame_collection))
... 1024 ...

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

Download 24 hours of data from a single proposal

proposal = 'FellowshipProposal'
response = requests.get(
  'https://archive-api.lco.global/frames/?start=2016-1-1&end=2016-1-2&PROPID=' + proposal,
  headers=headers
).json()

frames = response['results']
for frame in frames:
  with open(frame['filename'], 'wb') as f:
    f.write(requests.get(frame['url']).content)

Search by RA and Dec

response = requests.get(
  'https://archive-api.lco.global/frames/?covers=POINT(112.3 20.9)',
  headers=headers
).json()

frames = response['results']
for frame in frames:
  print(frame['filename'])
  ... "ogg2m001-fs02-20160202-0167-e10.fits", "ogg2m001-fs02-20160202-0166-e10.fits" ...

Download a frame’s related files

response = requests.get(
  'https://archive-api.lco.global/frames/39728/related/',
  headers=headers
).json()
frames = response['results']
for frame in frames:
  with open(frame['filename'], 'wb') as f:
    f.write(requests.get(frame['url']).content)

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.