API Usage


The API provides a mechanism to interact with the data stored in RealEarth. The web display can be configured using these keywords on the server side (using the JavaScript initialization object) or the the client side (as part of the URL).

Keywords

Key Description Format Values Default
animate Flag to specify Animation Boolean true,false  
animationmode Animation mode Mode type time,layer time
animationrock Flag to specify Animation rocking Boolean true,false  
animationspeed Animation speed Number 0-100 50
basemap Initial basemap to display Basemap ID bw,wb,filled,[Components],(Product ID)  
basemaps Basemaps to be made available (Basemap ID),... See basemap list  
bounds Initial lat/lon bounds of display South,West,North,East West negative  
center Latitude and longitude to display Latitude,Longitude West negative 38,-97
centerproduct Product to set center Product ID    
centervalue Value to set center ID value    
collection Initial collection to display Collection ID See collection list
databounds Lat/lon bounds of the data to load (shape data only) South,West,North,East West negative  
keyboard Flag to control keyboard interaction Boolean true,false -1
labels Label to use in display Label ID line,grid,[Components]  
legend Flag to set legend display Boolean true,false 1
logo Flag to specify logo overlay on large images Boolean true,false 1
preloaddata Flag to control preload of next frame Boolean true,false -1
products Products to display (Product ID),...  
selector Flag to enable/disable Product Selector Boolean true,false 1
time Anchor time for display and animation Y-M-D H:m[:s] Absolute time  
timeproduct Product to define animation times Product ID    
timerange Time range for animation Y-M-D h:m[:s],Y-M-D h:m[:s] Absolute time range  
timespan Time span relative to anchor for animation period #(dhmst)[,#(dhmst)] Relative time or time range 6t
timestep Time step for animation #(dhms) Relative time 1h
ui Flag to enable/disable the User Interface Boolean true,false 1
waitdata Flag to control wait for data before next frame Boolean true,false -1
zoom Initial zoom level of display Number 1-20 4

Formats and Values

A Product ID is the identifier for a given product. Times can be absolute or relative.
NOTE: Most API calls allow time to be specified using the time keyword with an arbitrary date and time. The preferred, more efficient way to specify time is to use the products keyword form [Product ID]_[YYYYMMDD]_[hhmmss], which requests the exact date and time given without the need to look up the nearest time for each individual request.
See below for examples.

Time Matching

Explanation

RealEarth uses most recent time matching. When metadata, imagery, or shapes are requested, data for the most recent time is returned, without going past the given time. Each product defines a valid time range for its own data, after which it is considered to be expired and will be ignored. Each animation step consults the API to determine which absolute time to show for each product layer.

Diagram

Metadata

Product Information
/api/products

Provides metadata about the given products

Reply Formats:
Parameters:
Optional:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/products?exclude=times
https://realearth.ssec.wisc.edu/api/products?products=SNOWDEPTH24
https://realearth.ssec.wisc.edu/api/products?search=global&timespan=-6h

Available Times
/api/times

Provides the complete list of available times

Reply Formats:
Parameters:
Examples:
https://realearth.ssec.wisc.edu/api/times?products=SNOWDEPTH24

Nearest Time
/api/time

Provides the nearest recent absolute product time

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/time?products=SNOWDEPTH24
https://realearth.ssec.wisc.edu/api/time?products=SNOWDEPTH24&time=2024-03-29+09:57

Latest Time
/api/latest

Provides the latest absolute product time

Reply Formats:
Parameters:
Examples:
https://realearth.ssec.wisc.edu/api/latest?products=SNOWDEPTH24

Geographic Extents
/api/extents

Provides the geographic extents

Reply Formats:
Parameters:
Optional Parameters:
Examples:
https://realearth.ssec.wisc.edu/api/extents?products=SNOWDEPTH24

Imagery

Individual Tiles
/api/image

Provides access to raster tiles

Reply Formats:
Parameters:
Optional Parameters:
Examples:
https://realearth.ssec.wisc.edu/api/image?products=SNOWDEPTH24&x=4&y=5&z=4
https://realearth.ssec.wisc.edu/api/image?products=SNOWDEPTH24_20240329_090000&x=4&y=5&z=4
https://realearth.ssec.wisc.edu/api/image?products=SNOWDEPTH24&time=2024-03-29+09:00:00&x=4&y=5&z=4

Arbitrary Bounds /api/image

Provides access to raster images with arbitrary bounds

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/image?products=SNOWDEPTH24&time=2024-03-29+09:57&center=38,-97&zoom=4&width=400&height=300
https://realearth.ssec.wisc.edu/api/image?products=SNOWDEPTH24&time=2024-03-29+09:57&bounds=25,-125,50,-65&width=400&height=300

Legend
/api/legend

Provides legend images

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/legend?products=SNOWDEPTH24

Shapes

Points, Lines, Polygons /api/shapes

Provides access to geometry from products defined by geo-located shapes

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/shapes?products=wi-counties
https://realearth.ssec.wisc.edu/api/shapes?products=wi-counties_20150701_120000
https://realearth.ssec.wisc.edu/api/shapes?products=wi-counties&time=2015-07-01+12:00:00

Data

Raw Data Values
/api/data

Provides raw data values

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/data?products=SNOWDEPTH24&lat=43&lon=-89

Formatted Data Values
/api/probe

Provides formatted data values

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
https://realearth.ssec.wisc.edu/api/probe?products=SNOWDEPTH24&lat=43&lon=-89