Coastal Observing Research and Development Center

HFRADAR Maps API

Do you want HFRADAR vectors on your map app.? We thought you might, so we built an API that allows you to access and query our tile base on your own.

With the inclusion of just a script tag and the Google Maps API, you can add your own vector overlays. Keep reading to see how.

Updated for Google Maps v3

The API documentation on this page works for the new GMv3-compatible API. Methods have not changed, only the main object!

Migrating from GMv2 to GMv3?

The following highlights the "major" changes between versions.
  • The API url changed.
  • The object, RTVTileLayer, was renamed to RTVMapType
  • There is no longer a need to wrap the RTVTileLayer/RTVMapType object in an overlay. This means, no more calls to rtv.getTileLayerOverlay() to change state. This need was alleviated by Google's upgrade. use caution
  • There is no longer a need to bind the 'statechange' event with overlay.refresh.
  • When creating a new RTVMapType object, you must provide the map object as a parameter to the constructor.

The basics

First, you'll need a page, a map, and our API.

Google Maps API v2 Google Maps API v3 Description
Simple Demo v2 Simple Demo v3 Barebones map utilizing the API
Complete Demo v2 Complete Demo v3 A typical map that uses most of the map features.
Kitchen Sink v2 Kitchen Sink v3 A complete tour of the API
v2.0.6 Features v2 v2.0.6 Features v3 Demonstration of how to use getLatestTimestampAtLatLng
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title>Google Maps JavaScript API Example: Simple Map</title> <script src="http://maps.google.com/maps/api/js?sensor=false" type="text/javascript"></script> <script type="text/javascript" src="http://cordc.ucsd.edu/js/RTV/RTVMapType.js"></script> <script type="text/javascript"> /** * Initialize the Google map. */ function initialize() { /** * boiler-plate Google Maps code. */ var mapOptions = { center: new google.maps.LatLng(38.0, -98.0), zoom: 3, mapTypeId: google.maps.MapTypeId.ROADMAP }; var map = new google.maps.Map( document.getElementById("map_canvas"), mapOptions ); /** * Adding HFRADAR-derived surface currents to the map */ var rtv = new RTVMapType(map); map.overlayMapTypes.push(rtv); } </script> </head> <body onload="initialize()"> <div id="map_canvas" style="width: 500px; height: 300px;"></div> </body> </html>

Configuration

If you're looking for more than just 6km resolution averaged over 25 hours, than you probably won't be happy with the defaults for very long. Don't panic, we've added several options for you to get to your place of customized zen.

Setter methods
Method Return Description
setOpacity(float opacity) bool Assign the opacity/transparency of the overlay. 1=> completely opaque, 0=> completely transparent.
setColorRange(int lo, int hi) bool Assign the color scale range you wish to use. Default is 0-50 cm/s, but valid range is from 0-250 cm/s. lo < hi.
setColorScheme(int scheme) bool Assign the color scheme/palette to use. Valid input is 0..12. Default is 4. Try 'em all in the Kitchen Sink Demo.
setResolution(string res) bool Assign the resolution to display. Valid input is (500m|1km|2km|6km).
setAveraged(bool set=true) bool Assign state: show averaged currents
setHourly(bool set=true) bool Assign state: show hourly currents
setTimestamp(int timestamp) bool Assign state: show vectors valid at this timestamp.
 
New in v2.0.6
setLatestTimestampAtLatLng(GLatLng[,callback]) void This method returns data to a callback function. The current resolution and process (averaged|hourly) are used to identify availability. The callback function will accept 2 parameters: (int timestamp, object metadata). The metadata object will be either of the form {"error":_message_}, or {"lat":_lat_,"lng":_lng_,"distance":_arc_degrees_,"latest":_timestamp_}. This method alters the state of the displayed map and updates it with the latest available tile set nearest the provided GLatLng, within +/-1 degree lat and/or lon.
Getter methods
Method Return Description
getLatestTimestamp() int Returns the epoch timestamp of the most recent tile layer available for the current settings. You may need to subtract an hour from this if your sites have longer than average latency.
getVectorData(GLatLng latlng, function callback) bool Allows point-click identification of features. Pass a GLatLng object and a callback function, the callback will be executed when the feature query has completed. Parameter to the callback is a javascript object literal {"lat":value,"lng":value,"u":value,"v":value}. You can use this object to access the exact lat,lon nearest the point clicked, along with the surface current's U and V vector components (in cm/s).
getOpacity() float Return the opacity assigned for the RTV layer. Range: [0,1].
getColorScheme() int Returns the color scheme in use.
getColorbarUrl(width=220,height=45) string Returns a URL to a colorbar that represents the data range being displayed. The height includes 15 pixels of top and bottom padding to make room for the text labels, so for 45 pixels, only 15 pixels is actual color bar.
getPrefix() string Returns the tile letter prefix used by the tile layer.
getTimestamp() int Returns the epoch timestamp of the currently displayed layer.
 
New in v2.0.5
getStation(callsign) object A JavaScript object containing station attributes. Some attributes include: sta, net, staname, lat, lon, time, endtime, and mtime. time and endtime are epoch timestamps in seconds since 1970-01-01 UTC that represent range of time that this station was active and valid. mtime is another epoch indicating when the last radial file was received.
getStations() array An array of station callsigns. These callsigns can be used to get more information about a station.
getStationCount() int The number of active and reporting stations.
getNetwork(net) object A JavaScript object containing network attributes. `net` is the abbreviation used internally. Some attributes include: net, netname
getNetworks() array An array of network abbreviations. These abbreviations can be used to get more information about a network.
getNetworkCount() int The number of active and reporting networks.
getNetworkUpdateTime() int Returns an epoch timestamp (seconds since 1970-01-01 UTC) of the arrival time for the most recent radial file received by the national network.
 
New in v2.0.6
getLatestTimestampAtLatLng(GLatLng,callback) void Like setLatestTimestampAtLatLng, this method returns data to a callback function. The current resolution and process (averaged|hourly) are used to identify availability. The callback function will accept 2 parameters: (int timestamp, obj metadata). If you wish to simply set the time to this latest value, use setLatestTimestampAtLatLng for simplicity.
Events
Event Bound to Parameters Description
load RTVMapType timestamp Triggered when the RTVMapType is fully initialized. The timestamp is the most recently available layer for the current configuration. Station and network metadata are also available at this time.
statechange RTVMapType none Triggered whenever a setting is changed, requiring that the map be refreshed. This event needs to be listened for so that the tiles are updated whenever a setting is changed.
timechange RTVMapType timestamp This event is triggered by the setTimestamp method. If the time is changed, a listener might want to display the new time. This method allows for an event-based display listener, rather than setting the display whenever one sets the time.
latest_loaded RTVMapType none This event is triggered upon initialization when timestamp metadata is available.
network_loaded RTVMapType none This event is triggered upon initialization when station and network metadata are available.