NAV
Python Javascript

Introduction

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

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

Welcome to the LCO Developer documentation!

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

A note about code formatting

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

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

May be shortened in the documentation to:

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

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

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

Deprecation Policy

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

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

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

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

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

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 Requests 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 Requests. A value > 1.0 will raise your priority and debit your Proposal’s ipp_time_available upon submission. If a Request does not complete, the time debited for that Request is returned. A value < 1.0 will lower your priority and credit your Proposal’s ipp_time_available up to your ipp_limit on the successful completion of a Request. For more information on IPP, 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,
   "configuration_repeats": 1,
   "optimization_type": "TIME",
   "extra_params": {}
}

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 Configurations.
windows false true A list of Windows in which this Request should be considered for observation.
optimization_type false false TIME, AIRMASS Optimization emphasis for the scheduler to use when scheduling this Request. Defaults to TIME which emphasizes scheduling earlier in its time window. AIRMASS emphasizes scheduling at optimal airmass, but will have a lower overall chance of the request being observed.
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.
configuration_repeats false false The number of times to repeat the set of configurations of this Request, for things like nodding back and forth between targets. Defaults to 1.
state true false PENDING, WINDOW_EXPIRED, COMPLETED, CANCELED The current state of this Request.
extra_params false false Extra Request parameters. When submitting a manually created mosaic pattern, which is a Request with multiple Configurations where each Configuration contains a Target defining one pointing in the mosaic, include "mosaic": "custom" in these extra_params. This will ensure that custom is propagated to the MOSAIC header in the resulting FITS files to indicate that the image is part of a manually created mosaic. For information on how to generate a pre-defined mosaic pattern, see here.

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": {...},
    "extra_params" : {...}
}

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": {...},
    "extra_params" : {...}
}

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 InstrumentConfigs should be repeated in a loop. Only applicable for REPEAT_* type Configurations.
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 Configurations.
constraints false true The observation Constraints placed on this Configuration.
target false true The Target to observe.
instrument_configs false true A list of InstrumentConfigs 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
extra_params false false Extra Configuration parameters.

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.

Observations on an Imager type instrument can have an offset in arcseconds applied for dithering. There is a convenience endpoint to generate a dither pattern given a Configuration and pattern parameters, but the offsets can also be specified manually. Offsets are specified as InstrumentConfig extra parameters with the offset_ra and offset_dec fields. There is a requirement that each offset must be within 40% of the FOV of the autoguider camera it is on, except of SOAR instruments, which allow offsets up to 1800 arcseconds.

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 InstrumentConfigs 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": {
        "narrowband_g_position": "in",
        "narrowband_r_position": "out",
        "narrowband_i_position": "out",
        "narrowband_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. Not that with the release of muscat4, the diffusers will no longer be available on muscat3. They are replaced with narrowband filters on each channel, specified in the same way that the diffusers were (in/out).

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,
    "max_lunar_phase": 1.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.
max_lunar_phase false false Maximum acceptable moon phase fraction from 0 (new moon) to 1.0 (full moon). Defaults to 1.0.

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, SATELLITE 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 Options Description
ra false true Right ascension in decimal degrees.
dec false true Declination in decimal degrees.
epoch false false In modified Julian days (MJD). Defaults to 2000.
proper_motion_ra true false Right ascension proper motion ±33 mas/year. Defaults to 0, max 20000.
proper_motion_dec true false Declination proper motion ±33 mas/year. Defaults to 0, max 20000.
parallax false false ±0.45 mas, max 2000. Defaults to 0.

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.

Satellite Targets

Field Read Only Required Options Description
altitude false true Altitude of this target
azimuth false true Azimuth of this target
diff_altitude_rate false true Differential altitude rate (arcsec/s)
diff_azimuth_rate false true Differential azimuth rate (arcsec/s)
diff_altitude_acceleration false true Differential altitude acceleration (arcsec/s^2)
diff_azimuth_acceleration false true Differential azimuth acceleration (arcsec/s^2)
diff_epoch false true Reference time for non-sidereal motion (MJD)

