#################
Lightning Strikes
#################

========
Overview
========

Request Types
-------------

This portion of the API concerns lightning strikes, which are point data
affecting a geographic region (defined by an extent) or proximity around a
location (defined by a point and radius).  There are 2 request types, providing
different levels of detail. Each response identifies a possible transition to
further information. These can be depicted as follows:

.. image:: _static/lightning.png
   :alt: Lightning Request Transition Diagram
   :align: center

.. _lightning_parameters:

Request Parameters
------------------

Lightning summary and history requests allow for additional parameters beyond
those specified by the :ref:`request_format`.

* **OPTIONAL**: A list of strike types (*types*) to include in the response.
  Accepted values are ``cloud`` (cloud-to-cloud lightning only), ``ground``
  (cloud-to-ground lightning only), or both, separated by a comma. If
  unspecified, only ground strikes are included.

* **OPTIONAL** (proximity requests only): A radius in statute miles or
  kilometers (*radius*) around the given location defining a search area for
  lightning strikes included in the response.  If unspecified, *radius*
  defaults to 1. The maximum allowed radius is 20 statute miles.

* **OPTIONAL** (proximity requests only): A unit designator (*units*) for
  interpretation of the radius as well as the distance included in the response.
  Accepted values are ``miles`` or ``km``. If unspecified, *units* defaults to
  statute miles.

* **OPTIONAL** (proximity history requests only): A sort order (*sort*) for lightning
  strikes in the response. Accepted values include ``distance`` (nearest to
  farthest) or ``time`` (oldest to newest). If unspecified, results are sorted
  by distance.

Response Content
----------------

The following fields are included in each representation of a lightning strike:

* **id** (string)
* **date/time** (`RFC 3339`_ string including milliseconds)
* **type** (string): "cloud" or "ground"
* **location** (`ISO 6709`_ string)
* **peak current**
    * **unit** (string): "amps"
    * **value** (integer)
* **distance** (proximity requests only)
    * **unit** (string): "miles" or "km"
    * **value** (decimal)
* **bearing** (proximity requests only)
    * **unit** (string): "degrees from north"
    * **value** (decimal)

=======================
Proximity-Based Summary
=======================

This request returns the total number of lightning strikes impacting the
proximity around a specific location within a date range (the last 24 hours by
default). Results are returned as `JSON`_ or `XML`_. A link to the
`proximity-based history`_ (within the same date range) is included in the
response to facilitate a client-side transition.

URI Examples
------------

::

    forensic.api.wdtinc.com/v2/lightning/summary/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/summary/+DD.ddd-DDD.ddd.xml?radius=&units=&begin=&end=&types=&u=&t=

See prior sections for a description of the :ref:`request_format` and
:ref:`lightning_parameters`.

.. rst-class:: html-toggle

JSON Response
-------------

