Tutorials, Links, and Other Helpful Information

Videos

File Formats

Our videos are primarily released in .mp4 and .webm. Both of these file formats are supported in all modern web browsers. If you're having issues viewing either of these, we'd recommend either downloading the videos and attempting to preview them with your media viewer of choice, or trying to view the page in a different browser.

Some of our older content is also available in .mpg and .dv. While these formats are not supported for web display, we have retroactively generated .webm copies of these visualizations, which should display without any issues. .mpg and .dv are generally still supported in desktop media viewer applications, and you may have luck downloading them.

Resolutions

In most cases, our newer visualizations are created in 4K (3840 x 2160) at either 30 or 60 frames per second. All of our newer visualizations, and most of our older visualizations, are also published in HD (1920 x 1080 or 1280 x 720; 30fps / 60fps). Some of our oldest work is also published in NTSC (720 x 480; 29.97fps).

Images

File Formats

Out images are primarily released in .jpg, .jpeg, or .png. These are pretty universally supported, so you should (hopefully) have no issue viewing any of these.

We also occasionally release some of our higher-resolution content in .tif, .tiff, or .exr. These files on the site are generally accompanied by more-compatible (albeit, lower-resolution) versions in more common formats. These are likely what your web browser displays on pages containing images with these file extensions.

.tif and .tiff files are commonly supported by desktop image viewers, but not web browsers (save for Safari on Apple devices). As a result, we'd recommend downloading them and previewing them in a desktop image viewer.

Likewise, .exr files are commonly supported by desktop image viewers, but not web browsers.

Resolutions

Much like our videos, the vast majority of our newer visualizations are published in 4K, with smaller resolutions being available through the "downloads" dropdown menu. All of our newer content, and most of our older content, is also published in HD.

Frames

In addition to making compiled versions of our videos available, we commonly include links to directories containing all of the individual frames that make up those visualizations. These directories can be found linked in the "downloads" menu, under the "frames" heading.

File Formats

Our frames are generally released in .exr, .tif, and .tiff. For more information about handling these file types, see the images section.

Downloading

Understandably, it is desirable to fetch more than one frame at a time. There are currently two recommended tools for downloading multiple frames from our site:

1. DownThemAll

