### Install and Run Redis Server

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Installs the Redis server on Debian-based systems and starts the Redis server. This is required for tests involving the Redis key/value store.

```bash
$ sudo apt install redis-server
$ redis-server

```

--------------------------------

### Install Documentation Dependencies and Build HTML

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Installs dependencies required for documentation generation and then builds the HTML documentation. Navigate to the 'docs' directory before running 'make html'.

```bash
$ pip install -r requirements-docs.txt
$ cd docs
$ make html

```

--------------------------------

### Install Pytest Dependencies

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Installs the necessary dependencies for running pytest tests. Ensure you have a requirements-pytest.txt file.

```bash
$ pip install -r requirements-pytest.txt

```

--------------------------------

### Get All Callinfo Data

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieve all available information for a given callsign from the country-files.com database. Ensure a LookupLib instance is configured.

```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_all("DH1TW")
```

--------------------------------

### Lookup Prefix Information from Countryfile

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Obtain country-specific data for an amateur radio prefix using the default countryfile.com database. This example looks up information for the prefix 'DH'.

```python
from pyhamtools import LookupLib
myLookupLib = LookupLib()
print myLookupLib.lookup_prefix("DH")
```

--------------------------------

### Download EQSL User List

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the official list of EQSL.cc users. Returns a list of callsigns. Network connectivity is required. This example checks if 'DH1TW' is present in the list.

```python
from pyhamtools.qsl import get_eqsl_users
mylist = get_eqsl_users()
try:
   mylist.index('DH1TW')
except ValueError as e:
   print e
```

--------------------------------

### Lookup Callsign Data from Clublog API

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

This example demonstrates how to retrieve detailed lookup data for a specific amateur radio callsign from the Clublog API at a given point in time. Ensure you have a valid API key and specify the correct lookup type.

```python
from pyhamtools import LookupLib
from datetime import datetime, timezone
my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
timestamp = datetime(year=1962, month=7, day=7, tzinfo=timezone.utc)
print my_lookuplib.lookup_callsign("VK9XO", timestamp)
```

--------------------------------

### Get Home Callsign

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Extract the base callsign by removing country prefixes and activity suffixes. This is useful for normalizing callsigns.

```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_homecall("HC2/DH1TW/P")
```

--------------------------------

### Get Latitude and Longitude for a Callsign

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the latitude and longitude for a given amateur radio callsign. Note that the precision of the returned coordinates can vary significantly depending on the data source.

```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_lat_long("DH1TW")
```

--------------------------------

### Decode Callsign and Get Country Information

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Queries the Callinfo object to retrieve comprehensive information for a given callsign, including country, ADIF ID, continent, and geographical coordinates. Assumes 'cic' is an initialized Callinfo object.

```python
>>> cic.get_all("DH1TW")
{
    'country': 'Fed. Rep. of Germany',
    'adif': 230,
    'continent': 'EU',
    'latitude': 51.0,
    'longitude': 10.0,
    'cqz': 14,
    'ituz': 28
}
```

--------------------------------

### Convert Maidenhead Locator to Latitude/Longitude

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts a Maidenhead locator string into WGS84 latitude and longitude coordinates. By default, it returns the center of the square; set center=False to get the south/western corner.

```python
from pyhamtools.locator import locator_to_latlong
latitude, longitude = locator_to_latlong("JN48QM")
print latitude, longitude
```

--------------------------------

### Initialize Callinfo with LookupLib

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Instantiates a Callinfo object, injecting a pre-configured LookupLib object. This prepares the system for callsign lookups.

```python
>>> from pyhamtools import Callinfo
>>> cic = Callinfo(my_lookuplib)
```

--------------------------------

### Initialize LookupLib for Country-files.com

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Initializes a LookupLib object for the Country-files.com database. The latest database will be downloaded automatically. Requires importing 'LookupLib' from 'pyhamtools'.

```python
>>> from pyhamtools import LookupLib
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
```

--------------------------------

### Set Environment Variables for API Keys

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Configures environment variables for QRZ.com credentials and Clublog API key. Replace placeholders with your actual credentials.

```bash
$ export CLUBLOG_APIKEY="<your API key>"
$ export QRZ_USERNAME="<your qrz.com username>"
$ export QRZ_PWD="<your qrz.com password>"

```

--------------------------------

### Callinfo Class Initialization

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Initializes the Callinfo class with a LookupLib instance and an optional logger.

