Use Cases:

Creating aware datetime objects

check out the example script in examples/aware_datetime.py

Getting a location’s time zone offset

check out the example script in examples/get_offset.py

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] \
    [--zone-id-dtype {uint8,uint16}]

Per default the script parses the combined.json from its own parent directory (timezonefinder) into data files inside its parent directory. Use --zone-id-dtype (or set TIMEZONEFINDER_ZONE_ID_DTYPE) when your dataset contains more than 256 distinct timezones so the generated binaries use uint16 storage instead of the default uint8. How to use the timezonefinder package with data files from another location is described HERE.

Data update shell script

The included update_data.sh shell script simplifies downloading the latest version of timezone-boundary-builder data and parsing in with file_converter.py. It is non-interactive and controlled entirely via command line flags:

/bin/bash /path/to/timezonefinder/update_data.sh [--dataset=full|same-since-now] [--with-oceans] [--rm-tmp]

Without the --with-oceans flag the dataset WITHOUT ocean timezones is used. This is useful if you do not require ocean timezones and want to have smaller data files.