(available for Firefox and Chromium-based (e.g. Google Chrome or Microsoft Edge) browsers.

For instructions on using this extension, see its website .

2. Using curl on the command line

If you do not already have curl installed on your system, download it here .
Basic command usage:

prompt> curl [options] url

• url - the url you want to download. You can specify a numeric sequence using a range of numbers between brackets (see the example below).
• [options] - a variety of option flags. We suggest using the options '-LO' which will follow links and will store your downloaded frames in the current directory as their original file names.

For example, suppose we wish to download a frame sequence from animation ID 3032 which is located at:

						https://svs.gsfc.nasa.gov/vis/a000000/a003000/a003032/frames/1024x512/
					

The frame files have the form cld_f.nnnn.png, where nnnn are the frame numbers ranging from 0060 to 0119. In the directory where you wish to place the frames, execute the following command:

prompt> curl -LO "https://sfc.nasa.gov/vis/a000000/a003000/a003032/frames/1024x512/cld_f.[0060-0119].png"

This command will download each specified file in the given sequence if it exists.

Search API

The search API allows for automatic querying of our search page .

The basic format for a search API call is:
https://svs.gsfc.nasa.gov/api/search/?{url parameters}

Filtering Results

Any GET request that is performed by the SVS search can be executed in our API by prepending /api to the beginning of the URL. Generally, we recommend performing a search through the search page, and then trying to perform it through the API. On the search page, there is a shortcut to the API with the current search parameters that can be found by clicking on the small file-with-brackets icon () to the right of the result count.

Limiting results

By default, the API will return 100 results at a time. You can reduce the number of stories returned by providing the limit parameter.

The maximum limit that can be specified is 2000. Specify limit=none or limit=all to view all of the results, though the maximum limit still applies.

Pagination

The API will return at most the number of stories specified in the limit parameter, which again defaults to 100. The total number of results will be given in the count field. To obtain subsequent "pages" of stories, provide the offset and limit parameters.

For convenience, this "next" URL will be given in the next field. next will be null if you are already viewing all of the results, or the last page of the results.

Similarly, there is a previous field which gives the URL for the previous page of results, if applicable.

Data Specification

As an example, consider the following request:
https://svs.gsfc.nasa.gov/search/?studio=SVS&made_for=EIC ( )

At the time this documentation was written, this request would return the following JSON data:

{
    "count": 19,
    "next": null,
    "previous": null,
    "results": [
		{
			"id": 5126,
			"url": "https://svs.gsfc.nasa.gov/5126/",
			"result_type": "Visualization",
			"release_date": "2023-07-07T00:00:00-04:00",
			"title": "NOAA Annual Greenhouse Gas Index",
			"description": "This visualization of the NOAA Annual Greenhouse Gas Index shows the relative warming contribution from various greenhouse gasses (1979-2022). The donut chart shows 2022 AGGI data. || The NOAA Annual Greenhouse Gas Index (AGGI) tracks the increasing amount of heat being added to the atmosphere by human-related greenhouse gas (GHG) emissions. It is based on the highest quality measurements of GHGs in the atmosphere from sites around the world. This visualization contains data from 1979-2022. The quantity plotted is the global radiative forcing, which is a measure of how much each component is warming the Earth. The 'other' category includes hydrofluorocarbons (HFCs), Chlorofluorocarbons (CFCs), and hydrochlorofluorocarbons (HCFCs). The donut chart shows the 2022 data. This visualization, aimed at showing the relative contributions of each gas, leaves off the scale and units. In 2022 the total radiative forcing was 3.4 Watts per meter squared. || ",
			"hits": 63
		},
		{
			"id": 5121,
			"url": "https://svs.gsfc.nasa.gov/5121/",
			"result_type": "Visualization",
			"release_date": "2023-06-30T00:00:00-04:00",
			"title": "ODIAC: a map of human made carbon dioxide emissions",
			"description": "ODIAC (Open-source Data Inventory for Anthropogenic CO2) map for December 2021. || The Open-source Data Inventory for Anthropogenic CO2 (A.K.A. ODIAC) is a global high-resolution (1x1km) emission data product for fossil fuel carbon dioxide (CO2) emission. ODIAC was originally designed and developed under the Greenhouse gas Observing SATellite (GOSAT) project at Japan’s National Institute for Environmental Studies (NIES). Since then, ODIAC has been maintained at the Universities Space Research Association (USRA) in collaboration with NASA, NIES and the Appalachian State University. ODIAC pioneered the combined use of space-based nighttime light data and individual power plant emission/location profiles to estimate the global spatial extent of fossil fuel CO2 emissions. ODIAC has been a key input data for NASA’s carbon modeling. ODIAC has been also widely used in the international science research community for a variety of applications across key policy relevant scales (global to local). || ",
			"hits": 146
		},
		.
		.
		.
	]
},
					

The response will always contain the following fields:

• count - The total number of results for the given query, regardless of which page or how many results are currently being shown.
• next - The URL that will display the next page of results, using the same limit as the current request. This field will be null if all of the results are being shown, or if the final page of results is being shown.
• previous - The URL that will display the previous page of results, using the same limit as the current request. This field will be null if all of the results are being shown, or if the first page of results is being shown.
• results - An array of results objects (see below).

Each individual result object contains the following fields:

• id - The ID of the page that this result represents.
• url - The URL that this result links to.
• result_type - The type of result that this is.
• release_date - The date and time that this result was released.
• title - The title of this result.
• description - A (brief) description of this result.
• hits - The total number of views that the page this result represents has gotten over the past 10 days. Note: this number is updated daily between 2:00am ~ 4:00am ET

Page API

The page API provides more detailed information on specific site pages. Whereas the search API's results provide a broad overview of a page, the page API provides the full breadth of information that the SVS has available for any given page. This allows for automatic querying of datasets, keywords, credit information, and many many more pieces of metadata about our visualizations.

Currently, the page API supports:

• Visualization pages (e.g https://svs.gsfc.nasa.gov/5101/ )
• Gallery pages (e.g https://svs.gsfc.nasa.gov/new/gallery/ )

The basic format for a page API call is:
https://svs.gsfc.nasa.gov/api/{page ID}/

The page ID for any given page can be found by looking for the "ID: XXXXX" box, located just underneath the page's title. For visualization pages, this can also be found in the URL. Additionally, there is a link to the API on relevant pages, available by clicking on the small file-with-brackets icon () located next to the "ID: XXXXX" box.

Data Specification

As an example, consider the following request:
https://svs.gsfc.nasa.gov/api/5101/ ( )

At the time this documentation was written, this request would return the following JSON data:

{
	"id": 5101,
	"url": "https://svs.gsfc.nasa.gov/5101/",
	"page_type": "Visualization",
	"title": "Sea Surface Temperature (SST) - Near Real Time",
	"description": "An equirectangular view of sea surface temperature (SST) data for the past two and half years, updated daily to include the latest available data. || This visualization shows Sea Surface Temperature (SST) data from the Jet Propulsion Laboratory (JPL) Multi-scale Ultra-high Resolution (MUR) Sea Surface Temperature Analysis.  This visualization is updated once a day to include the latest available data. || ",
	"release_date": "2023-05-08T00:00:00-04:00",
	"update_date": "2023-09-06T09:01:42.770455-04:00",
	"main_image": {
		"id": 855019,
		"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_mur_colobar_print.jpg",
		"filename": "sst_mur_colobar_print.jpg",
		"media_type": "Image",
		"alt_text": "Sea Surface Temperature color bar.  Color range is light blue - white - orange - red.  -10 to 40 degrees Celsius",
		"width": 1024,
		"height": 576,
		"pixels": 589824
	},
	"main_video": {
		"id": 855700,
		"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_30_sec_robinson_4096x2048_2x1_30p.mp4",
		"filename": "sst_30_sec_robinson_4096x2048_2x1_30p.mp4",
		"media_type": "Movie",
		"alt_text": "A view of sea surface temperature (SST) data for the past two and half years, updated daily to include the latest available data.  This version is a robinson projection. ",
		"width": 4096,
		"height": 2048,
		"pixels": 8388608,
		"audio_track": null,
		"captions": null
	},
	"progress": "Complete",
	"media_groups": [
		{
			"id": 312499,
			"url": "https://svs.gsfc.nasa.gov/5101#media_group_312499",
			"widget": "Video player",
			"title": "",
			"caption": "",
			"description": "An equirectangular view of sea surface temperature (SST) data for the past two and half years, updated daily to include the latest available data.  ",
			"items": [
				{
					"id": 206430,
					"item_type": "media",
					"extra_data": null,
					"title": null,
					"caption": null,
					"media": {
						"id": 855015,
						"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_mur_print.jpg",
						"filename": "sst_mur_print.jpg",
						"media_type": "Image",
						"alt_text": "An equirectangular view of sea surface temperature (SST) data for the past two and half years, updated daily to include the latest available data.  ",
						"width": 1024,
						"height": 512,
						"pixels": 524288
					}
				},
				{
					"id": 206431,
					"item_type": "media",
					"extra_data": null,
					"title": null,
					"caption": null,
					"media": {
						"id": 855014,
						"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_mur_searchweb.png",
						"filename": "sst_mur_searchweb.png",
						"media_type": "Image",
						"alt_text": "An equirectangular view of sea surface temperature (SST) data for the past two and half years, updated daily to include the latest available data.  ",
						"width": 320,
						"height": 180,
						"pixels": 57600
					}
				},
				.
				.
				.
			],
			"extra_data": {}
		},
		{
			"id": 312498,
			"url": "https://svs.gsfc.nasa.gov/5101#media_group_312498",
			"widget": "Basic text with HTML",
			"title": "",
			"caption": "",
			"description": "This visualization shows Sea Surface Temperature (SST) data from the Jet Propulsion Laboratory (JPL) Multi-scale Ultra-high Resolution (MUR) Sea Surface Temperature Analysis.  This visualization is updated once a day to include the latest available data.",
			"media": [],
			"extra_data": {}
		},
		{
			"id": 312500,
			"url": "https://svs.gsfc.nasa.gov/5101#media_group_312500",
			"widget": "Single image",
			"title": "",
			"caption": "",
			"description": "An equirectangular view of the most recent sea surface temperature (SST) data available (still image). ",
			"items": [
				{
					"id": 206435,
					"item_type": "media",
					"extra_data": null,
					"title": null,
					"caption": null,
					"instance": {
						"id": 856705,
						"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_mur_most_recent_print.jpg",
						"filename": "sst_mur_most_recent_print.jpg",
						"media_type": "Image",
						"alt_text": "An equirectangular view of the most recent sea surface temperature (SST) data available (still image). ",
						"width": 1024,
						"height": 512,
						"pixels": 524288
					}
				},
				{
					"id": 206434,
					"item_type": "media",
					"extra_data": null,
					"title": null,
					"caption": null,
					"instance": {
						"id": 856704,
						"url": "https://svs.gsfc.nasa.gov/vis/a000000/a005100/a005101/sst_mur_most_recent.exr",
						"filename": "sst_mur_most_recent.exr",
						"media_type": "Image",
						"alt_text": "An equirectangular view of the most recent sea surface temperature (SST) data available (still image). ",
						"width": 4096,
						"height": 2048,
						"pixels": 8388608
					}
				}
			],
			"extra_data": {}
		},
		.
		.
		.
	],
	"studio": "SVS",
	"funding_sources": [
		"ESE"
	],
	"credits": [
		{
			"role": "Visualizer",
			"people": [
				{
					"name": "Kel Elkins",
					"employer": "USRA"
				},
				{
					"name": "Greg Shirah",
					"employer": "NASA/GSFC"
				}
			]
		},
		{
			"role": "Technical support",
			"people": [
				{
					"name": "Laurence Schuler",
					"employer": "ADNET Systems, Inc."
				},
				{
					"name": "Ian Jones",
					"employer": "ADNET Systems, Inc."
				}
			]
		}
	],
	"missions": [],
	"series": [],
	"tapes": [],
	"papers": [],
	"datasets": [
		{
			"name": "Multi-scale Ultra-high Resolution (MUR) Sea Surface Temperature (SST) Analysis",
			"common_name": "MUR SST",
			"platform": null,
			"sensor": null,
			"type": "Analysis",
			"organization": "JPL PO DAAC",
			"description": null,
			"credit": null,
			"url": null,
			"date_range": null,
		}
	],
	"nasa_science_categories": [
		"Earth"
	],
	"keywords": [
		"Earth Information Center",
		"Earth Science",
		"Ocean",
		"Ocean Temperature",
		"Oceans",
		"Physical oceanography",
		"sea surface temperature"
	],
	"recommended_pages": [],
	"related": [
		{
			"id": 4809,
			"url": "https://svs.gsfc.nasa.gov/4809/",
			"page_type": "Visualization",
			"title": "Earth Day 2020: Sea Surface Temperature (SST) from January 2016 through March 2020",
			"description": "Sea Surface Temperature - composited version with all layers includedThis video is also available on our YouTube channel. || ",
			"release_date": "2020-04-21T00:00:00-04:00",
			"update_date": "2023-09-07T00:18:08.898152-04:00",
			"main_image": {
				"url": "https://svs.gsfc.nasa.gov/vis/a000000/a004800/a004809/sst_comp_layer.1300_print.jpg",
				"filename": "sst_comp_layer.1300_print.jpg",
				"media_type": "Image",
				"alt_text": "Sea Surface Temperature - composited version with all layers includedThis video is also available on our YouTube channel.",
				"width": 1024,
				"height": 576,
				"pixels": 589824
			}
		}
	],
	"sources": [],
	"products": [],
	"newer_versions": [],
	"older_versions": [],
	"alternate_versions": []
}
					

The response will always contain the following fields:

• id - The page ID of the requested item.
• url - The url that this page can be found at.
• page_type - What type of page this is.

This response will also contain extra fields that vary depending on the type of page requested.

Dial-A-Moon API

The Dial-A-Moon API is used to power the Dial-A-Moons (e.g. on #5048 ) across the SVS site. It also serves as a useful resource for getting astronomical information about the Moon for a given date.

If you have any questions specifically about the data returned by this API, please contact . For general API inquiries, please contact .

Note: the Dial-A-Moon API has a couple of specific restrictions:

• Data is only available in 1-hour increments, except during eclipses, where it switches to 1-minute increments.
• The earliest data available is January 1st, 2011, 00:00 UTC.
• The latest data available is December 31st, 23:00 UTC for the current year. We add in the next year of data when the yearly Moon Phase and Libration visualization comes out, which has historically happened in November.

The basic format for a Dial-A-Moon API call is:
https://svs.gsfc.nasa.gov/api/dialamoon/{UTC timestamp in YYYY-MM-DDTHH:MM}
Note: there is always a letter T in between the date and time, and it is not something that should be converted.

Data Specification

As an example, consider the following request:
https://svs.gsfc.nasa.gov/api/dialamoon/2023-07-12T15:37 ( )
Note: even though the time requested is 15:37 UTC, the API will always round that to the closest point it has data for. In this case, 15:37 becomes 16:00. This is also true during eclipses, where the increments switch to 1 minute instead of 1 hour.

{
    "image": {
        "url": "https://svs.gsfc.nasa.gov/vis/a000000/a005000/a005048/frames/730x730_1x1_30p/moon.4625.jpg",
        "filename": "frames/730x730_1x1_30p/moon.4625.jpg",
        "media_type": "Image",
        "alt_text": "An image of the moon, as it would appear on 2023-07-12 16:00:00+00:00. (Frame: 4625)",
        "width": 730,
        "height": 730,
        "pixels": 532900
    },
    "image_highres": {
        "url": "https://svs.gsfc.nasa.gov/vis/a000000/a005000/a005048/frames/5760x3240_16x9_30p/fancy/comp.4625.tif",
        "filename": "frames/5760x3240_16x9_30p/fancy/comp.4625.tif",
        "media_type": "Image",
        "alt_text": "An image of the moon, as it would appear on 2023-07-12 16:00:00+00:00. (Frame: 4625)",
        "width": 5760,
        "height": 3240,
        "pixels": 18662400
    },
    "su_image": {
        "url": "https://svs.gsfc.nasa.gov/vis/a000000/a005000/a005049/frames/730x730_1x1_30p/moon.4625.jpg",
        "filename": "frames/730x730_1x1_30p/moon.4625.jpg",
        "media_type": "Image",
        "alt_text": "An image of the moon, as it would appear on 2023-07-12 16:00:00+00:00. (Frame: 4625)",
        "width": 730,
        "height": 730,
        "pixels": 532900
    },
    "su_image_highres": {
        "url": "https://svs.gsfc.nasa.gov/vis/a000000/a005000/a005049/frames/5760x3240_16x9_30p/fancy/comp.4625.tif",
        "filename": "frames/5760x3240_16x9_30p/fancy/comp.4625.tif",
        "media_type": "Image",
        "alt_text": "An image of the moon, as it would appear on 2023-07-12 16:00:00+00:00. (Frame: 4625)",
        "width": 5760,
        "height": 3240,
        "pixels": 18662400
    },
    "time": "2023-07-12T16:00",
    "phase": 23.81,
    "obscuration": 0.0,
    "age": 24.474,
    "diameter": 1845.5,
    "distance": 388369.0,
    "j2000_ra": 3.2364,
    "j2000_dec": 19.875,
    "subsolar_lon": -115.103,
    "subsolar_lat": 1.525,
    "subearth_lon": 6.457,
    "subearth_lat": -2.417,
    "posangle": 346.15
}
					

The response will always contain the following fields:

• image - An image of the Moon at the requested timestamp. This follows the same format as the media items from the visualization page API.
• image_highres - A higher resolution image of the Moon (often annotated with some additional information) at the requested timestamp. This follows the same format as the media items from the visualization page API.
• su_image - The south-up version of image.
• su_image_highres - The south-up version of image_highres.
• time - The timestamp corresponding to the data fetched.
• phase - The illuminated percentage of the Moon, as seen from Earth. 0.00 represents a new moon and 100.00 represents a full moon.
• obscuration - The percentage of the Moon inside the Earth's umbra shadow.
  Note: this is only used during Eclipses, and is 0.0 during all other times.
• age - The age (in days) since the start of the current lunar cycle.
• diameter - The current diameter (in arcseconds) of the Moon, as it appears from Earth.
• distance - The distance of the Moon (in kilometers) from Earth.
• j2000_ra - The J2000 right ascension (in degrees) of the Moon at the requested timestamp.
• j2000_dec - The J2000 declination (in degrees) of the Moon at the requested timestamp.
• subsolar_lon, subsolar_lat - The longitude and latitude (in degrees) of the subsolar point on the Moon at the requested timestamp. This can be thought of as the point on the Moon where the Sun is directly overhead.
• subearth_lon, subearth_lat - Like the subsolar point, but for the Earth instead of the Sun. These angles define the libration in longitude and latitude (in degrees).
• posangle - The position angle of the north polar axis. This is the tilt of the Moon relative to its line of right ascension, or the north celestial pole, measured counterclockwise.

Media Group Items

Media group items do not have their own API, but are formatted the same across other APIs that use them. This section is intended to serve as a data specification for that common format.

All media group items contain the following parameters:

• id - The id number of this media group item.
• item_type - A string indicating the type of this media group item. item_type will always be one of the following:
  • media - A media item. For more information on media items, see the section on media items .
  • media_group - Another media group.
  • link - A link to another page.
  • details_page - A visualization page.
  • gallery_page - A gallery page.
• instance - A summary of the actual object this media group item points to.

media and link items contain the following extra fields:

• title - An optional title used when displaying this item.
• caption - An optional caption used when displaying this item.

link items also contain an additional extra field:

• target - The URL that this item points to.

Media Items

Media items do not have their own API, but are formatted the same across other APIs that use them. This section is intended to serve as a data specification for that common format.

• id - The id number of this media item.
• url - The url that this media item can be found at.
• filename - The filename of this media item.
• media_type - A string indicating the type of this media item. media_type will always be one of the following:
  • Image - An image file.
  • Movie - A video file.
  • Frames - A set of images that are individual frames from a particular video. Note: despite being treated as individual media items, Frames are actually groups of individual images.
  • Captions - A set of captions for a particular video.
  • Audio - An audio file.
  • Presentation - A presentation file (usually PowerPoint or .pdf).
  • File - A file that can't be categorized into one of the other media types.
• alt_text - Alt text for this media item.

Some items (e.g. images, movies, and frames) also contain the following extra information:

• width - The width of this item (in pixels).
• height - The height of this item (in pixels).
• pixels - The total number of pixels in this image (= width x height).