```APIDOC
## Class: Callinfo

### Description
The `Callinfo` class is designed to retrieve data such as country, latitude, longitude, and CQ Zone for an Amateur Radio callsign. It can be used with any lookup database provided through an instance of `LookupLib`.

### Parameters
* **lookuplib** (`LookupLib`) – An instance of `LookupLib`.
* **logger** (*logging.getLogger*, optional) – A Python logger instance.
```

--------------------------------

### Copy Lookup Data to Redis

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Copies the entire lookup data from a specified source (e.g., Country-files.com PLIST) into a Redis instance. This requires a running Redis instance and the redis-py connector. Old data in Redis with the same prefix will be overwritten.

```python
from pyhamtools import LookupLib
import redis
r = redis.Redis()
my_lookuplib = LookupLib(lookuptype="countryfile")
print my_lookuplib.copy_data_in_redis(redis_prefix="CF", redis_instance=r)
```

--------------------------------

### LookupLib

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

A wrapper class for various Amateur Radio databases (Clublog.org, Country-files.com, QRZ.com) providing a unified interface. It supports direct lookups, or data can be stored and queried from Redis for faster access.

```APIDOC
## class pyhamtools.lookuplib.LookupLib(lookuptype='countryfile', apikey=None, apiv='1.3.3', filename=None, logger=None, username=None, pwd=None, redis_instance=None, redis_prefix=None)

### Description
This class acts as a wrapper for multiple Amateur Radio databases, including Clublog.org (XML and API), Country-files.com, and QRZ.com. It aims to provide a consistent interface for data retrieval. The data can be processed directly from the internet/files or from a Redis instance for improved performance.

### Parameters
#### Path Parameters
- **lookuptype** (str) - Required - Specifies the database source: "clublogxml", "clublogapi", "countryfile", "redis", or "qrz".
- **apikey** (str) - Optional - API key for Clublog.org.
- **username** (str) - Optional - Username for QRZ.com.
- **pwd** (str) - Optional - Password for QRZ.com.
- **apiv** (str, optional) - API version for QRZ.com, defaults to '1.3.3'.
- **filename** (str, optional) - Local file path for Clublog XML or Country-files.com cty.plist.
- **logger** (logging.getLogger, optional) - A Python logger instance.
- **redis_instance** (redis.Redis, optional) - An instance of a Redis client.
- **redis_prefix** (str, optional) - A prefix for identifying lookup data sets within Redis.

### Methods
#### copy_data_in_redis(redis_prefix, redis_instance)

Copies the complete lookup data into Redis, overwriting existing data.

* **Parameters:**
  * **redis_prefix** (str) - Prefix to distinguish data in Redis.
  * **redis_instance** (str) - An instance of Redis.
* **Returns:**
  * **bool** - True if data copied successfully.

### Example
```python
from pyhamtools import LookupLib
import redis
r = redis.Redis()
my_lookuplib = LookupLib(lookuptype="countryfile")
print my_lookuplib.copy_data_in_redis(redis_prefix="CF", redis_instance=r)

# Example using Redis for lookups
my_lookuplib_redis = LookupLib(lookuptype="redis", redis_instance=r, redis_prefix="CF")
print my_lookuplib_redis.lookup_callsign("3D2RI")
```

### Response Example (copy_data_in_redis)
```json
True
```

### Response Example (lookup_callsign via Redis)
```json
{
  "adif": 460,
  "continent": "OC",
  "country": "Rotuma Island",
  "cqz": 32,
  "ituz": 56,
  "latitude": -12.48,
  "longitude": 177.08
}
```
```

--------------------------------

### Download Clublog User List

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the latest official list of Clublog users. Returns a dictionary containing user data like first/last QSO, last LOTW upload, locator, and OQRS status. Network connectivity is required.

```python
from pyhamtools.qsl import get_clublog_users
clublog = get_lotw_users()
clublog['HC2/AL1O']
```

--------------------------------

### Calculate Shortpath and Longpath Heading

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Calculates the shortpath and longpath heading between two Maidenhead grid locators. Ensure the 'pyhamtools.locator' module is imported.

```python
>>> from pyhamtools.locator import calculate_heading, calculate_heading_longpath
>>> calculate_heading("JN48QM", "QF67bf")
74.3136

>>> calculate_heading_longpath("JN48QM", "QF67bf")
254.3136
```

--------------------------------

