Screenshots

The screenshot APIs can be used to generate custom videos of up to three image datasource layers composited together. Solar feature/event markers pins, extended region polygons, associated text labels, and a size-of-earth scale indicator can optionally be overlayed onto a movie.

takeScreenshot

GET /v2/takeScreenshot/

Generate a custom screenshot.

You must specify values for either x1, y1, x2, and y2 or x0, y0, width and height.

By default, the response is a JSON object containing a unique screenshot identifier (id) that can be used to with the downloadScreenshot API endpoint.

Set the display parameter to true to directly return the screenshot as binary PNG image data in the response.

Please note that each request causes the server to generate a screenshot from scratch and is resource intensive. For performance reasons, you should cache the response if you simply intend to serve exactly the same screenshot to multiple users.

Request Parameters:

Parameter

Required

Type

Example

Description

date

Required

string

2014-01-01T23:59:59Z

Desired date/time of the image. ISO 8601 combined UTC date and time UTC format.

imageScale

Required

number

2.4204409

Image scale in arcseconds per pixel.

layers

Required

string

[3,1,100]
or
[3,1,100,2,60,1,2010-03-01T12:12:12.000Z]

Image datasource layer(s) to include in the screenshot.

events

Optional

string

[AR,HMI_HARP;SPoCA,1],[CH,all,1]

List feature/event types and FRMs to use to annoate the movie. Use the empty string to indicate that no feature/event annotations should be shown.

eventLabels

Required

boolean

false

Optionally annotate each event marker with a text label.

scale

Optional

boolean

false

Optionally overlay an image scale indicator.

scaleType

Optional

string

earth

Image scale indicator.

scaleX

Optional

number

-1000

Horizontal offset of the image scale indicator in arcseconds with respect to the center of the Sun.

scaleY

Optional

number

-500

Vertical offset of the image scale indicator in arcseconds with respect to the center of the Sun.

width

Optional

string

1920

Width of the field of view in pixels. (Used in conjunction width x0,`y0`, and height).

height

Optional

string

1200

Height of the field of view in pixels. (Used in conjunction width x0,`y0`, and width).

x0

Optional

string

0

The horizontal offset of the center of the field of view from the center of the Sun. Used in conjunction with y0, width, and height.

y0

Optional

string

0

The vertical offset of the center of the field of view from the center of the Sun. Used in conjunction with x0, width, and height.

x1

Optional

string

-5000

The horizontal offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with y1, x2, and y2.

y1

Optional

string

-5000

The vertical offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, x2, and y2.

x2

Optional

string

5000

The horizontal offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and y2.

y2

Optional

string

5000

The vertical offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and x2.

display

Optional

boolean

false

Set to true to directly output binary PNG image data. Default is false (which outputs a JSON object).

watermark

Optional

boolean

true

Optionally overlay a watermark consisting of a Helioviewer logo and the datasource abbreviation(s) and timestamp(s) displayed in the screenshot.

callback

Optional

string

Wrap the response object in a function call of your choosing.

Example: Take Screenshot (JSON)

JSON response to “takeScreenshot” API requests. Assumes that the display parameter was omitted or set to false.

Example Request:
https://api.helioviewer.org/v2/takeScreenshot/?date=2014-01-01T23:59:59Z&imageScale=2.4204409&layers=[SDO,AIA,AIA,335,1,100]&events=[AR,HMI_HARP;SPoCA,1],[CH,all,1]&eventsLabels=false&x0=0&y0=0&width=1920&height=1200
Example Response:
{
    "id": 3285980
}
Response Description

Parameter

Required

Type

Description

id

Required

string

Unique screenshot identifier (e.g. “3285980”)

Example: binary (PNG image data)

Set the display parameter to true to directly return binary PNG image data in the response.

Example Request:
https://api.helioviewer.org/v2/takeScreenshot/?imageScale=2.4204409&layers=[SDO,AIA,AIA,304,1,100]&events=&eventLabels=true&scale=true&scaleType=earth&scaleX=0&scaleY=0&date=2014-02-25T15:53:00.136Z&x1=-929.2475775696686&x2=106.70112763033143&y1=-970.7984919973343&y2=486.3069298026657&display=true&watermark=true&events=[CH,all,1]

downloadScreenshot

GET /v2/downloadScreenshot/

Download a custom screenshot (that was generated using the takeScreenshot API endpoint).

Request Parameters:

Parameter

Required

Type

Example

Description

id

Required

number

3240748

Unique screenshot identifier (provided by the response to a takeScreenshot request).

Example: binary (PNG image data)

Example Request:
https://api.helioviewer.org/v2/downloadScreenshot/?id=3240748