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

The products API provides metadata about the given products:
http://realearth.ssec.wisc.edu/api/products

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

Nearest Time

The time API provides the nearest recent absolute product time:
http://realearth.ssec.wisc.edu/api/time

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
http://realearth.ssec.wisc.edu/api/time?products=globalir
http://realearth.ssec.wisc.edu/api/time?products=globalir&time=2017-11-24+02:09

JSON

Other

Imagery

Individual Tiles

The image API provides access to raster tiles:
http://realearth.ssec.wisc.edu/api/image

Reply Formats:
Parameters:
Optional Parameters:
Examples:
http://realearth.ssec.wisc.edu/api/image?products=globalir&x=4&y=5&z=4
http://realearth.ssec.wisc.edu/api/image?products=globalir_20171124_010000&x=4&y=5&z=4

Arbitrary Bounds

The image API provides access to raster images with arbitrary bounds:
http://realearth.ssec.wisc.edu/api/image

Reply Formats:
Parameters:
Optional Parameters:
Notes:
Examples:
http://realearth.ssec.wisc.edu/api/image?products=globalir&time=2017-11-24+02:09&center=38,-97&zoom=4&width=400&height=300
http://realearth.ssec.wisc.edu/api/image?products=globalir&time=2017-11-24+02:09&bounds=25,-125,50,-65&width=400&height=300

Shapes

Points, Lines, Polygons

Products defined by geo-located shapes can be rendered into raster images using the image API, or the shapes can be provided directly using the shapes API:
http://realearth.ssec.wisc.edu/api/shapes

Reply Formats:
Parameters:
Optional Parameters:
Examples:
http://realearth.ssec.wisc.edu/api/shapes?products=FXUS_20171127_000000
http://realearth.ssec.wisc.edu/api/shapes?products=FXUS&time=2017-11-27+00:00:00