coord2loc 0.0.2

Convert latitude and longitude into localities like countries and states

coord2loc

Convert latitude and longitude coordinates into localities like countries and states.

Overview

coord2loc is a Python library that allows you to convert geographic coordinates (latitude and longitude) into human-readable locations, such as countries and administrative regions (states, provinces, etc.). It uses polygon data from geoBoundaries.org to accurately map coordinates to their corresponding locations.

Installation

pip install coord2loc_usa

Usage

Basic Usage

from coord2loc import Coordinate, locate

# Create a coordinate (New York City)
coordinate = Coordinate(latitude=40.7128, longitude=-74.0060)

# Locate the coordinate
location = locate(coordinate)

# Print the result
print(f"Country: {location.country}")
print(f"Administrative Region: {location.administrative_region}")
# Output:
# Country: USA
# Administrative Region: New York

Handling Unknown Locations

By default, the locate function returns None for coordinates that cannot be found (e.g., in oceans):

from coord2loc import Coordinate, locate

# Coordinate in the Atlantic Ocean
coordinate = Coordinate(latitude=30.0, longitude=-40.0)

# Locate the coordinate
location = locate(coordinate)

# Check if location was found
if location is None:
    print("Location not found")
else:
    print(f"Country: {location.country}")
    print(f"Administrative Region: {location.administrative_region}")
# Output:
# Location not found

Configuring Behavior with Options

You can customize the behavior of the locate function using the Options class:

from coord2loc import Coordinate, Options, locate, CoordinateNotFound

# Create a coordinate in the ocean
coordinate = Coordinate(latitude=30.0, longitude=-40.0)

# Configure to raise an exception when location is not found
options = Options(raise_on_not_found=True)

try:
    location = locate(coordinate, options)
    print(f"Country: {location.country}")
    print(f"Administrative Region: {location.administrative_region}")
except CoordinateNotFound as e:
    print(f"Error: {e}")
# Output:
# Error: Coordinate (30.0, -40.0) could not be located

API Reference

Classes

Coordinate

A named tuple representing a geographic coordinate.

• latitude (float): The latitude value (-90 to 90)
• longitude (float): The longitude value (-180 to 180)

Location

A named tuple representing a location.

• country (str): The country name
• administrative_region (str): The administrative region (state, province, etc.)

Options

A named tuple for configuring the behavior of the locate function.

• raise_on_invalid (bool, default=True): Whether to raise an exception for invalid coordinates
• raise_on_not_found (bool, default=False): Whether to raise an exception when a location cannot be found

Functions

locate(coordinate, options=Options())

Locates a coordinate and returns the corresponding location.

• coordinate (Coordinate): The coordinate to locate
• options (Options, optional): Configuration options
• Returns: A Location object if found, otherwise None (unless raise_on_not_found is True)

Exceptions

InvalidCoordinate

Raised when a coordinate is invalid (outside the valid range).

CoordinateNotFound

Raised when a coordinate cannot be located (when raise_on_not_found is True).

Attribution

• geoBoundaries.org (CC BY 4.0): This library embeds polygons derived from the data made available by geoBoundaries.
• coord2state (MIT): This library is essentially a python port Austin Henley's coord2state javascript library. Thank you Austin!