******************
Point Forecast API
******************

The WeatherOps Point Forecast API is an on-demand weather observation and
forecast service via an authenticated web service (HTTP). This service provides
the best available match for both our WeatherOps
forecast as well as the nearest possible observation data.


===========
Quick Start
===========

When creating an account at `WeatherOps Point Forecast API
<https://www.weatherops.com/weatherops-apis>`_, you will be provided with an
Application ID (username) and Application Key (password).

A simple example of a curl request from a command line with Basic Authentication:

.. code-block:: bash

	$ curl -X GET "https://skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35.191&LON=-97.439" \
	  --user <username>:<password>
	Ex. curl -X GET "https://skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35&LON=-97"  \
	 --user abcd5678:01234567890123456789abcdefghijkl


===================
Accepted Parameters
===================


Required
--------

One of these choices of location information. LAT/LON is preferred choice:

*  U.S. Locations: ``ZIP`` **or** ``CITY`` & ``STATE``
	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?ZIP=76354
	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?CITY=norman&STATE=ok

*  Global Cities: ``CITY`` & ``COUNTRY``
	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?CITY=tokyo&COUNTRY=jp

*  Any Global Locations:  ``LAT`` & ``LON``
	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=34.1&LON=-98.57



Optional
--------

* ``UNITS`` - By default, all values are returned in SI units (e.g. Celsius).

  * ``UNITS=us`` Return units in English units such as inches of mercury (Hg) and Fahrenheit.
	Example:skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35&LON=-97&UNITS=US

  * ``UNITS=all`` Return values in both English and SI units. The returned XML will be larger.
	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35&LON=-97&UNITS=all

* ``HOURS=`` and ``DAYS=``
	Both can be used to limit response sizes. They can be used together as well.

	``HOURS=`` option can be used to limit the number of hourly rows returned. This allows for
	smaller file sizes and improved reponse times. This value can be set to HOURS=0.

	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35&LON=-97&HOURS=24

	``DAYS=`` option can be used limit the number of days. This allows for smaller file
	sizes and improved response times. This value can be set to DAYS=0.

	Example: skywisefeeds.wdtinc.com/feeds/api/mega.php?LAT=35&LON=-97&DAYS=3

* ``TIMEZONE=local``
	This option sets some of the parameter values like <ob_time>,<sunrise_local>,
	<sunset_local>, and <time_local> for hourly forecasts. Since the offsets can not
	be guaranteed correct for all locations, the suggested way to use this service is
	with the default UTC time.

* ``FORMAT=json``
	This option converts the output to JSON format. This is a simple conversion that
	uses the same structure as the default XML.


.. rst-class:: html-toggle

==============
Error Messages
==============

If a location cannot be found then the following response is returned:

.. code-block:: xml

      <?xml version="1.0" encoding="UTF-8" ?>
      - <Error>
        <message>Unable to geocode the location provided</message>
        </Error>

If the lat/lon coordinates are out of bounds (e.g. lat > 90 or lon < -90; lon > 180 or lon < -180) a response will be returned.
The returned location will be set to the maximum or minimum allowable latitude and/or longitude coordinate.


===============
XML Description
===============

The product can be thought of as having data in 4 primary sections:

1) the <location> tag at the top has estimated location information.

	*  :doc:`mega_location`
2) the <sfc_ob> section has the closest qualified observation to the location.

	*  :doc:`mega_current`

Under forecasts, there are two sections:

3) <daily_summaries> section has individual <daily_summary> sections with summary forecast
information for local Midnight-midnight at the location.

	*  :doc:`mega_daily`

4) <hourly_summaries> section has individual <hourly_summary> sections with forecast
information for each hour.

	*  :doc:`mega_hourly`