The JSON representation of the resource is structured as follows
(loosely based on Google's `JSON style guide`_)::

    {
        "apiVersion": "2.5.8",
        "lightningSummary": {
            "dateRange": {
                "begin": "YYYY-MM-DDThh:mm:ss",
                "end": "YYYY-MM-DDThh:mm:ss"
            },
            "location": "+DD.ddd-DDD.ddd",
            "radius": {
                "unit": "",
                "value": DD.dd
            }
            "selfLink": "/v2/lightning/summary/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&u=&t=",
            "strikeCount": nn,
            "lightningHistoryLink": "/v2/lightning/history/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&u=&t=",
        }
    }

.. rst-class:: html-toggle

XML Response
------------

The XML representation of the resource is structured as follows (based on
Google's `XML style guide`_):

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <lightningSummary xmlns="http://forensic.api.wdtinc.com/lightning"
                  xmlns:xlink="http://www.w3.org/1999/xlink"
                  xlink:href="/v2/lightning/summary/+DD.ddd-DDD.ddd.xml?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=">
        <dateRange begin="YYYY-MM-DDThh:mm:ss" end="YYYY-MM-DDThh:mm:ss" />
        <location format="iso6709">+DD.ddd-DDD.ddd</location>
        <radius unit="">DD.dd</radius>
        <strikeCount>nn</strikeCount>
        <lightningHistory xlink:href="/v2/lightning/history/+DD.ddd-DDD.ddd.xml?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=" />
    </lightningSummary>

====================
Region-Based Summary
====================

This request returns the total number of lightning strikes impacting a given
region within a date range (the last 24 hours by default). The region is required
to be no more than 40 miles wide in either direction.  Results are returned
as `JSON`_ or `XML`_. A link to the `region-based history`_ (within the same
date range) is included in the response to facilitate a client-side transition.

URI Examples
------------

::

    forensic.api.wdtinc.com/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&end=&types=&u=&t=

See prior sections for a description of the :ref:`request_format` and
:ref:`lightning_parameters`.

.. rst-class:: html-toggle

JSON Response
-------------

The JSON representation of the resource is structured as follows
(loosely based on Google's `JSON style guide`_)::

    {
        "apiVersion": "2.5.8",
        "lightningSummary": {
            "dateRange": {
                "begin": "YYYY-MM-DDThh:mm:ss",
                "end": "YYYY-MM-DDThh:mm:ss"
            },
            "region": "+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd",
            "selfLink": "/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&u=&t=",
            "strikeCount": nn,
            "lightningHistoryLink": "/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&u=&t=",
        }
    }

.. rst-class:: html-toggle

XML Response
------------

The XML representation of the resource is structured as follows (based on
Google's `XML style guide`_):

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <lightningSummary xmlns="http://forensic.api.wdtinc.com/lightning"
                  xmlns:xlink="http://www.w3.org/1999/xlink"
                  xlink:href="/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&amp;end=&amp;types=&amp;u=&amp;t=">
        <dateRange begin="YYYY-MM-DDThh:mm:ss" end="YYYY-MM-DDThh:mm:ss" />
        <region format="iso6709">+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd</region>
        <strikeCount>nn</strikeCount>
        <lightningHistory xlink:href="/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&amp;end=&amp;types=&amp;u=&amp;t=" />
    </lightningSummary>

=======================
Proximity-Based History
=======================

This request returns the history of lightning strikes impacting the proximity
around a specific location within a date range (the last 24 hours by default).
The region is required to be no more than 40 miles wide in either direction.
Results are returned as `GeoJSON`_, `KML`_, or `XML`_. An empty list (feature
collection) is returned if there are no strikes. A link to the
`proximity-based summary`_ (within the same date range) is included in the
response to facilitate a client-side transition.

URI Examples
------------

::

    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&sort=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd.kml?radius=&units=&begin=&end=&types=&sort=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd.xml?radius=&units=&begin=&end=&types=&sort=&u=&t=

See prior sections for a description of the :ref:`request_format` and
:ref:`lightning_parameters`.

.. rst-class:: html-toggle

GeoJSON Response
----------------

The GeoJSON representation of the resource is structured as follows::

    {
        "apiVersion": "2.5.8",
        "lightningHistory": {
            "dateRange": {
                "begin": "YYYY-MM-DDThh:mm:ss",
                "end": "YYYY-MM-DDThh:mm:ss"
            },
            "features": [
                {
                    "geometry": {
                        "coordinates": [
                            -85.930000000000007,
                            38.079999999999998
                        ],
                        "type": "Point"
                    },
                    "properties": {
                        "timestamp": "YYYY-MM-DDThh:mm:ss.ssss",
                        "id": "...",
                        "location": "+DD.ddd-DDD.ddd",
                        "peakCurrent": {
                            "unit": "amps",
                            "value": DDD
                        },
                        "proximity": {
                            "bearing": {
                                "unit": "degrees from north",
                                "value": DD.dd
                            },
                            "distance": {
                                "unit": "",
                                "value": DD.dd
                            }
                        },
                        "type": "cloud"
                    },
                    "type": "Feature"
                },
                {
                    "geometry": {
                        "coordinates": [
                            -74.930000000000007,
                            42.019999999999998
                        ],
                        "type": "Point"
                    },
                    "properties": {
                        "timestamp": "YYYY-MM-DDThh:mm:ss.ssss",
                        "id": "...",
                        "location": "+DD.ddd-DDD.ddd",
                        "peakCurrent": {
                            "unit": "amps",
                            "value": DDD
                        },
                        "proximity": {
                            "bearing": {
                                "unit": "degrees from north",
                                "value": DD.dd
                            },
                            "distance": {
                                "unit": "",
                                "value": DD.dd
                            }
                        },
                        "type": "ground"
                    },
                    "type": "Feature"
                },
                :
                :
            ],
            "lightningSummaryLink": "/v2/lightning/summary/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&u=&t=",
            "location": "+DD.ddd-DDD.ddd",
            "radius": {
                "unit": "miles",
                "value": DD.dd
            },
            "selfLink": "/v2/lightning/history/+DD.ddd-DDD.ddd?radius=&units=&begin=&end=&types=&u=&t=",
            "type": "FeatureCollection"
        }
    }

.. rst-class:: html-toggle

KML Response
------------

The KML representation of the resource is structured as follows:

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <kml xmlns="http://www.opengis.net/kml/2.2">
        <Document>
            <name>Lightning History</name>
            <ExtendedData>
                <Data name="selfLink">
                    <value>/v2/lightning/history/+DD.ddd-DDD.ddd?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=</value>
                </Data>
                <Data name="beginDate"><value>YYYY-MM-DDThh:mm:ssZ</value></Data>
                <Data name="endDate"><value>YYYY-MM-DDThh:mm:ssZ</value></Data>
                <Data name="location"><value>+DD.ddd-DDD.ddd</value></Data>
                <Data name="radius"><value>DD.ddd</value></Data>
                <Data name="radius-unit"><value>miles</value></Data>
                <Data name="lightningSummaryLink">
                    <value>/v2/lightning/summary/+DD.ddd-DDD.ddd?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=</value>
                </Data>
            </ExtendedData>
            <Placemark>
                <name>id</name>
                <ExtendedData>
                    <Data name="timestamp"><value>YYYY-MM-DDThh:mm:ss.sssZ</value></Data>
                    <Data name="distance"><value>...</value></Data>
                    <Data name="distance-unit"><value>...</value></Data>
                    <Data name="bearing"><value>...</value></Data>
                    <Data name="bearing-unit"><value>degrees from north</value></Data>
                    <Data name="peakCurrent"><value>DDD</value></Data>
                    <Data name="peakCurrent-unit"><value>amps</value></Data>
                    <Data name="type"><value>cloud</value></Data>
                </ExtendedData>
                <Point>
                    <coordinates>-91.95,39.5024</coordinates>
                </Point>
            </Placemark>
            <Placemark>
                <name>id</name>
                <ExtendedData>
                    <Data name="timestamp"><value>YYYY-MM-DDThh:mm:ss.sssZ</value></Data>
                    <Data name="distance"><value>...</value></Data>
                    <Data name="distance-unit"><value>...</value></Data>
                    <Data name="bearing"><value>...</value></Data>
                    <Data name="bearing-unit"><value>degrees from north</value></Data>
                    <Data name="peakCurrent"><value>DDD</value></Data>
                    <Data name="peakCurrent-unit"><value>amps</value></Data>
                    <Data name="type"><value>ground</value></Data>
                </ExtendedData>
                <Point>
                    <coordinates>-81.847,42.7024</coordinates>
                </Point>
            </Placemark>
                :
                :
        </Document>
    </kml>

.. rst-class:: html-toggle

XML Response
------------

The XML representation of the resource is structured as follows (based on
Google's `XML style guide`_):

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <lightningHistory xmlns="http://forensic.api.wdtinc.com/lightning"
                  xmlns:xlink="http://www.w3.org/1999/xlink"
                  xlink:href="/v2/lightning/history/+DD.ddd-DDD.ddd.xml?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=">
        <dateRange begin="YYYY-MM-DDThh:mm:ss" end="YYYY-MM-DDThh:mm:ss" />
        <location format="iso6709">+DD.ddd-DDD.ddd</location>
        <radius unit="miles">DD.ddd</radius>
        <strike id="...">
            <timestamp>YYYY-MM-DDThh:mm:ss.sssZ</timestamp>
            <location format="iso6709">+DD.ddd-DDD.ddd</location>
            <peakCurrent unit="amps">DDD</peakCurrent>
            <proximity>
                <distance unit="">DD.dd</distance>
                <bearing unit="degrees from north">DD.dd</bearing>
            </proximity>
            <type>cloud</type>
        </strike>
        <strike id="...">
            <timestamp>YYYY-MM-DDThh:mm:ss.sssZ</timestamp>
            <location format="iso6709">+DD.ddd-DDD.ddd</location>
            <peakCurrent unit="amps">DDD</peakCurrent>
            <proximity>
                <distance unit="">DD.dd</distance>
                <bearing unit="degrees from north">DD.dd</bearing>
            </proximity>
            <type>ground</type>
        </strike>
            :
            :
        <lightningSummary xlink:href="/v2/lightning/summary/+DD.ddd-DDD.ddd.xml?radius=&amp;units=&amp;begin=&amp;end=&amp;types=&amp;u=&amp;t=" />
    </lightningHistory>

====================
Region-Based History
====================

This request returns the history of lightning strikes impacting a given region
within a date range (the last 24 hours by default). Results are returned as
`GeoJSON`_, `KML`_, or `XML`_. An empty list (feature collection) is returned
if there are no strikes. A link to the `region-based summary`_ (within the same
date range) is included in the response to facilitate a client-side transition.

URI Examples
------------

::

    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&sort=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.kml?begin=&end=&types=&sort=&u=&t=
    forensic.api.wdtinc.com/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&end=&types=&sort=&u=&t=

See prior sections for a description of the :ref:`request_format` and
:ref:`lightning_parameters`.

.. rst-class:: html-toggle

GeoJSON Response
----------------

The GeoJSON representation of the resource is structured as follows::

    {
        "apiVersion": "2.5.8",
        "lightningHistory": {
            "dateRange": {
                "begin": "YYYY-MM-DDThh:mm:ss",
                "end": "YYYY-MM-DDThh:mm:ss"
            },
            "features": [
                {
                    "geometry": {
                        "coordinates": [
                            -85.930000000000007,
                            38.079999999999998
                        ],
                        "type": "Point"
                    },
                    "properties": {
                        "timestamp": "YYYY-MM-DDThh:mm:ss.sss",
                        "id": "...",
                        "location": "+DD.ddd-DDD.ddd",
                        "peakCurrent": {
                            "unit": "amps",
                            "value": DDD
                        },
                        "type": "cloud"
                    },
                    "type": "Feature"
                },
                {
                    "geometry": {
                        "coordinates": [
                            -74.930000000000007,
                            42.019999999999998
                        ],
                        "type": "Point"
                    },
                    "properties": {
                        "timestamp": "YYYY-MM-DDThh:mm:ss.sss",
                        "id": "...",
                        "location": "+DD.ddd-DDD.ddd",
                        "peakCurrent": {
                            "unit": "amps",
                            "value": DDD
                        },
                        "type": "ground"
                    },
                    "type": "Feature"
                },
                :
                :
            ],
            "lightningSummaryLink": "/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&u=&t=",
            "region": "+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd",
            "selfLink": "/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&end=&types=&u=&t=",
            "type": "FeatureCollection"
        }
    }

.. rst-class:: html-toggle

KML Response
------------

The KML representation of the resource is structured as follows:

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <kml xmlns="http://www.opengis.net/kml/2.2">
        <Document>
            <name>Lightning History</name>
            <ExtendedData>
                <Data name="selfLink">
                    <value>/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&amp;end=&amp;types=&amp;u=&amp;t=</value>
                </Data>
                <Data name="beginDate"><value>YYYY-MM-DDThh:mm:ssZ</value></Data>
                <Data name="endDate"><value>YYYY-MM-DDThh:mm:ssZ</value></Data>
                <Data name="region"><value>+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd</value></Data>
                <Data name="lightningSummaryLink">
                    <value>/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd?begin=&amp;end=&amp;types=&amp;u=&amp;t=</value>
                </Data>
            </ExtendedData>
            <Placemark>
                <name>id</name>
                <ExtendedData>
                    <Data name="timestamp"><value>YYYY-MM-DDThh:mm:ss.sssZ</value></Data>
                    <Data name="peakCurrent"><value>DDD</value></Data>
                    <Data name="peakCurrent-unit"><value>amps</value></Data>
                    <Data name="type"><value>cloud</value></Data>
                </ExtendedData>
                <Point>
                    <coordinates>-91.95,39.5024</coordinates>
                </Point>
            </Placemark>
            <Placemark>
                <name>id</name>
                <ExtendedData>
                    <Data name="timestamp"><value>YYYY-MM-DDThh:mm:ss.sssZ</value></Data>
                    <Data name="peakCurrent"><value>DDD</value></Data>
                    <Data name="peakCurrent-unit"><value>amps</value></Data>
                    <Data name="type"><value>ground</value></Data>
                </ExtendedData>
                <Point>
                    <coordinates>-81.847,42.7024</coordinates>
                </Point>
            </Placemark>
                :
                :
        </Document>
    </kml>

.. rst-class:: html-toggle

XML Response
------------

The XML representation of the resource is structured as follows (based on
Google's `XML style guide`_):

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <lightningHistory xmlns="http://forensic.api.wdtinc.com/lightning"
                  xmlns:xlink="http://www.w3.org/1999/xlink"
                  xlink:href="/v2/lightning/history/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&amp;end=&amp;types=&amp;u=&amp;t=">
        <dateRange begin="YYYY-MM-DDThh:mm:ss" end="YYYY-MM-DDThh:mm:ss" />
        <region format="iso6709">+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd</region>
        <strike id="...">
            <timestamp>YYYY-MM-DDThh:mm:ss.sssZ</timestamp>
            <location format="iso6709">+DD.ddd-DDD.ddd</location>
            <peakCurrent unit="amps">DDD</peakCurrent>
            <type>cloud</type>
        </strike>
        <strike id="...">
            <timestamp>YYYY-MM-DDThh:mm:ss.sssZ</timestamp>
            <location format="iso6709">+DD.ddd-DDD.ddd</location>
            <peakCurrent unit="amps">DDD</peakCurrent>
            <type>ground</type>
        </strike>
            :
            :
        <lightningSummary xlink:href="/v2/lightning/summary/+DD.ddd-DDD.ddd+DD.ddd-DDD.ddd.xml?begin=&amp;end=&amp;types=&amp;u=&amp;t=" />
    </lightningHistory>

.. _`GeoJSON`: http://en.wikipedia.org/wiki/GeoJSON
.. _`ISO 6709`: http://en.wikipedia.org/wiki/ISO_6709
.. _`JSON`: http://en.wikipedia.org/wiki/JSON
.. _`JSON style guide`: http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml
.. _`KML`: https://developers.google.com/kml/documentation/
.. _`RFC 3339`: http://www.ietf.org/rfc/rfc3339.txt
.. _`XML`: http://en.wikipedia.org/wiki/XML
.. _`XML style guide`: http://google-styleguide.googlecode.com/svn/trunk/xmlstyle.html