google timezone api. getting timezone for a (latitude, longitude) tuple, or for a string address

googletz.py

from geopy import geocoders
    
def getlatlon(address, i=0, avg=False):
    '''
    returns a tuple with (lat, lon) of desired place
    
    Parameters
    ----------
    address: str
             the address as given to google maps
             
    i: None or int. 0
       if general address is given, ie 'town, country', 
       a list of possible locations will be found
       
       if i=0: only first place will be retrieved
       if None: all places will be retrieved
    
    avg: bool. False
         if i == None and avg == True: the average of all found places will be calculated
        
    Example
    -------
    
    getlatlon('tirgoviste, Ro') 
    getlatlon('tirgoviste, romania')
    getlatlon('general florescu tirgoviste, romania')
    '''
    g = geocoders.GoogleV3()
    res = g.geocode(address, exactly_one=False)

    if i is not None:                  # user wants only first place
        #place, (lat, lon) = res[0]
        return res[i][1]
    elif not avg:               # user wants entire list of places
        return res
    else:                           # user wants an aproximation, average of all places
        Llat, Llon = [place[1][0] for place in res], [place[1][1] for place in res]
        averagelat, averagelon = sum(Llat)/float(len(Llat)), sum(Llon)/float(len(Llon))
        return (averagelat, averagelon)


def gettzgoogle(loc, dt=None, apikey=None, ret=None, **kv):
    '''gets timezone for a latitude and longitude tuple
    
    Parameters
    ----------
        
    loc: tuple/list or str
         if tuple/list: it must have 2 values (latitude, longitude)
         if str: it must be the address as given to google maps
    
    dt: number or datetime source
        if number, it must be a timestamp, the number of seconds from 1 jan 1970
        else: it must be some datetime source (it will be given to P.to_datetime) 
    
    apikey: None or str
            api key for google
    
    ret: None or str
         if None: all json dict will be returned
         if str: only that parameter will be returned
                 choices: dstOffset, rawOffset, timeZoneId, timeZoneName, status    
    
    **kv: optional arguments (valid only when loc is a string address)
          i: int. 0
             to be sent to getlatlon()
          avg: bool. False
             to be sent to getlatlon()
             
    Example
    -------
    
    gettzgoogle([45,27], ret='timeZoneId')  # 'Europe/Bucharest
    
    gettzgoogle([45,27])
        {u'dstOffset': 0,
         u'rawOffset': 7200,
         u'status': u'OK',
         u'timeZoneId': u'Europe/Bucharest',
         u'timeZoneName': u'Eastern European Standard Time'}
    
    gettzgoogle('targoviste, ro')
       
    '''                        
    url = 'https://maps.googleapis.com/maps/api/timezone/json'
    if isinstance(loc, str):
        i, avg = 0, False
        if 'i' in kv:
            i = kv['i']
        if 'avg' in kv:
            avg = kv['avg']
        loc = getlatlon(loc, i, avg)
    
    elif not isinstance(loc, tuple):
        loc = tuple(loc)
    
    from .time1 import timestamp   # simple function to convert datetime to timestaamp
    params = dict(location='%f,%f' % loc, timestamp='%s' % timestamp(dt), key=apikey)
    
    res = requests.get(url, params=params)
    res = res.json()
    
    if ret is None:
        return res
        
    return res[ret]
    
    
from geopy import distance

def getdistance(place1, place2, unit='km'):
    '''distance between 2 places'''
    if isinstance(place1, str):
        place1 = getlatlon(place1)
    if isinstance(place2, str):
        place2 = getlatlon(place2)

    res = distance.distance(place1, place2)
    
    if 'km' in unit:
        return res.km
    elif 'mi' in unit:
        return res.miles
    elif 'fe' in unit:
        return res.feet
    elif 'me' in unit:
        return res.meters