Metadata-Version: 2.4
Name: django-ip2location-timezone
Version: 2.0.0
Summary: Django IP2Location Timezone is a simple Django package that can help you easily display your website visitor the time according to their location.
Home-page: https://github.com/ip2location/django-ip2location-timezone
Author: IP2Location
Author-email: support@ip2location.com
License: MIT License
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Description-Content-Type: text/markdown
License-File: LICENSE.TXT
License-File: AUTHORS
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: summary

# Django IP2Location Time Zone

Django IP2Location Time Zone package enables you easily display your website visitor the time based on their geo location derived from the IP address. This package uses **[IP2Location.io API](https://www.ip2location.io/ip2location-documentation)** for IP lookup and time zone information.

## Requirements

1. Python 2.7 and above.
2. Django 5.1 and above.
3.  **[IP2Location.io](https://www.ip2location.io/pricing)** API Key. You can get a trial API key from [IP2Location.io](https://www.ip2location.io/sign-up?ref=5&trial=1).

    > Note: The time zone information is only available with IP2Location.io API Plus plan and above.

## Quick Start

1. Install this package from PyPI: 
	```bash
	pip install django-ip2location-timezone
	```
	
2. Add "*ip2location_timezone*" to your INSTALLED_APPS setting in settings.py:
    ```python
    INSTALLED_APPS = (
      ...
      'ip2location_timezone',
    )
   ```
   
3. Add "*IP2locationTimezoneMiddleware*" to your MIDDLEWARE in settings.py:
   ```python
    MIDDLEWARE = (
      ...
      'ip2location_timezone.middleware.IP2locationTimezoneMiddleware',
    )
   ```
   
4. Add your **[IP2Location.io API](https://www.ip2location.io/ip2location-documentation)** API Key in settings.py:
    ```python
    IP2LOCATION_API_KEY = 'YOUR_API_KEY'
    ```
   
5. In your template, add the following code to display the user time zone and current time:
	```html
	{% load tz %}
	{% localtime on %}
		{% get_current_timezone as TIME_ZONE %}
		Your timezone is {{ TIME_ZONE }}.<br/><br/>
		It is {% now "DATETIME_FORMAT" %}
	{% endlocaltime %}
	```

## Upgrading to 2.0.0

Version 2.0.0 contains breaking changes. Please read this section before upgrading from 1.x.

### Breaking changes

- **IP2Location.io API replaces the IP2Location Web Service.** The plugin now queries the [IP2Location.io](https://www.ip2location.io) API. The API key setting name is unchanged (`IP2LOCATION_API_KEY`), but you will likely need to [get a new API key](https://www.ip2location.io) from IP2Location.io and update its value.
- **Dropped support for Django 1.11 and 2.2.** Supported versions are now Django 5.1 and 6.0.

### Behavior changes

- **API errors no longer raise exceptions.** If the lookup fails (timeout, invalid key, quota exceeded, malformed response), the fields fall back to their default values.
- **Request fields now have default values.** The following fields are always present on the request object:

  | Field | Default |
  |-------|---------|
  | `country_code`    | `NO_DATA` |
  | `country_name`    | `NO_DATA` |
  | `region_name`    | `NO_DATA` |
  | `city_name`    | `NO_DATA` |
  | `latitude`    | `NO_DATA` |
  | `longitude`    | `NO_DATA` |
  | `zip_code`    | `NO_DATA` |
  | `time_zone`    | `NO_DATA` |
  | `olson_time_zone` | `PLAN_NOT_SUPPORTED` |
  | `current_time` | `PLAN_NOT_SUPPORTED` |
  | `gmt_offset` | `PLAN_NOT_SUPPORTED` |
  | `is_dst` | `PLAN_NOT_SUPPORTED` |

### Upgrade steps

1. Upgrade the package:

   ```bash
   pip install --upgrade django-ip2location-timezone
   ```

2. Replace your API key in settings with a key from IP2Location.io:

   ```python
   IP2LOCATION_API_KEY = "your-ip2location-io-api-key"
   ```

3. If your code checks for missing or `None` field values, update it to handle the new defaults.

If you need to stay on the old behavior for now, pin the previous version:

```bash
pip install "django-ip2location-timezone<2.0"
```

## Support

Email: [support@ip2location.com](mailto:support@ip2location.com).

URL: [https://www.ip2location.com](https://www.ip2location.com/)