### pyhamtools.qsl.get_eqsl_users

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the latest official list of EQSL.cc users. Returns a list of callsigns.

```APIDOC
## pyhamtools.qsl.get_eqsl_users

### Description
Downloads the latest official list of EQSL.cc users. Returns a list of callsigns.

### Parameters
* **kwargs** – Optional arguments, including:
  * **url** (*string*) – Download URL.

### Returns
* **list** – List containing the callsigns of EQSL users (unicode).

### Raises
* **IOError** – When network is unavailable, file can’t be downloaded or processed.

### Example
```python
from pyhamtools.qsl import get_eqsl_users
my_list = get_eqsl_users()
print('DH1TW' in my_list)
```
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Executes the project's tests using pytest, including code coverage analysis.

```bash
$ pytest --cov pyhamtools

```

--------------------------------

### Calculate Longpath Heading Between Locators

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the longpath heading in degrees from the first Maidenhead locator to the second. Ensure valid string locators are provided.

```python
from pyhamtools.locator import calculate_heading_longpath
calculate_heading_longpath("JN48QM", "QF67bf")
# Output: 254.3136
```

--------------------------------

### pyhamtools.qsl.get_clublog_users

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the latest official list of Clublog users. Returns a dictionary with user data if available.

```APIDOC
## pyhamtools.qsl.get_clublog_users

### Description
Downloads the latest official list of Clublog users. Returns a dictionary with user data if available.

### Parameters
* **kwargs** – Optional arguments, including:
  * **url** (*string*) – Download URL.

### Returns
* **dict** – Dictionary containing (if data available) the fields: firstqso, lastqso, last-lotw, lastupload (datetime), locator (string) and oqrs (boolean).

### Raises
* **IOError** – When network is unavailable, file can’t be downloaded or processed.

### Example
```python
from pyhamtools.qsl import get_clublog_users
clublog = get_clublog_users()
print(clublog['HC2/AL1O'])
```
```

--------------------------------

### pyhamtools.locator.calculate_sunrise_sunset

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the next sunset and sunrise for a Maidenhead locator at a given date and time.

```APIDOC
## pyhamtools.locator.calculate_sunrise_sunset

### Description
Calculates the next sunset and sunrise for a Maidenhead locator at a given date & time.

### Parameters
#### Path Parameters
* **locator1** (string) - Required - Maidenhead Locator, either 4, 6 or 8 characters
* **calc_date** (datetime, optional) - Starting datetime for the calculations (UTC)

### Returns
A dictionary containing datetimes for morning_dawn, sunrise, evening_dawn, sunset.

### Raises
* **ValueError** – When called with wrong or invalid input arg
* **AttributeError** – When args are not a string

### Example
```pycon
>>> from pyhamtools.locator import calculate_sunrise_sunset
>>> from datetime import datetime, timezone
>>> myDate = datetime(year=2014, month=1, day=1, tzinfo=timezone.utc)
>>> calculate_sunrise_sunset("JN48QM", myDate)
{
    'morning_dawn': datetime.datetime(2014, 1, 1, 6, 36, 51, 710524, tzinfo=datetime.timezone.utc),
    'sunset': datetime.datetime(2014, 1, 1, 16, 15, 23, 31016, tzinfo=datetime.timezone.utc),
    'evening_dawn': datetime.datetime(2014, 1, 1, 15, 38, 8, 355315, tzinfo=datetime.timezone.utc),
    'sunrise': datetime.datetime(2014, 1, 1, 7, 14, 6, 162063, tzinfo=datetime.timezone.utc)
}
```
```

--------------------------------

### Calculate Heading Between Locators

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Calculates the heading between two Maidenhead locators. Ensure both locators are valid.

```python
from pyhamtools.locator import calculate_heading
calculate_heading("JN48QM", "QF67bf")
74.3136
```

--------------------------------

### get_all

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves all available data from the underlying database for a given callsign.

```APIDOC
## Method: get_all

### Description
Looks up a callsign and returns all available data from the underlying database.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** dict
* A dictionary containing callsign-specific data.

### Raises
* **KeyError** – If the callsign could not be identified.

### Example
```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_all("DH1TW")
```

