Use Cases:

Creating aware datetime objects

# first pip install pytz
from pytz import timezone, utc
from pytz.exceptions import UnknownTimeZoneError

# tzinfo has to be None (means naive)
naive_datetime = YOUR_NAIVE_DATETIME

try:
    tz = timezone(timezone_name)
    aware_datetime = naive_datetime.replace(tzinfo=tz)
    aware_datetime_in_utc = aware_datetime.astimezone(utc)

    naive_datetime_as_utc_converted_to_tz = tz.localize(naive_datetime)

except UnknownTimeZoneError:
    pass  # {handle error}

Getting a location’s time zone offset

from datetime import datetime
from pytz import timezone, utc


def get_offset(*, lat, lng):
    """
    returns a location's time zone offset from UTC in minutes.
    """

    today = datetime.now()
    tz_target = timezone(tf.certain_timezone_at(lng=lng, lat=lat))
    # ATTENTION: tz_target could be None! handle error case
    today_target = tz_target.localize(today)
    today_utc = utc.localize(today)
    return (today_utc - today_target).total_seconds() / 60


bergamo = {"lat": 45.69, "lng": 9.67}
minute_offset = get_offset(**bergamo)

also see the pytz Doc.

Django

querying the timezone name in a Django view:

def find_timezone(request, lat, lng):
    lat = float(lat)
    lng = float(lng)
    try:
        timezone_name = tf.timezone_at(lng=lng, lat=lat)
    except ValueError:
        # the coordinates were out of bounds
        pass  # {handle error}
    if timezone_name is None:
        # no timezone matched
        ...

    # do something with timezone_name
    ...

Use other data

File converter script

This package includes the file_converter.py script to parse timezone data and compile the binary data files required by the timezonefinder package. This script is built for processing the specific geojson format of the default data: timezone-boundary-builder. Any other data in this format can also be parsed:

python /path/to/timezonefinder/scripts/file_converter.py [-inp /path/to/input.json] [-out /path/to/output_folder]

Per default the script parses the combined.json from its own parent directory (timezonefinder) into data files inside its parent directory. How to use the timezonefinder package with data files from another location is described HERE.

Data parsing shell script

The included parse_data.sh shell script simplifies downloading the latest version of timezone-boundary-builder data and parsing in with file_converter.py. It supports downloading and parsing the timezone-boundary-builder version WITHOUT ocean timezones. This is useful if you do not require ocean timezones and want to have smaller data files.

/bin/bash  /path/to/timezonefinder/parse_data.sh