wettercom.py

# -*- coding: utf-8 -*-

"""
Client for the openweater API from Wetter.com

Usage:
>>> w = WetterCom('ProjectName', 'ApiKey')
>>> w.search_location('48143', type='zip')
u'exact_match': True,
             u'hits': 4,
             u'maxhits': 30,
             u'result': [{u'adm_1_code': u'DE',
                          u'adm_2_name': u'Nordrhein-Westfalen',
                          u'adm_4_name': u'Münster',
                          ...
>>> w.get_forecast('DE0010058')
{u'city_code': u'DE0010058',
 u'forecast': {u'2013-03-13': {u'06:00': {u'd': u'1363154400',
                                          u'dhl': u'2013-03-13 06:00',
                                          u'dhu': u'2013-03-13 04:00',
                                          u'p': u'5',
                                          u'tn': u'-8',
                                          ...
"""

import hashlib
import requests


class WetterCom(object):
    BASE_URL = 'http://api.wetter.com/'
    SEARCH_URL = {'keyword': 'location/index/search/{}/project/{}/cs/{}',
                  'name': 'location/name/search/{}/project/{}/cs/{}',
                  'zip': 'location/plz/search/{}/project/{}/cs/{}'}
    FORECAST_URL = 'forecast/weather/city/{}/project/{}/cs/{}'

    def __init__(self, project, apiKey):
        self.project = project
        self.apiKey = apiKey

    def _get_checksum(self, keyword):
        """Returns md5 hash for authentication"""
        string = self.project + self.apiKey + keyword
        return hashlib.md5(string).hexdigest()

    def _parse_response(self, response):
        """Checks response for error and cleans it"""
        if 'error' in response:
            if response['error']['title'] == 'Invalid access data':
                raise WetterComAuthenticationError(
                    response['error']['title']
                )
            else:
                raise WetterComError(
                    'Unknown Error:{}'.format(
                        ' '.join(response['error'].itervalues()))
                )
        #Clean up response
        if 'search' in response:
            response = response['search']
        if 'city' in response:
            response = response['city']
        if 'credit' in response:
            del response['credit']
        return response

    def _format_url(self, url, string):
        url = url.format(string, self.project, self._get_checksum(string))
        url = self.BASE_URL + url + '/output/json'
        return url

    def _dispatch_request(self, url):
        response = requests.get(url).json()
        return response

    def search_location(self, searchString, type='keyword'):
        """Search for locations"""
        if not type in self.SEARCH_URL:
            raise ValueError(
                '{} is no valid type of search ({})'.format(
                    type,
                    self.SEARCH_URL.keys())
            )
        url = self.SEARCH_URL[type]
        url = self._format_url(url, searchString)
        response = self._dispatch_request(url)
        return self._parse_response(response)

    def get_forecast(self, cityCode):
        """Loads forecast informations by the given cityCode"""
        url = self._format_url(self.FORECAST_URL, cityCode)
        response = self._dispatch_request(url)
        return self._parse_response(response)


class WetterComError(Exception):
    pass


class WetterComAuthenticationError(WetterComError):
    pass