Helioviewer Logo

API


  1. Overview
  2. Helioviewer.org URLs
  3. Screenshots
  4. JPEG 2000
  5. Movies
  6. Appendices
    1. Identifiers
    2. Variable Types
    3. Coordinates



Overview

In order to facilitate third-party application developers who wish to use content from and interact with Helioviewer.org, a number of APIs have been developed, offering access to a variety of components used by Helioviewer. The simplest API actions require only a single request and result in some resource being returned, e.g. a movie or JP2 image series, or some action being performed, e.g. loading a particular image into Helioviewer.org. Some API methods are more complex and involve multiple steps. For example, when creating a movie, the request is first queued using one request. Subsequent requests are then used to determine when the movie has been built, and then finally to download or play the movie.

The general structure of queries is as follows:

http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=methodName&param1=value1&param2=value2...

The base URL is the same for each of the API methods ( http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php). The "action" parameter is required for all requests and specifies the specific functionality to access. In addition, other parameters may also be required depending on the specific API being accessed. The one exception to this rule is for launching Helioviewer.org with custom settings which is accessed from http://www.helioviewer.org/index.php and does not require an "action" to be specified. Finally, the queries may be sent using either a GET or POST request. In both cases the result is a JSON object

Helioviewer.org URLs

By specifying URL parameters at the main Helioviewer.org page, it is possible to control what data is loaded into the page when the user follows a URL. This is useful for dynamically loading a specific view or observation into Helioviewer using a URL. Note that all parameters for URL generation are optional.

Usage:

http://helioviewer.ias.u-psud.fr/helioviewer/index.php?

Supported Parameters:

date ISO 8601 UTC Date Date and time to display
centerX Float Horizontal offset from the center of the Sun in arc-seconds.
centerY Float Vertical offset from the center of the Sun in arc-seconds.
imageScale Float Image scale in arc-seconds/pixel
imageLayers 2d List A comma-separated list of the image layers to be displayed. Each image layer should be of the form: [OBSERVATORY, INSTRUMENT, DETECTOR, MEASUREMENT, VISIBLE, OPACITY].
movieId String Identifier of Helioviewer.org movie to display when page is loaded.
output String Output format to use when displaying the page. Currently there are two accepted output formats: "web" and "embed". If no output method is specified the output will default to the standard web display.

Examples: http://helioviewer.ias.u-psud.fr/helioviewer/index.php?date=2011-06-01T00:00:00Z&imageScale=4.8408818&imageLayers=[SDO,AIA,AIA,171,1,100],[SOHO,LASCO,C2,white-light,1,100]

http://helioviewer.ias.u-psud.fr/helioviewer/index.php?movieId=tk115

Screenshots

