geopointdb 1.1.0

Offline geolocation and geocoding package using SQLite (~200000+ world cities)

GeoPointDB

GeoPointDB is a lightweight Python package for fast offline geolocation lookups. It provides an easy way to find city coordinates (latitude and longitude) using a local SQLite database containing approximately 200000+ world cities.

Features

• Offline First: No internet connection required after installation
• Fast Lookups: Uses SQLite for efficient querying
• Simple API: Easy-to-use Python interface
• Minimal Dependencies: Uses only Python standard library
• Auto-setup: Automatically initializes the database on first use

Installation

You can install GeoPointDB using pip:

pip install geopointdb

Quick Start

Basic Usage

from geopointdb.getpoint import LatLonFinder

# Initialize the finder (automatically sets up the database on first run)
finder = LatLonFinder()

# Find cities by name (case-insensitive partial match)
cities = finder.find_city('New York')
for city in cities:
    print(f"{city['city']}, {city['country']}: {city['lat']}, {city['lon']}")

# Get coordinates for a specific city
coordinates = finder.get_coordinates('London')
if coordinates:
    lat, lon = coordinates
    print(f"London coordinates: {lat}, {lon}")

# Don't forget to close the connection when done
finder.close()

Using Context Manager

For better resource management, you can use the context manager pattern:

with LatLonFinder() as finder:
    coords = finder.get_coordinates('Tokyo')
    print(f"Tokyo coordinates: {coords}")

API Reference

LatLonFinder Class

__init__(self, db_file=None, csv_file=None)

Initialize the finder with optional custom database or CSV file paths.

• db_file: Path to SQLite database file (default: worldcities.db in package directory)
• csv_file: Path to CSV file for initial database creation (if database doesn't exist)

find_city(self, city_name)

Find cities by name (case-insensitive partial match).

• city_name: Full or partial city name to search for
• Returns: List of dictionaries containing city information (city, country, lat, lon)

get_coordinates(self, city_name)

Get coordinates for a specific city (exact match).

• city_name: Exact city name (case-insensitive)
• Returns: Tuple of (latitude, longitude) or None if not found

close(self)

Close the database connection. Always call this when done with the finder.

Database

The package includes a SQLite database (worldcities.db) with approximately 200000+ world cities. The database is automatically created from the included CSV file on first use if it doesn't exist.

Database Schema

The cities table has the following columns:

• city: City name
• country: Country name
• lat: Latitude (decimal degrees)
• lon: Longitude (decimal degrees)

Development

Prerequisites

• Python 3.7+
• Git

Setup

1. Clone the repository:

   git clone https://github.com/Pulkit-Py/geopointdb.git
   cd geopointdb
   

2. Create and activate a virtual environment:

   # Windows
   python -m venv venv
   .\venv\Scripts\activate
   
   # Unix/macOS
   python3 -m venv venv
   source venv/bin/activate
   

3. Install development dependencies:

   pip install -r requirements-dev.txt
   pip install -e .
   

Running Tests

pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

For support, please open an issue on the GitHub repository.

Acknowledgements

• World cities data from geonames.org

Support

If you found this project helpful, consider:

• Giving it a ⭐ on GitHub
• Following me on social media
• Sharing it with others who might find it useful

---

Made with ❤️ by Pulkit-Py From 🇮🇳 India