### Note
The content of the returned data depends on the injected `LookupLib` and the used database. For example, Clublog might not provide ITU Zones, while country-files.com does.
```

--------------------------------

### Calculate Sunrise and Sunset Times

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the next sunrise and sunset times for a given Maidenhead locator and date. The date should be a UTC datetime object.

```python
from pyhamtools.locator import calculate_sunrise_sunset
from datetime import datetime, timezone
myDate = datetime(year=2014, month=1, day=1, tzinfo=timezone.utc)
calculate_sunrise_sunset("JN48QM", myDate)
# Output: {
#     'morning_dawn': datetime.datetime(2014, 1, 1, 6, 36, 51, 710524, tzinfo=datetime.timezone.utc),
#     'sunset': datetime.datetime(2014, 1, 1, 16, 15, 23, 31016, tzinfo=datetime.timezone.utc),
#     'evening_dawn': datetime.datetime(2014, 1, 1, 15, 38, 8, 355315, tzinfo=datetime.timezone.utc),
#     'sunrise': datetime.datetime(2014, 1, 1, 7, 14, 6, 162063, tzinfo=datetime.timezone.utc)
# }
```

--------------------------------

### pyhamtools.qsl.get_lotw_users

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the latest official list of ARRL Logbook of the World (LOTW) users. Returns a dictionary with callsigns and last upload dates.

```APIDOC
## pyhamtools.qsl.get_lotw_users

### Description
Downloads the latest official list of ARRL Logbook of the World (LOTW) users. Returns a dictionary with callsigns and last upload dates.

### Parameters
* **kwargs** – Optional arguments, including:
  * **url** (*string*) – Download URL.

### Returns
* **dict** – Dictionary containing the callsign (unicode) and date of the last LOTW upload (datetime).

### Raises
* **IOError** – When network is unavailable, file can’t be downloaded or processed.
* **ValueError** – Raised when data from file can’t be read.

### Example
```python
from pyhamtools.qsl import get_lotw_users
my_dict = get_lotw_users()
print(my_dict['DH1TW'])
```
```

--------------------------------

### Convert Latitude/Longitude to Maidenhead Locator

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts given latitude and longitude coordinates into a Maidenhead locator string. Ensure latitude and longitude are provided in decimal degrees.

```python
from pyhamtools.locator import latlong_to_locator
latitude = 48.5208333
longitude = 9.375
latlong_to_locator(latitude, longitude)
```

--------------------------------

### Calculate Sunrise and Sunset

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Calculates the sunrise and sunset times for a given locator and date. Imports 'calculate_sunrise_sunset' from 'pyhamtools.locator' and 'datetime' from the 'datetime' module.

```python
>>> from pyhamtools.locator import calculate_sunrise_sunset
>>> from datetime import datetime
>>> my_locator = "JN48QM"
>>> my_date = datetime(year=2015, month=1, day=1)
>>> data = calculate_sunrise_sunset(my_locator, my_date)
>>> print("Sunrise: " + data['sunrise'].strftime("%H:%MZ") + ", Sunset: " + data['sunset'].strftime("%H:%MZ"))
```

--------------------------------

### Download LOTW User List

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Downloads the latest official list of ARRL Logbook of the World (LOTW) users. Returns a dictionary mapping callsigns to their last LOTW upload datetime. Network connectivity is required.

```python
from pyhamtools.qsl import get_lotw_users
mydict = get_lotw_users()
mydict['DH1TW']
```

--------------------------------

### Convert Frequency to Band and Mode

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts a frequency in kHz to its corresponding IARU band and mode. Raises a KeyError for invalid or out-of-band frequencies. Supported modes include CW, USB, LSB, and DIGITAL.

```python
from pyhamtools.utils import freq_to_band
print freq_to_band(14005.3)
```

--------------------------------

### Perform Callsign Lookup Using Redis

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Instantiates a LookupLib object to perform callsign lookups using data stored in Redis. This is an efficient method for frequent lookups once data is loaded into Redis.

```python
from pyhamtools import LookupLib
import redis
r = redis.Redis()
my_lookuplib = LookupLib(lookuptype="redis", redis_instance=r, redis_prefix="CF")
my_lookuplib.lookup_callsign("3D2RI")
```

--------------------------------

### Calculate Longpath Distance Between Locators

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the longpath distance in kilometers between two Maidenhead locators. Input locators must be valid strings.

```python
from pyhamtools.locator import calculate_distance_longpath
calculate_distance_longpath("JN48QM", "QF67bf")
# Output: 23541.5867
```

--------------------------------

### Calculate Shortpath Distance Between Locators

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Use this function to find the distance in kilometers between two Maidenhead locators using the shortpath calculation. Ensure inputs are valid string locators.

```python
from pyhamtools.locator import calculate_distance
calculate_distance("JN48QM", "QF67bf")
# Output: 16466.413
```

--------------------------------

### pyhamtools.locator.calculate_heading

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the heading from the first to the second Maidenhead locator in degrees.

```APIDOC
## pyhamtools.locator.calculate_heading

