<?php 
require_once "../../config/settings.inc.php";
require_once "../../include/myview.php";
$t = new MyView();
$t->title = "RadMap API";
$t->content = <<<EOM
<style>
div.item h4 {
 color: #f00;
 border-bottom: 1px solid #ccc;
 margin-bottom: 1px;
}
div.desc {
 margin-left: 20px;
}
</style>


<h3>IEM RadMap API</h3>

<div class="alert alert-danger">Please note: This mapping service is
provided without warranty.  Please do not use this on a high traffic website.
If necessary, this application may be disabled to keep the IEM web farm from
melting!  This API is intended to support local scripts to generate timelapse
movies.
</div>

<p>The "radmap" application dynamically generates a PNG image based on a set
of HTTP provided parameters.  This page documents these parameters. Please note
that the API presented here may change in the future.

<h3>Basic HTML example:</h3>
<pre>
&lt;img src="{$EXTERNAL_BASEURL}/GIS/radmap.php?layers[]=nexrad&amp;sector=conus&amp;ts=200806071000" /&gt;
</pre>
<img src="/GIS/radmap.php?layers[]=nexrad&sector=conus&ts=200806071000" 
width="640" height="480" alt="radmap image"/>

<h3>HTTP GET Parameters</h3>
<div class="item">
 <h4>&amp;layers[]=...&amp;layers[]=...&amp;...</h4>
<div class="desc">
 Layer(s) to draw in the map. Here is a list of available layers:
<ul>
    <li><i>airtemps</i> - <strong>Realtime Only</strong> Plot 2 meter air 
        temperatures in Fahrenheit.</li>
 <li><i>cbw</i> - County/Zone based Watch/Warning/Advisories</li>
 <li><i>county_warnings</i> - County based Warnings</li>
 <li><i>cwas</i> - National Weather Service County Warning Area (CWA)</li>
 <li><i>goes</i> - <a href="goes.phtml">GOES Satellite</a> imagery, you
 also need to specify the product as a seperate 
 CGI variable. <sup>[2]</sup>
 <ul>
     <li><i>goes_product</i> VIS for visible, IR for infrared, and WV for water
     vapor</li>
 </ul>
 </li>
 <li><i>interstates</i> - Interstate Roadways</li>
 <li><i>legend</i> - Include Legend on the Map</li>
 <li><i>lsrs</i> - Local Storm Reports <sup>[1]</sup></li>
 <li><i>nexrad</i> - CONUS Nexrad Base Reflectivity Composite <sup>[2]</sup></li>
 <li><i>places</i> - 2010 Census Incorporated Places </li>
 <li><i>ridge</i> - Single Site <a href="ridge.phtml">NEXRAD/TDWR</a> imagery, you
 also need to specify the RADAR site and level 3 product as two seperate 
 CGI variables. <sup>[2]</sup>
 <ul>
     <li><i>ridge_radar</i> 3 character radar identifier</li>
     <li><i>ridge_product</i> 3 character levelIII product identifier</li>
 </ul>
 </li>
 <li><i>roads</i> - Iowa Winter Road Conditions</li>
 <li><i>sbw</i> - Storm based Watch/Warning/Advisories</li>
    <li><i>surface</i> - <strong>Realtime Only</strong> Plot dots for RWIS
    pavement temperatures. See <a href="/GIS/apps/iem/freeze.phtml">IEM Freeze</a> app.</li>
  <li><i>uscounties</i> - CONUS Counties </li>
 <li><i>usdm</i> - United States Drought Monitor (latest only)</li>
 <li><i>watch_by_county</i> - Convective Watch-by-County</li>
 <li><i>watches</i> - Polygon SPC Watch boundaries</li>
</ul>
<p>[1] Storm reports are plotting valid at the given time (variable ts).
        To specify a time range, set ts1 and ts2 variable to the UTC start
        and end time respectively.
        For example, &amp;ts1=200806071000&amp;ts2=200806071015 to get LSRs
        between 10 and 1015z.</p>
<p>[2] Logic is applied to these layers to find the closest imagery to the specified
time or the realtime imagery if no time (variable ts) is specified.
</div>
</div>


<div class="item">
 <h4>&amp;sector=...</h4>
<div class="desc">
 Predefined areal extent to use for the map. Current sectors are:
<ul>
 <li><i>conus</i> - CONUS</li>
 <li><i>hun</i> - Northern Alabama</li>
 <li><i>iem</i> - Iowa</li>
 <li><i>ict</i> - Wichita, Kansas</li>
 <li><i>lot</i> - Chicago</li>
 <li><i>sd</i> - South Dakota</li>
 <li><i>texas</i> - Texas</li>
 <li><i>wfo</i> - NWS Weather Forecast Office, if you use this, then you need
 to also set the variable sector_wfo=XXX , where XXX is the 3 char call letters</li>
</ul>
</div>
</div>

<div class="item">
 <h4>&amp;width=640&amp;height=480</h4>
<div class="desc">
 Width and height of the map in pixels.
</div>
</div>

<div class="item">
 <h4>&amp;vtec=...</h4>
<div class="desc">
 VTEC identification string of a specific product.  The result is a map 
 centered on this product with a timestamp set to product issuance. An
 example VTEC string is: "2008.O.NEW.KDMX.TO.W.0048".
</div>
</div>

<div class="item">
 <h4>&amp;pid=...</h4>
<div class="desc">
  This is for the specific example of offices who issue geometries with 
  their SPS statements.  An example string is: "200903082123-KGRR-WWUS83-SPSGRR"
</div>
</div>

<div class="item">
 <h4>&amp;bbox=xmin,ymin,xmax,ymax</h4>
<div class="desc">
  Bounding box of the map (typically a latitude and longitude box). An example
  would be "-95.4,40.1,-89.4,44.5".
</div>
</div>

<div class="item">
 <h4>&amp;ts=YYYYMMDDHHII</h4>
<div class="desc">
  Timestamp in UTC for which the map is valid for.  For example, 6:45 UTC on 
5 Jun 2005 would be "200506050645".  For the imagery layers, this timestamp is
used to find the closest imagery in time.
</div>
</div>

<div class="item">
 <h4>&amp;ts1=YYYYMMDDHHII&amp;ts2=YYYYMMDDHHII</h4>
<div class="desc">
  Start and end timestamp in UTC for to look for Local Storm Reports. 
  For example, 6:45 UTC on 5 Jun 2005 would be "200506050645". If ts1 is not
  specified, it defaults to the value of ts.
</div>
</div>

<div class="item">
 <h4>&amp;title=....</h4>
<div class="desc">
  A customized title to place on the map.
</div>
</div>

<div class="item">
 <h4>&amp;tz=....</h4>
<div class="desc">
  A lame specification of the timezone that should be used for the map.  This
  can be only of the following "UTC, EDT, EST, CDT, CST, MDT, MST, PDT, PST".
</div>
</div>


<h3>Example Python client script</h3>

<p>Here is an example python script that will call this service and locally
generate a folder of images that can then be converted into a movie.
<br />
<pre style="border-top: 1px solid #ccc; background: #EEFFCC; border-bottom: 1px solid #ccc; padding-left: 5px;">
#!/usr/bin/env python

import os
from datetime import datetime, timedelta

# Generate series of images between 0z and 12z on the 3rd of August
now = datetime(2008, 8, 3, 0, 0)
ets = datetime(2008, 8, 3, 12, 0)
interval = timedelta(minutes=5)

baseuri = "{$EXTERNAL_BASEURL}/GIS/radmap.php?"
baseuri += "width=800&amp;height=600&amp;bbox=-95,42.5,-89,45.5"
baseuri += "&amp;layers[]=uscounties&amp;layers[]=nexrad&amp;layers[]=sbw"
baseuri += "&amp;layers[]=watch_by_county"

# Change into a frames folder
os.chdir("frames")
stepi = 0
while (now < ets):
  url = "%s&ts=%s" % (baseuri, now.strftime("%Y%m%d%H%M"))
  cmd = "wget -q -O %05i.png '%s'" % (stepi, url )
  os.system(cmd)
  stepi += 1
  now += interval

os.system("ffmpeg -y -i %05d.png -b 2000k out.mp4")
</pre>

<h3>Change Log</h3>
<ul>
  <li><strong>2 April 2025:</strong> Simplified what actually works with regards
   to IEM GOES archive plotting. All the IEM has is a composite of WV, IR, and VIS.</li>
 <li><strong>22 May 2016:</strong> Clarified the Local Storm Reports timestamp
        options.</li>
 <li><strong>4 May 2012:</strong> Add incorporated places as a layer option.</li>
 <li><strong>14 Apr 2012:</strong> Another cleanup and add ridge and GOES
 imagery layers as available plotting options.</li>
 <li><strong>18 Oct 2011:</strong> Cleanup and clarify LSRs.</li>
 <li><strong>10 Mar 2009:</strong> Initial release</li>
</ul>
EOM;
$t->render('single.phtml');