The Screenshot API provides a way for users to create custom single-layer and composite images using Helioviewer.org. Depending on how you plan to use the screenshot, the process can be handled in either one or two steps. In the simplest case, takeScreenshot is called with "display=true" and an image is returned directly. Alternatively, when the display parameter is not set to true in the request an identifier is returned which can then be used by the downloadScreenshot method to display the image. This is useful when you want to provide a reusable link to the image you create.
  1. Creating a Screenshot

    Returns a single image containing all layers/image types requested. If an image is not available for the date requested the closest available image is returned. The region to be included in the screenshot may be specified using either the top-left and bottom-right coordinates in arc-seconds, or a center point in arc-seconds and a width and height in pixels. See the Coordinates Appendix for more infomration about working with coordinates in Helioviewer.org.


    Usage:

    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=takeScreenshot

    Supported Parameters:

    date ISO 8601 UTC Date Timestamp of the output image. The closest timestamp for each layer will be found if an exact match is not found.
    imageScale Float The zoom scale of the image. Default scales that can be used are 0.6, 1.2, 2.4, and so on, increasing or decreasing by a factor of 2. The full-res scale of an AIA image is 0.6.
    layers String A string of layer information in the following format:
    Each layer is comma-separated with these values: [sourceId,visible,opacity].
    If you do not know the sourceId, you can alternately send this layer string: [obs,inst,det,meas,opacity]. Layer strings are separated by commas: [layer1],[layer2],[layer3].
    y1 Float [Optional] The offset of the image's top boundary from the center of the sun, in arcseconds.
    x1 Float [Optional] The offset of the image's left boundary from the center of the sun, in arcseconds.
    y2 Float [Optional] The offset of the image's bottom boundary from the center of the sun, in arcseconds.
    x2 Float [Optional] The offset of the image's right boundary from the center of the sun, in arcseconds.
    x0 Float [Optional] The horizontal offset from the center of the Sun.
    y0 Float [Optional] The vertical offset from the center of the Sun.
    width Integer [Optional] Width of the screenshot in pixels (Maximum: 3840).
    height Integer [Optional] Height of the screenshot in pixels (Maximum: 2400).
    display Boolean [Optional] If display is true, the screenshot will display on the page when it is ready. If display is false, the filepath to the screenshot will be returned. If display is not specified, it will default to true (Default=false).
    watermark Boolean [Optional] Whether or not the include the timestamps and the Helioviewer.org logo in the screenshot (Default=true).

    Examples: http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=takeScreenshot&date=2011-03-01T12:12:12Z&imageScale=10.52&layers=[3,1,100],[4,1,100]&x1=-5000&y1=-5000&x2=5000&y2=5000&display=true
    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=takeScreenshot&date=2011-03-01T12:12:12Z&imageScale=10.52&layers=[SOHO,EIT,EIT,171,1,100],[SOHO,LASCO,C2,white-light,1,100]&x1=-5000&y1=-5000&x2=5000&y2=5000
    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=takeScreenshot&date=2011-06-07T09:00:00Z&imageScale=2.4204409&layers=[SDO,AIA,AIA,304,1,100]&x0=0&y0=0&width=1024&height=1024&display=true

  2. Retrieving an Existing Screenshot

    Displays the screenshot associated with the specified id.


    Usage:

    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=downloadScreenshot

    Supported Parameters:

    id Integer The screenshot id as returned from takeScreenshot.

    Example: http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=downloadScreenshot&id=181

JPEG 2000 API:

Helioviewer's JPEG 2000 API's enable access to the raw JPEG 2000 images used to generate the tiles seen on the site, as well as real-time generation of JPEG 2000 Image Series (JPX).

  1. JP2 Images:

    Returns a single JPEG 2000 (JP2) image. If an image is not available for the date request the closest available image is returned.


    Usage:

    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJP2Image

    Supported Parameters:

    observatory String Observatory
    instrument String Instrument
    detector String Detector
    measurement String Measurement
    date ISO 8601 UTC Date Observation date and time
    sourceId Integer [Optional] The image source ID (can be used in place of observatory, instrument, detector and measurement parameters).
    jpip Boolean [Optional] Returns a JPIP URI instead of an actual image.

    Examples: http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJP2Image&observatory=SOHO&instrument=EIT&detector=EIT&measurement=171&date=2003-10-05T00:00:00Z
    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJP2Image&observatory=SOHO&instrument=LASCO&detector=C2&measurement=white-light&date=2003-10-05T00:00:00Z&jpip=true

  2. JPX API

    Returns a JPEG 2000 Image Series (JPX) file. The movie frames are chosen by matching the closest image available at each step within the specified range of dates.


    Usage:

    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJPX

    Supported Parameters:

    observatory String Observatory
    instrument String Instrument
    detector String Detector
    measurement String Measurement
    startTime ISO 8601 UTC Date Movie start time
    endTime ISO 8601 UTC Date Movie end time
    cadence Integer [Optional] The desired amount of time between each movie-frame, in seconds. If no cadence is specified, the server will attempt to select an optimal cadence.
    sourceId Integer [Optional] The image source ID (can be used in place of observatory, instrument, detector and measurement parameters).
    verbose Boolean [Optional] In addition to the JPX file URI, timestamps for each frame in the resulting movie and any warning messages generated are included in a JSON response.
    jpip Boolean [Optional] Returns a JPIP URI instead of an actual movie.
    linked Boolean [Optional] Returns a linked JPX file containing image pointers instead of data for each individual frame in the series. Currently, only JPX image series support this feature.

    Result:

    The default action is to simply return the requested JPX file. If additional information is needed, for example, then a JSON result will be returned with the file URI plus any additional parameters requested.

    uri String [Optional] Location of the requested file.
    frames List [Optional] List of timestamps.
    error String [Optional] Any fatal error messages generated during the request
    warning String [Optional] Any non-fatal warning messages generated during the request

    Examples: http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJPX&observatory=SOHO&instrument=EIT&detector=EIT&measurement=171&startTime=2003-10-05T00:00:00Z&endTime=2003-10-20T00:00:00Z
    http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=getJPX&observatory=SOHO&instrument=MDI&detector=MDI&measurement=magnetogram&startTime=2003-10-05T00:00:00Z&endTime=2003-10-20T00:00:00Z&cadence=3600&linked=true&jpip=true

    Notes:

    • If no cadence is specified Helioviewer.org attempts to choose an optimal cadence for the requested range and data source.


    Movies:

    The movie API allows users to create time-lapse videos of what they are viewing on the website. There are two steps involved in Helioviewer.org movie requests: 1) queueing the movie, and 2) retrieving the movie once it has been processed.

    1. Queueing a Movie

      Because of the high-demands of creating movies on the fly, requests for movies from Helioviewer.org must be added to a queue before being processed. Only when all of the movies ahead of the requested one have been processed will the request be handled and the movie generated.

      Upon queueing a movie, some basic information about the movie request will be returned including an identifier to reference that movie in the future and an estimated time until the movie has been processsed. This information can be used to check on the movie status using the getMovieStatus API call, and then eventually to either download or play the movie once it is ready.

      Movies may contain between 10 and 300 frames. The movie frames are chosen by matching the closest image available at each step within the specified range of dates, and are automatically generated using the Screenshot API calls. The region to be included in the movie may be specified using either the top-left and bottom-right coordinates in arc-seconds, or a center point in arc-seconds and a width and height in pixels. See the Coordinates Appendix for more infomration about working with coordinates in Helioviewer.org.


      Usage:

      http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=queueMovie

      Supported Parameters:

      startTime ISO 8601 UTC Date Desired starting timestamp of the movie. The timestamps for the subsequent frames are incremented by a certain timestep.
      endTime ISO 8601 UTC Date Desired ending timestamp of the movie. Time step and number of frames will be figured out from the range between startTime and endTime.
      imageScale Float The zoom scale of the images. Default scales that can be used are 0.6, 1.2, 2.4, and so on, increasing or decreasing by a factor of 2. The full-res scale of an AIA image is 0.6.
      layers String A string of layer information in the following format:
      Each layer is comma-separated with these values: [sourceId,visible,opacity].
      If you do not know the sourceId, you can alternately send this layer string: [obs,inst,det,meas,opacity]. Layer strings are separated by commas: [layer1],[layer2],[layer3].
      y1 Float [Optional] The offset of the image's top boundary from the center of the sun, in arcseconds.
      x1 Float [Optional] The offset of the image's left boundary from the center of the sun, in arcseconds.
      y2 Float [Optional] The offset of the image's bottom boundary from the center of the sun, in arcseconds.
      x2 Float [Optional] The offset of the image's right boundary from the center of the sun, in arcseconds.
      x0 Float [Optional] The horizontal offset from the center of the Sun.
      y0 Float [Optional] The vertical offset from the center of the Sun.
      width Integer [Optional] Width of the movie in pixels (Maximum: 3840).
      height Integer [Optional] Height of the movie in pixels (Maximum: 2400).
      numFrames Integer [Optional]The maximum number of frames that will be used during movie creation. You may have between 10 and 300 frames. The default value is 300.
      frameRate Float [Optional]The number of frames per second. The default value is 15.
      movieLength Float [Optional]The length in seconds of the video to be produced.
      watermark Boolean [Optional] Enables turning watermarking on or off. If watermark is set to false, the images will not be watermarked, which will speed up movie generation time but you will have no timestamps on the movie. If left blank, it defaults to true and images will be watermarked.
      display Boolean [Optional] If display is true, the movie will display on the page when it is ready. If display is false, the filepath to the movie's flash-format file will be returned as JSON. If display is not specified, it will default to true.

      Result:

      The result includes an identifier for the movie request and an estimated time before the movie is ready to be downloaded.

      id String Movie identifier
      eta Integer The estimated time in seconds until the movie has been processed.

      Examples: http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=queueMovie&startTime=2010-03-01T12:12:12Z&endTime=2010-03-04T12:12:12Z&imageScale=21.04&layers=[3,1,100],[4,1,100]&x1=-5000&y1=-5000&x2=5000&y2=5000
      http://helioviewer.ias.u-psud.fr/helioviewer/api/index.php?action=queueMovie&startTime=2010-03-01T12:12:12Z&endTime=2010-03-04T12:12:12Z&imageScale=21.04&layers=[SOHO,EIT,EIT,304,1,100],[SOHO,LASCO,C2,white-light,1,100]&x1=-5000&y1=-5000&x2=5000&y2=5000


    Appendices:

    1. Supported Identifiers

      This appendice contains a list of the identifiers supported by Helioviewer. For some queries, complex identifiers may be built up from the simpler ones below. For example, to uniquely identify a specific type of image, you must specify a comma-separated set of four identifiers: Observatory, Instrument, Detector, and Measurement. For example, to refer to an EIT 171 image, the identifier SOHO,EIT,EIT,171 is used.

      Observatories:

      Identifier: Description:
      SDO SDO (Solar Dynamics Observatory)
      SOHO SOHO (Solar and Heliospheric Observatory)
      STEREO_A STEREO_A (Solar Terrestrial Relations Observatory Ahead)
      STEREO_B STEREO_B (Solar Terrestrial Relations Observatory Behind)
      Yohkoh Yohkoh (SOLAR-A)

      Instruments:

      Identifier: Description:
      AIA AIA (Atmospheric Imaging Assembly)
      EIT EIT (Extreme ultraviolet Imaging Telescope)
      HMI HMI (Helioseismic and Magnetic Imager)
      LASCO LASCO (Large Angle and Spectrometric Coronagraph Experiment)
      MDI MDI (The Michelson Doppler Imager)
      SECCHI SECCHI (Sun Earth Connection Coronal and Heliospheric Investigation)
      SXT SXT (Soft X-ray Telescope)

      Detectors:

      Identifier: Description:
      AIA AIA (Atmospheric Imaging Assembly)
      C2 LASCO C2
      C3 LASCO C3
      COR1 Coronagraph 1
      COR2 Coronagraph 2
      EIT EIT (Extreme ultraviolet Imaging Telescope)
      EUVI EUVI (Extreme ultraviolet Imager)
      HMI HMI (Helioseismic and Magnetic Imager)
      MDI MDI (The Michelson Doppler Imager)
      SXT SXT (Soft X-ray Telescope)

      Measurements:

      Identifier: Description:
      94 94 Ångström
      131 131 Ångström
      171 171 Ångström
      193 193 Ångström
      195 195 Ångström
      211 211 Ångström
      284 284 Ångström
      304 304 Ångström
      335 335 Ångström
      1600 1600 Ångström
      1700 1700 Ångström
      4500 4500 Ångström
      white-light White-light
      continuum Intensity spectrogram
      magnetogram Magnetogram
      AlMgMn Al/Mg/Mn filter (2.4 Å - 32 Å pass band)
      thin-Al 11.6 μm Al filter (2.4 Å - 13 Å pass band)


    2. Variable Types

      This appendice contains a list of some of the variable types used by the Helioviewer API's.


      Type: Description: Example:
      Boolean A boolean value. true
      Integer An integer. 12
      Float A floating point number. 2.4
      String A string. SOHO
      List A comma-separated list of some other type, usually strings or integers item1, item2
      2d List This is similar to a list except that each item of the list is a bracket-delineated list itself. [SOHO,EIT,EIT,171,1,100], [SOHO,LASCO,C2,white-light,0,100], [SOHO,MDI,MDI,continuum,1,50]
      ISO 8601 UTC Date ISO 8601 is a widely supported standarized date format. (See [1], [2]) 2003-10-05T00:00:00.000Z // Milliseconds are optional but trailing "Z" should always included.



    3. Working with Coordinates in Helioviewer.org

      Overview

      Several of the API methods supported by Helioviewer.org require you to specify a rectangular region of interest or "ROI", which is simply the portion of the image or movie you are interested in.

      There are two different methods for specifying region of interest (ROI) in Helioivewer.org API requests. The first method is to specify the coordinates for the top-left and bottom-right corners of the ROI in arcseconds. The other option is to specify the position of the center of your ROI in arcseconds and the dimensions for the ROI in pixels. In either case you will also need to specify an image scale in arcseconds per pixel. This appendix provides a description of how each of these methods can be used in API requests, and how to determine the appropriate arcsecond values to use to reach a desired effect.

      Arcseconds

      The first method for specifying an ROI in a Helioviewer.org API request is to specify the coordinates for the top-left (x1, y1) and bottom-right (x2, y2) corners of the ROI in arcseconds, with the origin at the center of the Sun. The below image depicts the location of the origin, and the direction of the axes, for this style request.

      To makes things more clear, below are some example requests, and the imageScale and ROI corresponding with that request.


      Examples:

      1) A complete AIA image at 1/16 its natural resolution (zoomed out four times)

      In this case the desired image scale is 2^4 x (natural scale) = 16 x 0.6 = 9.6. Now to determine the ROI coordinates, we must first determine how large the image will be at the specified scale. AIA is normally 4096x4096, so at 1/16 its natural resolution it will be 256x256 pixels. Since the origin is in the middle of the Sun (which here is in the middle of the Sun), the top-left corner is 128 pixels up and to the left (-128, -128), and the bottom-right corner is 128 pixels down and to the right (128, 128). Since the ROI must be specified in arcseconds, and not in pixels, we multiply by the desired imageScale: 128 x 9.6 = 1228.8.

      URL:http://helioviewer.org/api/?action=takeScreenshot&date=2011-06-21T00:00:00.000Z&layers=[SDO,AIA,AIA,304,1,100]&imageScale=9.6&x1=-1228.8&y1=-1228.8&x2=1228.8&y2=1228.8&display=true

      2) The top-right quadrant of an EIT image at 200% magnification

      First, determine the desired image scale = 1 / 2^1 x (EIT native image scale) = 1/2 x 2.63 = 1.315. At this scale, the image which would normally be 1024x1024 pixels is now 2048x2048 pixels, and the coordinates for the ROI in pixels would is (0,-1024), (1024,0). To convert to arcseconds we multiple the pixel values by the arcsecond/ pixel ratio (the imageScale) to get (0, -1346.56), (1346.56, 0).

      URL:http://helioviewer.org/api/?action=takeScreenshot&date=2011-06-21T00:00:00.000Z&layers=[SOHO,EIT,EIT,171,1,100]&imageScale=1.315&x1=0&y1=-1346.56&x2=1346.56&y2=0&display=true

      Finally, don't forget that you can use Helioviewer.org to check the coordinates and see if they are as you expect. Pressing the "m" key will return the position of the mouse pointer in Helioviewer.org viewport. Initially, the coordinates will be displayed in arcseconds. Note, however, that the y-axis value displayed for mouse-coordinates has the opposite sign to that passed in API requests. This is because the mouse position is returned in a coordinate system which is commonly used in solar physics. To get around this you can simply flip the sign for the y-coordinate you see on Helioviewer.org when mouse-coordinates are being displayed.

      Pixels

      Alternatively, if you prefer to explicityly specify the pixel dimensions for the image or movie, you can specify the center of your ROI in arc-seconds (x0, y0), relative to the center of the sun, and the width and height of the ROI in pixels. Although you are still required to work with Arcseconds for this method for some of the parameters, this provides a simple way to ensure that the resulting image or movie is a specific size in pixels.

      Similar to the first method, you will also need to specify the image scale to use, in arcseconds/pixel.


      Examples:

      1) A complete EIT image at it's natural resolution

      According to the table of image scales shown below, the native image scale for EIT is 2.63 arcseconds/pixel, and the image dimensions are 1024 x 1024 pixels.



      URL:http://helioviewer.org/api/?action=takeScreenshot&date=2011-07-07T00:00:00.000Z&layers=[SOHO,EIT,EIT,171,1,100]&imageScale=2.63&x0=0&y0=0&width=1024&height=1024&display=true

      2) A 1024 x 768 sub-region centered at the top-right corner of an AIA 131 image, centered at the top-right quadrant, and the natural scale of AIA.

      Since we want to center the image in the top-right corner, we need to figure out what arcsecond coordinates correspond to the pixel coordinates (1024, -1024). At its native resolution, AIA images have an image scale of 0.6 arcseconds/pixel, so we multiple the pixel coordinates by this ratio to get the corresponding arcsecond values.



      URL:http://helioviewer.org/api/?action=takeScreenshot&date=2011-07-07T00:00:00.000Z&layers=[SDO,AIA,AIA,131,1,100]&imageScale=0.6&x0=614.4&y0=-614.4&width=1024&height=768&display=true

      Image Scale

      When working with coordinates in Helioviewer.org, it is also important to understand the spatial scale of the images you are viewing and requesting. Each type of image (AIA, LASCO, etc) shows the Sun at some spatial scale or resolution. That is, each image pixel represents a certain number of arcseconds, and that ratio of arcseconds to pixels is refered to as the "image scale" for that image. Each of the different image types have their own native image scale, which is the number of arcseconds a pixel of the image represents when viewed at its native resolution. Below is a table listing the average native image scales and dimensions (in pixels) for images found on Helioviewer:


      Image Type: Dimensions (pixels) Image Scale (arcseconds/pixel)
      AIA 4096 x 4096 0.6
      COR-1 512 x 512 15.0
      COR-2 2048 x 2048 14.7
      EIT 1024 x 1024 2.63
      HMI 4096 x 4096 0.6
      LASCO C2 1024 x 1024 11.9
      LASCO C3 1024 x 1024 56
      MDI 1024 x 1024 1.985707
      Yohkoh SXT (Full) 1024 x 1024 2.46
      Yohkoh SXT (Half) 512 x 512 4.92
      Yohkoh SXT (Qrtr) 256 x 256 9.84

      Note: The values listed above are average values. Often, the image scale and dimensions for a given type of image tends to stay the same over time, and as such you can often use the above values as-is. Occasionally, however, the scale or dimensions will vary. If you find that you are getting unexpected results, or would like a higher level of precision, you should first use the getClosestImage method to determine the exact dimensions and scale for the image you are requesting.

      The smaller the (native) image scale is, the more detail you can see. For example, AIA has a much smaller native image scale ( 0.6"/px) than EIT does (2.63"/px) which is why you can see a lot more detail in AIA images.

      You are not limited to creating screenshots and movies at an image's native resolution, however, and so in an API request the imageScale specified need not (and in the case of composite images, often cannot) be the same as an images native resolution.

      For example, suppose you wanted to request an AIA image that is "zoomed out" by a factor of two. In this case, you would double the imageScale, so instead of 0.6, you would request an image scale of 1.2. Simiarly, when making a request which includes multiple layers, each of the layers will be scaled to match the imageScale you requested.

Last Updated: 2012-02-22 | Questions?