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
animationmode Flag to specify Animation mode Animation mode 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 terrain,satellite,bluemarble,filled,(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 use to set center Product ID    
databounds Lat/lon bounds of the data to load (shape data only) South,West,North,East West negative  
labels Label to use in display Label ID lines,grid,google  
legend Flag to set legend display Legend type true,false,hidden 1
products Products to display (Product ID),...   globalir.50,nexrhres.80
selector Flag to specify the Product Selector type Selector type true,false,mini 1
time Anchor time for display and animation Y-M-D H:m[:s] Absolute time  
timeproduct Product to use to define animation times Product ID    
timerange Time range to use for animation Y-M-D h:m[:s],Y-M-D h:m[:s] Absolute time range  
timespan Time span relative to anchor to use for animation period #(dhmst)[,#(dhmst)] Relative time or time range 6t
timestep Time step to use for animation #(dhms) Relative time 1h
ui Flag to enable/disable the User Interface 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=globalir
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=globalir

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=globalir
https://realearth.ssec.wisc.edu/api/time?products=globalir&time=2018-08-14+20:57

Latest Time
/api/latest

Provides the latest absolute product time

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

Geographic Extents
/api/extents

Provides the geographic extents

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

Imagery

Individual Tiles
/api/image

Provides access to raster tiles

Reply Formats:
Parameters:
Optional Parameters:
Examples:
https://realearth.ssec.wisc.edu/api/image?products=globalir&x=4&y=5&z=4
https://realearth.ssec.wisc.edu/api/image?products=globalir_20180814_200000&x=4&y=5&z=4
https://realearth.ssec.wisc.edu/api/image?products=globalir&time=2018-08-14+20: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=globalir&time=2018-08-14+20:57&center=38,-97&zoom=4&width=400&height=300
https://realearth.ssec.wisc.edu/api/image?products=globalir&time=2018-08-14+20: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=globalir

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=FXUS
https://realearth.ssec.wisc.edu/api/shapes?products=FXUS_20180301_120000
https://realearth.ssec.wisc.edu/api/shapes?products=FXUS&time=2018-03-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=globalir&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=globalir&lat=43&lon=-89