*******************
Python Weather API - Pyweatherbit
*******************

This is a wrapper for the Weatherbit API.

The Weatherbit IO allows you to access forecasts, current data, and historical data. This library wraps this functionality, and makes it accessible with Python.


Installation
############
You should use pip to install pyweatherbit.

* To install: pip install pyweatherbit
* To remove:  pip uninstall pyweatherbit

Requirements
############

- You need an API key to use it (https://weatherbit.io/). Sign up for the Free tier to get started.


Basic Use
#########

For additional information, refer to the Weatherbit.io documentation at https://www.weatherbit.io .

To use the wrapper:

.. code-block:: python

	from weatherbit.api import Api
	api_key = "YOUR API KEY"
	lat = 38.00
	long = -125.75

	api = Api(api_key)

	# Optional - Use HTTPS instead.
	# api.set_https(True)

	# Set the granularity of the API - Options: ['daily','hourly','3hourly']
	# Will only affect forecast requests.
	api.set_granularity('3hourly')

	forecast = api.get_forecast(lat=lat, lon=long)

	# You can also query by city:
	forecast = api.get_forecast(city="Raleigh,NC")

	# Or City, state, and country:
	forecast = api.get_forecast(city="Raleigh", state="North Carolina", country="US")

	# To get a time series of temperature, and precipitation:
	print forecast.get_series(['temp','precipitation'])
	...

The ``get_forecast()`` method requires named parameters. The current choices are either (lat=..., lon=...), (city="City,ST"), or (city=..., state=..., country=...)


Advanced
########

*function* weatherbit.Api.get_forecast(lat=..., lon=...)
---------------------------------------------------

This makes an API request and returns a **Forecast** object (see below).

Parameters:
	- **key** - Your API key from https://www.weatherbit.io.
	- **lat** - The latitude of the location for the forecast
	- **lon** - The longitude of the location for the forecast
	- **units** - (optional) A string of the preferred units of measurement. Choices are currently 'S' for scientific, 'M' for Metric, or 'I' for imperial units.

*function* weatherbit.Api.get_forecast(city=..., state=..., country=...)
---------------------------------------------------

This makes an API request and returns a **Forecast** object (see below).

Parameters:
	- **key** - Your API key from https://www.weatherbit.io.
	- **city** - The City to search by. This can be appended with a state like -> "City,ST".
	- **state** - (optional) State of location.
	- **country** - (optional) Country of location
	- **units** - (optional) A string of the preferred units of measurement. Choices are currently 'S' for scientific, 'M' for Metric, or 'I' for imperial units.

*function* weatherbit.Api.get_history(lat=..., lon=...)
---------------------------------------------------

This makes an API request and returns a **History** object (see below).

Parameters:
	- **key** - Your API key from https://www.weatherbit.io.
	- **lat** - The latitude of the location for the forecast
	- **lon** - The longitude of the location for the forecast
	- **units** - (optional) A string of the preferred units of measurement. Choices are currently 'S' for scientific, 'M' for Metric, or 'I' for imperial units.

*function* weatherbit.Api.get_history(city=..., state=..., country=...)
---------------------------------------------------

This makes an API request and returns a **History** object (see below).

Parameters:
	- **key** - Your API key from https://www.weatherbit.io.
	- **city** - The City to search by. This can be appended with a state like -> "City,ST".
	- **state** - (optional) State of location.
	- **country** - (optional) Country of location
	- **units** - (optional) A string of the preferred units of measurement. Choices are currently 'S' for scientific, 'M' for Metric, or 'I' for imperial units.

----------------------------------------------------



*class* forecastio.models.Forecast
------------------------------------

The **Forecast** object, it contains both weather data and the HTTP response from Weatherbit

**Attributes**
	- **response**
		- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response
	- **http_headers**
		- A dictionary of response headers. 
	- **json**
		- A dictionary containing the json data returned from the API call.
    - **city_name**
    	- City Name of the forecast points.
    - **country_code**
    	- Country Code of the forecast points
    - **state_code**
    	- State Code of the forecast points
    - **lat**
    	- Latitude of the forecast points
    - **lon**
    	- Longitude of the forecast points
	- **points**
	    - Array of forecast data Point objects.
**Methods**
	- **get_series([var1, var2, ... , varn])**
		- Returns list of dicts sorted by datetime, containing the desired variables in a time series.
	- **update()**
		- Refreshes the forecast data by making a new request.

----------------------------------------------------

*class* forecastio.models.History
------------------------------------

The **History** object, it contains both weather data and the HTTP response from Weatherbit

**Attributes**
	- **response**
		- The Response object returned from requests request.get() method. See https://requests.readthedocs.org/en/latest/api/#requests.Response
	- **http_headers**
		- A dictionary of response headers. 
	- **json**
		- A dictionary containing the json data returned from the API call.
    - **city_name**
    	- City Name of the historical points.
    - **country_code**
    	- Country Code of the historical points
    - **state_code**
    	- State Code of the historical points
    - **lat**
    	- Latitude of the historical points
    - **lon**
    	- Longitude of the historical points
	- **points**
	    - Array of historical data Point objects.
**Methods**
	- **get_series([var1, var2, ... , varn])**
		- Returns list of dicts sorted by datetime, containing the desired variables in a time series.
	- **update()**
		- Refreshes the forecast data by making a new request.

----------------------------------------------------

*class* weatherbit.models.Point
---------------------------------------------

Contains data about a history or forecast over time.

**Attributes**
	- **snow**
		- Total Snowfall.
	- **precip**
		- Total Liquid equivalent precipitation.
	- **snow6h**
		- 6h Total Snowfall.
	- **precip6h**
		- 6h Total Liquid equivalent precipitation.
	- **datetime**
		- Datetime object - Datetime  (UTC).
	- **wind_dir**
		- Average Wind direction in degrees (0-360).
	- **wind_spd**
		- Average Wind speed. 
	- **rh**
		- Average Relative Humidity (%).
	- **clouds**
		- Average Cloud cover (%).
	- **slp**
		- Average Sea level pressure in millibars.
	- **temp**
		- Average Temperature.
	- **max_temp**
		- Maximum Temperature. (daily only)
	- **min_temp**
		- Minimum Temperature. (daily only)
	- **weather**
	    - Dict containing day/night weather icon, description, and code.

----------------------------------------------------


*class* weatherbit.models.SingleTimePoint
---------------------------------------------

Contains data about a single point in time - Current weather data.

**Attributes**
	- **snow**
		- Total Snowfall.
	- **precip**
		- Total Liquid equivalent precipitation.
	- **snow3h**
		- Total 3h Snowfall.
	- **precip3h**
		- Total 3h  Liquid equivalent precipitation.
	- **datetime**
		- Datetime object - Datetime  (UTC).
	- **sunrise**
		- Datetime object - Sunrise time (UTC).
	- **sunset**
		- Datetime object - Sunset time  (UTC).
	- **wind_dir**
		- Wind direction in degrees (0-360).
	- **wind_spd**
		- Wind speed. 
	- **rh**
		- Relative Humidity (%).
	- **slp**
		- Sea level pressure in millibars.
	- **temp**
		- Temperature.
	- **clouds**
		- Cloud cover (%).
	- **visibility**
		- Visibility text (for METAR observations only).
	- **station**
		- Station ID.
	- **weather**
	    - Dict containing day/night weather icon, description, and code.

----------------------------------------------------