A sample satellite target returned via API

{
    "type": "SATELLITE",
    "name": "Shiny Space Junk",
    "altitude": 65.0,
    "azimuth": 0.0,
    "diff_altitude_rate": 0.633,
    "diff_azimuth_rate": -0.552,
    "diff_epoch": 0.0,
    "diff_altitude_acceleration": 0.0,
    "diff_azimuth_acceleration": 0.0
}

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

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

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 RequestGroups created after the given date.
created_before false Result includes RequestGroups created before the given date.
state false PENDING, CANCELED, COMPLETED, WINDOW_EXPIRED Result includes RequestGroups matching the given state.
name false Result includes RequestGroups with a name that contains or matches the given value.
user false Result includes RequestGroups submitted by users whose usernames contain the given value.
proposal false Result includes RequestGroups submitted under the specified proposal.
observation_type false NORMAL, RAPID_RESPONSE, TIME_CRITICAL Results include RequestGroups with the specified observation type.
ipp_value false Results include RequestGroups 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

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

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 Default Description

Expand Dither Pattern

requests.post(
    'https://observe.lco.global/api/configurations/dither/',
    json={
        'pattern': 'line',
        'num_points': 3,
        'point_spacing': 5,
        'configuration': {
            'type': 'EXPOSE',
            'instrument_type': '1M0-SCICAM-SINISTRO',
            'target': {
                'name': 'm33',
                'type': 'ICRS',
                'ra': 23.4621,
                'dec': 30.659942,
                'epoch': 2000
            },
            'constraints': {
                'max_airmass': 1.6,
                'min_lunar_distance': 30,
                'max_lunar_phase': 1.0
            },
            'acquisition_config': {},
            'guiding_config': {},
            'instrument_configs': [
                {
                    'exposure_time': 30,
                    'exposure_count': 1,
                    'optical_elements': {
                        'filter': 'v'
                    }
                }
            ]
        }
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/configurations/dither/',
    type: 'post',
    data: {
        'pattern': 'line',
        'num_points': 3,
        'point_spacing': 5,
        'configuration': {
            'type': 'EXPOSE',
            'instrument_type': '1M0-SCICAM-SINISTRO',
            'target': {
                'name': 'm33',
                'type': 'ICRS',
                'ra': 23.4621,
                'dec': 30.659942,
                'epoch': 2000
            },
            'constraints': {
                'max_airmass': 1.6,
                'min_lunar_distance': 30,
                'max_lunar_phase': 1.0
            },
            'acquisition_config': {},
            'guiding_config': {},
            'instrument_configs': [
                {
                    'exposure_time': 30,
                    'exposure_count': 1,
                    'optical_elements': {
                        'filter': 'v'
                    }
                }
            ]
        }
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the response:

{
    "acquisition_config": ...,
    "constraints": ...,
    "extra_params": {
        "dither_pattern": "line"
    },
    "guiding_config": ...,
    "instrument_configs": [{
        "exposure_count": 1,
        "exposure_time": 30.0,
        "extra_params": {
            "bin_x": 1,
            "bin_y": 1,
            "offset_dec": 0.0,
            "offset_ra": 0.0
        },
        "mode": "full_frame",
        "optical_elements": {
            "filter": "V"
        }
    },
    {
        "exposure_count": 1,
        "exposure_time": 30.0,
        "extra_params": {
            "bin_x": 1,
            "bin_y": 1,
            "offset_dec": 5.0,
            "offset_ra": 0.0
        },
        "mode": "full_frame",
        "optical_elements": {
            "filter": "V"
        }
    },
    {
        "exposure_count": 1,
        "exposure_time": 30.0,
        "extra_params": {
            "bin_x": 1,
            "bin_y": 1,
            "offset_dec": 10.0,
            "offset_ra": 0.0
        },
        "mode": "full_frame",
        "optical_elements": {
            "filter": "V"
        }
    }],
    "instrument_type": "1M0-SCICAM-SINISTRO",
    "target": ...,
    "type": "EXPOSE"
}

Authentication Required

Given a well formed Configuration containing one InstrumentConfig and dither expansion parameters, this endpoint returns a new Configuration with multiple InstrumentConfigs each with a different offset_ra and offset_dec value according to the dither expansion parameters.

HTTP Request

POST https://observe.lco.global/api/configurations/dither/

Query Parameters

Parameter Required Default Description
configuration true A well formed Configuration in JSON format containing a single InstrumentConfig.
pattern true The dither pattern you want to expand. Options are line, grid, or spiral. This value will be set as the dither_pattern field in the Configuration extra_params in the returned expanded Configuration, which will end up in the DITHER FITS header.
num_points false The number of points in the dither pattern. Required for line or spiral patterns.
point_spacing true The distance in arcseconds between each point in the dither pattern. For a grid pattern this refers to the distance between columns in the grid.
line_spacing false point_spacing For the grid pattern, this represents the spacing between rows in arcseconds. If it is not specified, it will default to the point_spacing.
orientation false 0.0 The angle to orient the pattern with, measured clockwise from North (y-axis). This only applies to the line and grid patterns.
num_rows false The number of rows in the grid dither pattern.
num_columns false The number of columns in the grid dither pattern.
center false false If true, the line or grid pattern are centered around the initial target position. If false (default), the initial target position is the initial position in the pattern.

Expand Mosaic Pattern

requests.post(
    'https://observe.lco.global/api/requests/mosaic/',
    json={
        'pattern':'line',
        'point_overlap_percent': '10',
        'num_points': 3,
        'request': {
            'acceptability_threshold': 90,
            'configurations': [
                {
                    'type': 'EXPOSE',
                    'instrument_type': '1M0-SCICAM-SINISTRO',
                    'instrument_configs': [
                        {
                            'exposure_count': 1,
                            'exposure_time': '10',
                            'mode': 'full_frame',
                            'extra_params': {},
                            'optical_elements': {
                                'filter':'b'
                            }
                        }
                    ],
                    'acquisition_config': {},
                    'guiding_config':{},
                    'target': {
                        'name': 'm33',
                        'type': 'ICRS',
                        'ra': 23.4621,
                        'dec': 30.659942,
                        'epoch': 2000
                    },
                    'constraints': {}
                }
            ],
            'windows': [
                {
                    'start': '2021-08-23 18:15:00',
                    'end': '2021-08-27 18:15:00'
                }
             ],
            'location': {
                'telescope_class': '1m0'
            }
        }
    }
).json()

$.ajax({
    url: 'https://observe.lco.global/api/requests/mosaic/',
    type: 'post',
    data: {
        'pattern':'line',
        'point_overlap_percent': '10',
        'num_points': 3,
        'request': {
            'acceptability_threshold': 90,
            'configurations': [
                {
                    'type': 'EXPOSE',
                    'instrument_type': '1M0-SCICAM-SINISTRO',
                    'instrument_configs': [
                        {
                            'exposure_count': 1,
                            'exposure_time': '10',
                            'mode': 'full_frame',
                            'extra_params': {},
                            'optical_elements': {
                                'filter':'b'
                            }
                        }
                    ],
                    'acquisition_config': {},
                    'guiding_config':{},
                    'target': {
                        'name': 'm33',
                        'type': 'ICRS',
                        'ra': 23.4621,
                        'dec': 30.659942,
                        'epoch': 2000
                    },
                    'constraints': {}
                }
            ],
            'windows': [
                {
                    'start': '2021-08-23 18:15:00',
                    'end': '2021-08-27 18:15:00'
                }
             ],
            'location': {
                'telescope_class': '1m0'
            }
        }
    },
    dataType: 'json',
    success: function(data){
      console.log(data);
    }
});

Returns the response:

{
    "location": ...,
    "configurations": [
        {
            "constraints": ...,
            "instrument_configs": [...],
            "acquisition_config": ...,
            "guiding_config": ...,
            "target": {
                ...
                "ra": 270.904,
                "dec": -24.387,
                ...
            },
            "instrument_type": "1M0-SCICAM-SINISTRO",
            "type": "EXPOSE"
        },
        {
            "constraints": ...,
            "instrument_configs": [...],
            "acquisition_config": ...,
            "guiding_config": ...,
            "target": {
                ...
                "ra": 270.904,
                "dec": -23.988664,
                ...
            },
            "instrument_type": "1M0-SCICAM-SINISTRO",
            "type": "EXPOSE"
        },
        {
            "constraints": ...,
            "instrument_configs": [...],
            "acquisition_config": ...,
            "guiding_config": ...,
            "target": {
                ...
                "ra": 270.904,
                "dec": -23.590328,
                ...
            },
            "instrument_type": "1M0-SCICAM-SINISTRO",
            "type": "EXPOSE"
        }
    ],
    "extra_params": {
        "mosaic_pattern": "line"
    },
    "windows": [ ... ],
    "acceptability_threshold": 90.0
}

Authentication Required

Given a well formed Request containing one Configuration and mosaic expansion parameters, this endpoint returns a new Request with multiple Configurations each with a different Target generated according the the mosaic expansion parameters. The pattern type used to generate the mosaic pattern is stored in the returned Request in the top level extra_params field. Expanding a mosaic only works for imager instruments on ICRS targets.

HTTP Request

POST https://observe.lco.global/api/requests/mosaic/

Query Parameters

Parameter Required Default Description
request true A well formed Request in JSON format containing a single Configuration.
pattern true The mosaic pattern you want to expand. Options are line or grid. This value will be set as the mosaic_pattern field in the Request extra_params in the returned expanded Request, which will end up in the MOSAIC FITS header.
point_overlap_percent false The percentage of overlap of the pointings in the pattern as a percentage of the field of view in declination. If not set, point_spacing must be set to determine distance between pointings. Either one of point_overlap_percent or point_spacing must be set for both the line and grid patterns. For the grid pattern, this refers to the overlap in rows.
line_overlap_percent false point_overlap_percent The percentage of overlap of the pointings in the pattern as a percentage of the field of view in right ascension when generating a grid pattern. Use this together with point_overlap_percent. If this field is not set but point_overlap_percent is, this field defaults to point_overlap_percent. This refers to the overlap in columns for the grid pattern.
num_points false The number of pointings in the mosaic pattern. Required for the line pattern.
point_spacing false Can be used instead of point_overlap_percent. The distance in arcseconds in declination between each pointing in the mosaic pattern. For a grid pattern, this refers to the spacing between rows.
line_spacing false point_spacing Can be used instead of line_overlap_percent when using point_spacing. For the grid pattern, this represents the spacing between pointings in arcseconds in right ascension, which is the distance between pointings in columns. If it is not specified, it will default to the point_spacing.
orientation false 0.0 The angle to orient the pattern with, measured East (clockwise) from North (y-axis). This applies to both the line and grid patterns.
num_rows false The number rows in the grid mosaic pattern, which are the number of pointings in the vertical / declination direction.
num_columns false The number of columns in the grid mosaic pattern, which are the number of pointings in the horizontal/ right ascension direction.
center false false If true, the line or grid pattern are centered around the initial target. If false (default), the generated pattern starts at the initial target.

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

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_types": ["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 UserRequests can currently be submitted with this Proposal.
title The title of the Proposal.
abstract The abstract of the Proposal.
tac_priority The priority of the Proposal as awarded by the TAC.
tac_rank The numerical ranking given to the Proposal by the TAC.
tag The group of which this Proposal is a part.

Authentication

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

Get all Proposals

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

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

Returns the response:


{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "LCOEPO1",
            "timeallocation_set": [
                {
                    "std_allocation": 15.0,
                    "std_time_used": 4.754,
                    "ipp_limit": 1.5,
                    "ipp_time_available": 0.75,
                    "rr_allocation": 0.0,
                    "rr_time_used": 0.0,
                    "tc_allocation": 0.0,
                    "tc_time_used": 0.0,
                    "instrument_types": ["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_types": ["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_types": ["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 Default Description
id false The id of the Semester.
semester_contains false Result is the a single Semester that contains the given date.
start false Get only Semesters that start on or after this date.
end false Get only Semesters that end on or before this date.

Get Single Semester

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

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

Returns the response:

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

Return a single Semester.

HTTP Request

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

Query Parameters

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

Telescope States

Get Telescope States

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

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

Returns the response:

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

Returns the states of telescopes in the LCO network. 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

A user can authenticate by using the same API token as the Observation Portal. See the Observation Portal Authentication instructions for more information. The token can also be obtained by logging into the Observation Portal’s web frontend and clicking on the profile link, or going to /api/profile and looking up the api_token in the response. This token should be included in the header of archive requests the same way as it is in the Observation Portal, i.e. by including Authorization: Token <token> in the header.

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",
    "reduction_level": 91,
    "observation_date": "2016-02-03T09:05:57.414000Z",
    "proposal_id": "FTPEPO2014A-003",
    "instrument_id": "fs02",
    "target_name": "P 2010 v1",
    "site_id": "ogg",
    "telescope_id": "2m0a",
    "exposure_time": "60.000",
    "primary_optical_element": "R",
    "public_date": "2016-02-03T09:05:57Z",
    "configuration_type": "EXPOSE",
    "observation_id": 54321,
    "request_id": 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
observation_date The UTC time at the start of exposure.
proposal_id The name of the proposal for which this frame was taken.
instrument_id The instrument that produced this frame.
target_name The name of the object given by the user as the target of the observation. This is not an exact match. It returns all frames with the given text included the OBJECT keyword in the header. (For example, target_name = M3 will return results for M3, M33, M31, etc.) Note this is not the same as searching by on sky position - this comes from the OBJECT header, which is free-form text which may or may not match the actual contents of the file.
target_name_exact The exact name of the object given by the user as the target of the observation. This will be an exact case-insensitive match to the OBJECT keyword in the header.
site_id The site that produced this frame.
telescope_id The telescope that produced this frame.
exposure_time The exposure time of the frame.
primary_optical_element The primary filter or optical element used to produce this frame.
public_date The date this frame become public.
configuration_type The type of exposure: EXPOSE, BIAS, SPECTRUM, CATALOG, etc.
observation_id The Observation ID of the frame
request_id The Request number of the frame
reduction_level 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/?site_id=ogg&configuration_type=SKYFLAT&start=2019-09-01T00:00:00&end=2019-09-02T00:00:00').json()

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

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
proposal_id string Unique values for frames which belong to this proposal
site_id string Unique values for frames produced at this site
telescope_id string Unique values for frames produced from this telescope
primary_optical_element string Unique values for frames produced using this primary filter or optical element
configuration_type string Unique values for frames which match this configuration type
instrument_id 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
dayobs date Frames taken exactly on this date for their DAY-OBS header
proposal_id string Frames which belong to this proposal
request_id integer Frames which belong to this Request
observation_id integer Frames which belong to this observation ID
site_id string Frames produced at this site
telescope_id string Frames produced from this telescope
primary_optical_element string Frames produced using this filter
configuration_type string Frames which match this configuration type
instrument_id string Frames taken with this instrument
target_name 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
reduction_level integer Frames at this reduction level
exposure_time integer Frames where the exposure time is greater than or equal to this value, in seconds
exclude_configuration_type string Frames whose configuration types are not in this set
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/?target_name=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-1T00:00:00&end=2016-1-2T00:00:00&proposal_id=' + 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(https://weather-api.lco.global'/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.
Python Javascript