add timezone parameter and documentation

2014-04-25 14:38:30 -04:00
parent 915ff7c82e
commit 7f0d8644f8
12 changed files with 90 additions and 49 deletions
--- a/app/views/docs/_sidebar.html.erb
+++ b/app/views/docs/_sidebar.html.erb
@ -1,6 +1,14 @@
 <ul class="nav nav-stacked" id="bootstrap-sidebar">

-  <li class="<%= 'active' if params[:action] == 'index' %>"><a href="/docs">Getting Started</a></li>
+  <% if params[:action] == 'index' %>
+    <li><a href="#start">Getting Started</a></li>
+    <li class="subitem"><a href="#support">Support</a></li>
+    <li class="subitem"><a href="#opensource">Open Source</a></li>
+    <li class="subitem"><a href="#headers">HTTP Headers</a></li>
+    <li class="subitem"><a href="#timezones">Time Zones</a></li>
+  <% else %>
+    <li><a href="/docs">Getting Started</a></li>
+  <% end %>

  <% if params[:action] == 'channels' %>
    <li><a href="#channels">Channels</a></li>
--- a/app/views/docs/channels/_feed.html.erb
+++ b/app/views/docs/channels/_feed.html.erb
@ -15,7 +15,8 @@ Valid parameters:
  <li><b>days</b> (integer) Number of 24-hour periods before now to include in feed (optional)</li>
  <li><b>start</b> (datetime) Start date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
  <li><b>end</b> (datetime) End date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
  <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
  <li><b>min</b> (decimal) Minimum value to include in response (optional)</li>
@ -176,7 +177,8 @@ replacing <span class="customcode">CHANNEL_ID</span> with the ID of your Channel
 Valid parameters:
 <ul>
  <li><b>key</b> (string) Read API Key for this specific Channel (optional--no key required for public channels)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
  <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
  <li><b>callback</b> (string) Function name to be used for JSONP cross-domain requests (optional)</li>
@ -248,7 +250,8 @@ replacing <span class="customcode">CHANNEL_ID</span> with the ID of your Channel
 Valid parameters:
 <ul>
  <li><b>key</b> (string) Read API Key for this specific Channel (optional--no key required for public channels)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
  <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
  <li><b>callback</b> (string) Function name to be used for JSONP cross-domain requests (optional)</li>
--- a/app/views/docs/channels/_field.html.erb
+++ b/app/views/docs/channels/_field.html.erb
@ -15,7 +15,8 @@ Valid parameters:
  <li><b>days</b> (integer) Number of 24-hour periods before now to include in feed (optional)</li>
  <li><b>start</b> (datetime) Start date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
  <li><b>end</b> (datetime) End date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
  <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
  <li><b>min</b> (decimal) Minimum value to include in response (optional)</li>
@ -160,7 +161,8 @@ replacing <span class="customcode">CHANNEL_ID</span> with the ID of your Channel
 Valid parameters:
 <ul class="format-block">
  <li><b>key</b> (string) Read API Key for this specific Channel (optional--no key required for public channels)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
  <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
  <li><b>callback</b> (string) Function name to be used for JSONP cross-domain requests (optional)</li>
--- a/app/views/docs/channels/_status.html.erb
+++ b/app/views/docs/channels/_status.html.erb
@ -11,7 +11,8 @@ replacing <span class="customcode">CHANNEL_ID</span> with the ID of your Channel
 Valid parameters:
 <ul>
  <li><b>key</b> (string) Read API Key for this specific Channel (optional--no key required for public channels)</li>
-  <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+  <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+  <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
  <li><b>callback</b> (string) Function name to be used for JSONP cross-domain requests (optional)</li>
 </ul>

--- a/app/views/docs/charts.html.erb
+++ b/app/views/docs/charts.html.erb
@ -45,7 +45,8 @@
      <li><b>days</b> (integer) Number of 24-hour periods before now to include in feed (optional)</li>
      <li><b>start</b> (datetime) Start date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
      <li><b>end</b> (datetime) End date in format YYYY-MM-DD%20HH:NN:SS (optional)</li>
-      <li><b>offset</b> (integer)  Offset of your timezone without daylight savings time (optional)</li>
+      <li><b>timezone</b> (string) <a href="/docs#timezones">Timezone identifier</a> for this request (optional)</li>
+      <li><b>offset</b> (integer) Timezone offset that results should be displayed in. Please use the <a href="/docs#timezones">timezone</a> parameter for greater accuracy. (optional)</li>
      <li><b>status</b> (true/false) Include status updates in feed by setting "status=true" (optional)</li>
      <li><b>location</b> (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)</li>
      <li><b>min</b> (decimal) Minimum value to include in response (optional)</li>
--- a/app/views/docs/index.html.erb
+++ b/app/views/docs/index.html.erb
@ -6,7 +6,7 @@

  <div class="col-sm-7 col-xs-12">

-    <h1>Getting Started</h1>
+    <h1 id="start">Getting Started</h1>

    <ul>
      <li>Sign Up for a New User Account -&nbsp;<a title="Create New ThingSpeak User Account" href="https://thingspeak.com/account/new">https://thingspeak.com/account/new</a></li>
@ -15,11 +15,11 @@
    </ul>

    <br>
-    <h4>Support</h4>
+    <h4 id="support">Support</h4>
    <p>Please post your questions, comments, and feature requests in the <a title="ThingSpeak Forum" href="http://community.thingspeak.com/forum/">ThingSpeak Forum</a>.</p>

    <br><br>
-    <h4>Open Source</h4>
+    <h4 id="opensource">Open Source</h4>

    <p>The ThingSpeak API is&nbsp;available&nbsp;on <a title="ThingSpeak Open Source Web of Things API on GitHub" href="https://github.com/iobridge/thingspeak" target="_blank">GitHub</a> and includes the complete ThingSpeak API for processing HTTP requests, storing numeric and&nbsp;alphanumeric&nbsp;data, numeric data processing, location tracking, and status updates. &nbsp;The open source version follows the same documentation as the ThingSpeak hosted service.</p>

@ -29,9 +29,37 @@
    </ul>

    <br><br>
-    <h4>HTTP Headers</h4>
+    <h4 id="headers">HTTP Headers</h4>
    If you would like to reduce the number of HTTP headers sent by our application, please add the parameter "headers=false" to any HTTP request.

+    <br><br><br><br>
+    <h4 id="timezones">Time Zones Reference</h4>
+    Time zones can be specified for any request by adding the <i>timezone</i> parameter with a value corresponding to any identifier found below.
+    Identifier names are case-sensitive, and should be URL-encoded in HTTP GET requests, for example:
+    <br><br>
+<pre>GET <span class="str"><%= @ssl_api_domain %>channels/9/fields/1/last.json?timezone=<span class="customcode">America%2FNew_York</span></span></pre>
+    <br>
+    <table class="table table-striped table-bordered table-condensed">
+      <tr>
+        <th>Identifier</th>
+        <th>Description</th>
+        <th>Current Offset</th>
+      </tr>
+      <% @timezones.each do |identifier, hash| %>
+        <tr>
+          <td><%= identifier %></td>
+          <td><%= raw(hash[:description]) %></td>
+          <td>UTC <%= hash[:offset] %></td>
+        </tr>
+      <% end %>
+    </table>
+
+    <div class="alert alert-warning">
+      <b>Note:</b>
+      <br>
+      If both the <i>offset</i> and <i>timezone</i> parameters are present, <i>offset</i> will be ignored in favor of the more accurate <i>timezone</i> parameter.
+    </div>
+
    <br><br><br><br><br><br><br><br><br><br><br><br>

  </div>