# GeoPointDB
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
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:
```bash
pip install geopointdb
```
## Quick Start
### Basic Usage
```python
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:
```python
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:
```bash
git clone https://github.com/Pulkit-Py/geopointdb.git
cd geopointdb
```
2. Create and activate a virtual environment:
```bash
# Windows
python -m venv venv
.\venv\Scripts\activate
# Unix/macOS
python3 -m venv venv
source venv/bin/activate
```
3. Install development dependencies:
```bash
pip install -r requirements-dev.txt
pip install -e .
```
### Running Tests
```bash
pytest
```
## License
This project is licensed under the MIT License - see the [LICENSE](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](https://github.com/Pulkit-Py/geopointdb/issues).
## Acknowledgements
- World cities data from [geonames.org](https://www.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
---
<p align="center">Made with ❤️ by <a href="https://github.com/Pulkit-Py">Pulkit-Py</a> From 🇮🇳 India</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/Pulkit-Py/geopointdb",
"name": "geopointdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "geolocation, geocoding, sqlite, offline, world cities",
"author": "Pulkit Saini",
"author_email": "Pulkit Saini <pulkitsaini127@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/0a/6c47fae8c2508af2059b56fca688edf1a1e9a5d99bfcefcf6e7cd5e060d4/geopointdb-1.2.0.tar.gz",
"platform": null,
"description": "# GeoPointDB\r\n\r\n[](https://www.python.org/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nGeoPointDB 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.\r\n\r\n## Features\r\n\r\n- **Offline First**: No internet connection required after installation\r\n- **Fast Lookups**: Uses SQLite for efficient querying\r\n- **Simple API**: Easy-to-use Python interface\r\n- **Minimal Dependencies**: Uses only Python standard library\r\n- **Auto-setup**: Automatically initializes the database on first use\r\n\r\n## Installation\r\n\r\nYou can install GeoPointDB using pip:\r\n\r\n```bash\r\npip install geopointdb\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom geopointdb.getpoint import LatLonFinder\r\n\r\n# Initialize the finder (automatically sets up the database on first run)\r\nfinder = LatLonFinder()\r\n\r\n# Find cities by name (case-insensitive partial match)\r\ncities = finder.find_city('New York')\r\nfor city in cities:\r\n print(f\"{city['city']}, {city['country']}: {city['lat']}, {city['lon']}\")\r\n\r\n# Get coordinates for a specific city\r\ncoordinates = finder.get_coordinates('London')\r\nif coordinates:\r\n lat, lon = coordinates\r\n print(f\"London coordinates: {lat}, {lon}\")\r\n\r\n# Don't forget to close the connection when done\r\nfinder.close()\r\n```\r\n\r\n### Using Context Manager\r\n\r\nFor better resource management, you can use the context manager pattern:\r\n\r\n```python\r\nwith LatLonFinder() as finder:\r\n coords = finder.get_coordinates('Tokyo')\r\n print(f\"Tokyo coordinates: {coords}\")\r\n```\r\n\r\n## API Reference\r\n\r\n### `LatLonFinder` Class\r\n\r\n#### `__init__(self, db_file=None, csv_file=None)`\r\nInitialize the finder with optional custom database or CSV file paths.\r\n\r\n- `db_file`: Path to SQLite database file (default: `worldcities.db` in package directory)\r\n- `csv_file`: Path to CSV file for initial database creation (if database doesn't exist)\r\n\r\n#### `find_city(self, city_name)`\r\nFind cities by name (case-insensitive partial match).\r\n\r\n- `city_name`: Full or partial city name to search for\r\n- Returns: List of dictionaries containing city information (city, country, lat, lon)\r\n\r\n#### `get_coordinates(self, city_name)`\r\nGet coordinates for a specific city (exact match).\r\n\r\n- `city_name`: Exact city name (case-insensitive)\r\n- Returns: Tuple of (latitude, longitude) or None if not found\r\n\r\n#### `close(self)`\r\nClose the database connection. Always call this when done with the finder.\r\n\r\n## Database\r\n\r\nThe 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.\r\n\r\n### Database Schema\r\n\r\nThe `cities` table has the following columns:\r\n- `city`: City name\r\n- `country`: Country name\r\n- `lat`: Latitude (decimal degrees)\r\n- `lon`: Longitude (decimal degrees)\r\n\r\n## Development\r\n\r\n### Prerequisites\r\n\r\n- Python 3.7+\r\n- Git\r\n\r\n### Setup\r\n\r\n1. Clone the repository:\r\n ```bash\r\n git clone https://github.com/Pulkit-Py/geopointdb.git\r\n cd geopointdb\r\n ```\r\n\r\n2. Create and activate a virtual environment:\r\n ```bash\r\n # Windows\r\n python -m venv venv\r\n .\\venv\\Scripts\\activate\r\n \r\n # Unix/macOS\r\n python3 -m venv venv\r\n source venv/bin/activate\r\n ```\r\n\r\n3. Install development dependencies:\r\n ```bash\r\n pip install -r requirements-dev.txt\r\n pip install -e .\r\n ```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\r\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\r\n4. Push to the branch (`git push origin feature/AmazingFeature`)\r\n5. Open a Pull Request\r\n\r\n## Support\r\n\r\nFor support, please open an issue on the [GitHub repository](https://github.com/Pulkit-Py/geopointdb/issues).\r\n\r\n## Acknowledgements\r\n\r\n- World cities data from [geonames.org](https://www.geonames.org/)\r\n\r\n\r\n## Support\r\n\r\nIf you found this project helpful, consider:\r\n- Giving it a \u2b50 on GitHub\r\n- Following me on social media\r\n- Sharing it with others who might find it useful\r\n\r\n---\r\n<p align=\"center\">Made with \u2764\ufe0f by <a href=\"https://github.com/Pulkit-Py\">Pulkit-Py</a> From \ud83c\uddee\ud83c\uddf3 India</p>\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Offline geolocation and geocoding package using SQLite (~200000+ world cities)",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/Pulkit-Py/geopointdb",
"Repository": "https://github.com/Pulkit-Py/geopointdb/issues"
},
"split_keywords": [
"geolocation",
" geocoding",
" sqlite",
" offline",
" world cities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e5e3005e017d6b63787809bbfc1c29d7acb45ce5ca07a5e7ee1193fb31d397b2",
"md5": "ea0ab38cb876dc81203cdb97c2d78d15",
"sha256": "ce31290257a457c777fc5af5b2772d29d8ae81fbbba285c857799e5f3ffeeee5"
},
"downloads": -1,
"filename": "geopointdb-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea0ab38cb876dc81203cdb97c2d78d15",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5336823,
"upload_time": "2025-09-13T06:11:09",
"upload_time_iso_8601": "2025-09-13T06:11:09.133804Z",
"url": "https://files.pythonhosted.org/packages/e5/e3/005e017d6b63787809bbfc1c29d7acb45ce5ca07a5e7ee1193fb31d397b2/geopointdb-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d0a6c47fae8c2508af2059b56fca688edf1a1e9a5d99bfcefcf6e7cd5e060d4",
"md5": "51a09aaec568311938bf8e0619b455c7",
"sha256": "d2aadf0f9f6567f59284d070d7b4032bba8c23d396ad66045689f4f17408bcac"
},
"downloads": -1,
"filename": "geopointdb-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "51a09aaec568311938bf8e0619b455c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5335747,
"upload_time": "2025-09-13T06:11:12",
"upload_time_iso_8601": "2025-09-13T06:11:12.142815Z",
"url": "https://files.pythonhosted.org/packages/4d/0a/6c47fae8c2508af2059b56fca688edf1a1e9a5d99bfcefcf6e7cd5e060d4/geopointdb-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 06:11:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Pulkit-Py",
"github_project": "geopointdb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "geopointdb"
}
JSON