### Description
Calculates the heading from the first to the second locator.

### Parameters
#### Path Parameters
* **locator1** (string) - Required - Locator, either 4, 6 or 8 characters
* **locator2** (string) - Required - Locator, either 4, 6 or 6 characters

### Returns
Heading in degrees (float)

### Raises
* **ValueError** – When called with wrong or invalid input arg
* **AttributeError** – When args are not a string

### Example
```pycon
>>> from pyhamtools.locator import calculate_heading
>>> calculate_heading("JN48QM", "QF67bf")
74.3136
```
```

--------------------------------

### pyhamtools.locator.calculate_heading_longpath

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the long path heading from the first to the second Maidenhead locator in degrees.

```APIDOC
## pyhamtools.locator.calculate_heading_longpath

### Description
Calculates the heading from the first to the second locator (long path).

### Parameters
#### Path Parameters
* **locator1** (string) - Required - Locator, either 4, 6 or 8 characters
* **locator2** (string) - Required - Locator, either 4, 6 or 8 characters

### Returns
Long path heading in degrees (float)

### Raises
* **ValueError** – When called with wrong or invalid input arg
* **AttributeError** – When args are not a string

### Example
```pycon
>>> from pyhamtools.locator import calculate_heading_longpath
>>> calculate_heading_longpath("JN48QM", "QF67bf")
254.3136
```
```

--------------------------------

### lookup_prefix

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves lookup data for a given amateur radio prefix and optional timestamp. This method is available for clublogxml, redis, qrz.com, and countryfile lookup types.

```APIDOC
## lookup_prefix(prefix, timestamp=None)

### Description
Returns lookup data of a Prefix. This method is available for clublogxml, redis, qrz.com, and countryfile lookup types.

### Parameters
#### Path Parameters
- **prefix** (string) - Required - Prefix of a Amateur Radio callsign
- **timestamp** (datetime) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **dict** - Dictionary containing the country specific data of the Prefix

### Raises
- **KeyError** – No matching Prefix found
- **APIKeyMissingError** – API Key for Clublog missing or incorrect

### Example
```python
from pyhamtools import LookupLib
myLookupLib = LookupLib()
print(myLookupLib.lookup_prefix("DH"))
```
```

--------------------------------

### Callsign Lookup using Country File

Source: https://github.com/dh1tw/pyhamtools/blob/master/README.md

Performs a callsign lookup using the AD1C's Country Files. Initializes LookupLib with 'countryfile' type and then uses Callinfo to retrieve all available information for a given callsign.

```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_all("DH1TW")
    {
        'country': 'Fed. Rep. of Germany',
        'adif': 230,
        'continent': 'EU',
        'latitude': 51.0,
        'longitude': 10.0,
        'cqz': 14,
        'ituz': 28
    }
```

--------------------------------

### pyhamtools.frequency.freq_to_band

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts a frequency in kHz into the corresponding IARU band plan band and mode. Returns a dictionary with the band and mode.

```APIDOC
## pyhamtools.frequency.freq_to_band

### Description
Converts a frequency in kHz into the corresponding IARU band plan band and mode. Returns a dictionary with the band and mode.

### Parameters
* **frequency** (*float*) – Required - Frequency in kHz.

### Returns
* **dict** – Dictionary containing the band (int) and mode (str).

### Raises
* **KeyError** – Wrong frequency or out of band.

### Example
```python
from pyhamtools.utils import freq_to_band
print(freq_to_band(14005.3))
```

### Note
Modes are: CW, USB, LSB, DIGITAL.
```

--------------------------------

### pyhamtools.locator.latlong_to_locator

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts WGS84 coordinates (latitude and longitude) into the corresponding Maidenhead Locator.

```APIDOC
## pyhamtools.locator.latlong_to_locator

### Description
Converts WGS84 coordinates into the corresponding Maidenhead Locator.

### Parameters
#### Path Parameters
* **latitude** (float) - Required - Latitude
* **longitude** (float) - Required - Longitude
* **precision** (int, optional) - 4, 6, 8, 10 chars (default 6)

### Returns
Maidenhead locator (string)

### Raises
* **ValueError** – When called with wrong or invalid input args
* **TypeError** – When args are non float values
```

--------------------------------

### get_cqz

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the CQ Zone for a given callsign.

```APIDOC
## Method: get_cqz

### Description
Returns the CQ Zone for a given Amateur Radio callsign.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** int
* Contains the callsign's CQ Zone.

### Raises
* **KeyError** – If no CQ Zone is found for the callsign.
```

--------------------------------

### Lookup CQ Zone Exception

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Checks the Clublog XML database for CQ Zone exceptions for a given callsign. This method is available for clublogxml and redis lookup types.

```pycon
>>> from pyhamtools import LookupLib
>>> my_lookuplib = LookupLib(lookuptype="clublogxml", apikey="myapikey")
>>> print my_lookuplib.lookup_zone_exception("DP0GVN")
38
```

--------------------------------

### get_ituz

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the ITU Zone for a given callsign.

```APIDOC
## Method: get_ituz

### Description
Returns the ITU Zone for a given Amateur Radio callsign.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** int
* Contains the callsign's ITU Zone.

### Raises
* **KeyError** – If no ITU Zone is found for the callsign.

### Note
Currently, only the Country-files.com lookup database contains ITU Zones.
```

--------------------------------

### Convert Frequency to Band (Deprecated)

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts a frequency in kHz to its corresponding band and mode according to the IARU bandplan. This function has been moved to pyhamtools.frequency in version 0.4.1 and is deprecated in this module.

```python
def freq_to_band(freq):
    # Function implementation details would be here
    pass
```

--------------------------------

### pyhamtools.locator.calculate_distance_longpath

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the longpath distance between two Maidenhead locators in kilometers.

```APIDOC
## pyhamtools.locator.calculate_distance_longpath

### Description
Calculates the (longpath) distance between two Maidenhead locators.

### Parameters
#### Path Parameters
* **locator1** (string) - Required - Locator, either 4, 6 or 8 characters
* **locator2** (string) - Required - Locator, either 4, 6 or 8 characters

### Returns
Distance in km (float)

### Raises
* **ValueError** – When called with wrong or invalid input arg
* **AttributeError** – When args are not a string

### Example
```pycon
>>> from pyhamtools.locator import calculate_distance_longpath
>>> calculate_distance_longpath("JN48QM", "QF67bf")
23541.5867
```
```

--------------------------------

### pyhamtools.locator.locator_to_latlong

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Converts a Maidenhead locator string into its corresponding WGS84 coordinates (latitude and longitude). It can return either the center of the square or the south/western corner.

```APIDOC
## pyhamtools.locator.locator_to_latlong

### Description
Converts a Maidenhead locator string into its corresponding WGS84 coordinates (latitude and longitude). It can return either the center of the square or the south/western corner.

### Parameters
* **locator** (*string*) – Required - Locator, either 4, 6 or 8 characters.
* **center** (*bool*) – Optional - Center of (sub)square. By default True. If False, the south/western corner will be returned.

### Returns
* **tuple (float, float)** – Latitude, Longitude

### Raises
* **ValueError** – When called with wrong or invalid Maidenhead locator string.
* **TypeError** – When arg is not a string.

### Example
```python
from pyhamtools.locator import locator_to_latlong
latitude, longitude = locator_to_latlong("JN48QM")
print latitude, longitude
```
```

--------------------------------

### lookup_zone_exception

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the CQ Zone exception for a given callsign and optional timestamp. This method is available for clublogxml, redis, and qrz.com lookup types.

```APIDOC
## lookup_zone_exception(callsign, timestamp=None)

### Description
Returns a CQ Zone if an exception exists for the given callsign. This method is available for clublogxml, redis, and qrz.com lookup types.

### Parameters
#### Path Parameters
- **callsign** (string) - Required - Amateur radio callsign
- **timestamp** (datetime) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **int** - Value of the the CQ Zone exception which exists for this callsign (at the given time)

### Raises
- **KeyError** – No matching callsign found
- **APIKeyMissingError** – API Key for Clublog missing or incorrect
```

--------------------------------

### pyhamtools.locator.calculate_distance

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Calculates the shortpath distance between two Maidenhead locators in kilometers.

```APIDOC
## pyhamtools.locator.calculate_distance

### Description
Calculates the (shortpath) distance between two Maidenhead locators.

### Parameters
#### Path Parameters
* **locator1** (string) - Required - Locator, either 4, 6 or 8 characters
* **locator2** (string) - Required - Locator, either 4, 6 or 8 characters

### Returns
Distance in km (float)

### Raises
* **ValueError** – When called with wrong or invalid maidenhead locator strings
* **AttributeError** – When args are not a string

### Example
```pycon
>>> from pyhamtools.locator import calculate_distance
>>> calculate_distance("JN48QM", "QF67bf")
16466.413
```
```

--------------------------------

### get_homecall

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Strips off country prefixes and activity suffixes from a callsign to return the base home call.

```APIDOC
## Method: get_homecall

### Description
Strips off country prefixes (e.g., HC2/) and activity suffixes (e.g., /P) from a callsign to return the base home call.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.

### Returns
* **Return type:** str
* The callsign without country/activity pre/suffixes.

### Raises
* **ValueError** – If no callsign is found in the string.

### Example
```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_homecall("HC2/DH1TW/P")
```
```

--------------------------------

### lookup_entity

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves lookup data for a given ADIF Entity identifier. This method is available for clublogxml, redis, clublogapi, qrz.com, and countryfile lookup types.

```APIDOC
## lookup_entity(entity=None)

### Description
Returns lookup data of an ADIF Entity. This method is available for clublogxml, redis, clublogapi, qrz.com, and countryfile lookup types.

### Parameters
#### Path Parameters
- **entity** (int) - Required - ADIF identifier of country

### Returns
- **dict** - Dictionary containing the country specific data

### Raises
- **KeyError** – No matching entity found

### Example
```python
from pyhamtools import LookupLib
my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
print(my_lookuplib.lookup_entity(273))
```
```

--------------------------------

### Check Invalid Operation with Clublog XML

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Use this snippet to check if an amateur radio operation is considered invalid in the Clublog XML database for a given callsign and optional timestamp. It raises a KeyError if no matching callsign is found.

```python
from pyhamtools import LookupLib
from datetime import datetime, timezone
my_lookuplib = LookupLib(lookuptype="clublogxml", apikey="myapikey")
print my_lookuplib.is_invalid_operation("5W1CFN")
try:
  timestamp = datetime(year=2012, month=1, day=31, tzinfo=timezone.utc)
  my_lookuplib.is_invalid_operation("5W1CFN", timestamp)
except KeyError:
  print "Seems to be invalid operation before 31.1.2012"
```

--------------------------------

### Calculate Distance between WGS84 Coordinates

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/examples.md

Calculates the distance between two WGS84 coordinates by first converting latitude and longitude to Maidenhead locators. Requires importing 'calculate_distance' and 'latlong_to_locator' from 'pyhamtools.locator'.

```python
>>> from pyhamtools.locator import calculate_distance, latlong_to_locator
>>> locator1 = latlong_to_locator(48.52, 9.375)
>>> locator2 = latlong_to_locator(-32.77, 152.125)
>>> distance = calculate_distance(locator1, locator2)
>>> print("%.1fkm" % distance)
```

--------------------------------

### lookup_callsign

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves lookup data for a given callsign and optional timestamp. This method is available for clublogxml, redis, clublogapi, qrz.com, and countryfile lookup types.

```APIDOC
## lookup_callsign(callsign=None, timestamp=None)

### Description
Returns lookup data if an exception exists for a callsign. This method is available for clublogxml, redis, clublogapi, qrz.com, and countryfile lookup types.

### Parameters
#### Path Parameters
- **callsign** (string) - Optional - Amateur radio callsign
- **timestamp** (datetime) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **dict** - Dictionary containing the country specific data of the callsign

### Raises
- **KeyError** – No matching callsign found
- **APIKeyMissingError** – API Key for Clublog missing or incorrect

### Example
```python
from pyhamtools import LookupLib
from datetime import datetime, timezone
my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
timestamp = datetime(year=1962, month=7, day=7, tzinfo=timezone.utc)
print(my_lookuplib.lookup_callsign("VK9XO", timestamp))
```
```

--------------------------------

### get_country_name

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the name of the country where the callsign is located.

```APIDOC
## Method: get_country_name

### Description
Returns the name of the country where the callsign is located.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** str
* The name of the country.

### Raises
* **KeyError** – If no country is found for the callsign.

### Note
Country names may vary slightly between databases (e.g., Country-files.com vs. Clublog).
```

--------------------------------

### is_valid_callsign

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Checks if a provided string is a valid amateur radio callsign. This function can also consider a timestamp for validation.

```APIDOC
## is_valid_callsign(callsign, timestamp=None)

### Description
Checks if a callsign is valid.

### Parameters
#### Path Parameters
- **callsign** (str) - Required - Amateur Radio callsign
- **timestamp** (datetime, optional) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **bool** - True if the callsign is valid, False otherwise.

### Example
```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.is_valid_callsign("DH1TW")
```

### Response Example
```json
True
```
```

--------------------------------

### Check if a Callsign is Valid

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Validates whether a given string is a recognized amateur radio callsign. This function checks against available databases.

```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.is_valid_callsign("DH1TW")
```

--------------------------------

### get_continent

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the continent identifier for a given callsign.

```APIDOC
## Method: get_continent

### Description
Returns the continent identifier for a given Amateur Radio callsign.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** str
* The identified continent.

### Raises
* **KeyError** – If no continent is found for the callsign.

### Note
Continent identifiers used: EU (Europe), NA (North America), SA (South America), AS (Asia), AF (Africa), OC (Oceania), AN (Antarctica).
```

--------------------------------

### get_lat_long

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the Latitude and Longitude for a given amateur radio callsign. It can optionally take a timestamp for historical lookups. Note that the precision of the returned coordinates can vary.

```APIDOC
## get_lat_long(callsign, timestamp=None)

### Description
Returns Latitude and Longitude for a callsign. The precision may vary as it often uses capital city coordinates.

### Parameters
#### Path Parameters
- **callsign** (str) - Required - Amateur Radio callsign
- **timestamp** (datetime, optional) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **dict** - Containing Latitude and Longitude

### Raises
- **KeyError** - No data found for callsign

### Example
```python
from pyhamtools import LookupLib, Callinfo
my_lookuplib = LookupLib(lookuptype="countryfile")
cic = Callinfo(my_lookuplib)
cic.get_lat_long("DH1TW")
```

### Response Example
```json
{
    "latitude": 51.0,
    "longitude": -10.0
}
```
```

--------------------------------

### is_invalid_operation

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Checks if an operation is known to be invalid for a given callsign and optional timestamp. This method is available for clublogxml and countryfile lookup types.

```APIDOC
## is_invalid_operation(callsign, timestamp=None)

### Description
Returns True if an operation is known as invalid for the given callsign and optional timestamp. This method is available for clublogxml and countryfile lookup types.

### Parameters
#### Path Parameters
- **callsign** (string) - Required - Amateur Radio callsign
- **timestamp** (datetime) - Optional - datetime in UTC (tzinfo=timezone.utc)

### Returns
- **bool** - True if a record exists for this callsign (at the given time)

### Raises
- **KeyError** – No matching callsign found
- **APIKeyMissingError** – API Key for Clublog missing or incorrect

### Example
```python
from pyhamtools import LookupLib
from datetime import datetime, timezone
my_lookuplib = LookupLib(lookuptype="clublogxml", apikey="myapikey")
print(my_lookuplib.is_invalid_operation("5W1CFN"))
try:
  timestamp = datetime(year=2012, month=1, day=31, tzinfo=timezone.utc)
  my_lookuplib.is_invalid_operation("5W1CFN", timestamp)
except KeyError:
  print("Seems to be invalid operation before 31.1.2012")
```
```

--------------------------------

### get_adif_id

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieves the ADIF ID of the country associated with a given callsign.

```APIDOC
## Method: get_adif_id

### Description
Returns the ADIF ID of the country for a given Amateur Radio callsign.

### Parameters
* **callsign** (*str*) – The Amateur Radio callsign.
* **timestamp** (*datetime*, optional) – A datetime object in UTC (tzinfo=timezone.utc).

### Returns
* **Return type:** int
* Contains the country ADIF ID.

### Raises
* **KeyError** – If no country is found for the callsign.
```

--------------------------------

### Lookup ADIF Entity Data

Source: https://github.com/dh1tw/pyhamtools/blob/master/docs/source/reference.md

Retrieve country-specific data using an ADIF Entity identifier. This snippet queries the Clublog API for entity ID 273, which corresponds to Turkmenistan.

```python
from pyhamtools import LookupLib
my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
print my_lookuplib.lookup_entity(273)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.