# GeoIntel
Python tool using Google's Gemini API to uncover the location where photos were taken through AI-powered geo-location analysis.
## Installation
```bash
pip install geointel
```
Usage
Command Line Interface
```
geointel --image path/to/your/image.jpg
```
[](https://asciinema.org/a/I6NqhIr6QkBWaaHNjSlieId5s)
Available Arguments
Argument Description
```
--image Required. Path to the image file or URL to analyze
--context Additional context information about the image
--guess Your guess of where the image might have been taken
--output Output file path to save the results (JSON format)
--api-key Custom Gemini API key
```
Examples
Basic usage:
geointel --image vacation_photo.jpg
With additional context:
geointel --image vacation_photo.jpg --context "Taken during summer vacation in 2023"
With location guess:
geointel --image vacation_photo.jpg --guess "Mediterranean coast"
Saving results to a file:
geointel --image vacation_photo.jpg --output results.json
Using a custom API key:
geointel --image vacation_photo.jpg --api-key "your-api-key-here"
API Key Setup
GeoIntel uses Google's Gemini API. You can:
1. Set the API key as an environment variable: GEMINI_API_KEY=your_key_here
2. Pass the API key directly when initializing: GeoIntel(api_key="your_key_here")
3. Use the --api-key parameter in the command line
Get your Gemini API key from Google AI Studio.
Python Library
```
from geointel import GeoIntel
# Initialize GeoIntel
geointel = GeoIntel()
# Analyze an image and get JSON result
result = geointel.locate(image_path="image.jpg")
# Work with the JSON data
if "error" in result:
print(f"Error: {result['error']}")
else:
# Access the first location
if "locations" in result and result["locations"]:
location = result["locations"][0]
print(f"Location: {location['city']}, {location['country']}")
# Get Google Maps URL
if "coordinates" in location:
lat = location["coordinates"]["latitude"]
lng = location["coordinates"]["longitude"]
maps_url = f"https://www.google.com/maps?q={lat},{lng}"
```
See the examples directory for more detailed usage examples.
Features
AI-powered geolocation of images using Google's Gemini API
Generate Google Maps links based on image coordinates
Provide confidence levels for location predictions
Support for additional context and location guesses
Export results to JSON
Handles both local image files and image URLs
Response Format
The API returns a structured JSON response with:
interpretation: Comprehensive analysis of the image
locations: Array of possible locations with:
Country, state, and city information
Confidence level (High/Medium/Low)
Coordinates (latitude/longitude)
Detailed explanation of the reasoning
Disclaimer:
GeoIntel is intended for educational and research purposes only. While it uses AI models to estimate the location of where an image was taken, its predictions are not guaranteed to be accurate. Do not use this tool for surveillance, stalking, law enforcement, or any activity that may infringe on personal privacy, violate laws, or cause harm.
The author(s) and contributors are not responsible for any damages, legal issues, or consequences resulting from the use or misuse of this software. Use at your own risk and discretion.
Always comply with local, national, and international laws and regulations when using AI-based tools.
Contributing
1. Fork the repository
2. Create a new branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Create a pull request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/atiilla/geointel",
"name": "geointel",
"maintainer": "Atiilla",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "geolocation, ai, image-analysis, gemini, google-ai",
"author": "Atiilla",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/47/fd/287517b821c1ab54a3f93060fee54636bd83d3315e3bdab30de7baff6f86/geointel-0.1.11.tar.gz",
"platform": null,
"description": "# GeoIntel\r\n\r\n\r\n\r\n\r\nPython tool using Google's Gemini API to uncover the location where photos were taken through AI-powered geo-location analysis.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install geointel\r\n```\r\n\r\nUsage\r\n\r\nCommand Line Interface\r\n```\r\ngeointel --image path/to/your/image.jpg\r\n```\r\n\r\n[](https://asciinema.org/a/I6NqhIr6QkBWaaHNjSlieId5s)\r\n\r\nAvailable Arguments\r\n\r\nArgument\tDescription\r\n```\r\n--image\tRequired. Path to the image file or URL to analyze\r\n--context\tAdditional context information about the image\r\n--guess\tYour guess of where the image might have been taken\r\n--output\tOutput file path to save the results (JSON format)\r\n--api-key\tCustom Gemini API key\r\n```\r\n\r\nExamples\r\n\r\nBasic usage:\r\n\r\ngeointel --image vacation_photo.jpg\r\n\r\nWith additional context:\r\n\r\ngeointel --image vacation_photo.jpg --context \"Taken during summer vacation in 2023\"\r\n\r\nWith location guess:\r\n\r\ngeointel --image vacation_photo.jpg --guess \"Mediterranean coast\"\r\n\r\nSaving results to a file:\r\n\r\ngeointel --image vacation_photo.jpg --output results.json\r\n\r\nUsing a custom API key:\r\n\r\ngeointel --image vacation_photo.jpg --api-key \"your-api-key-here\"\r\n\r\nAPI Key Setup\r\n\r\nGeoIntel uses Google's Gemini API. You can:\r\n\r\n1. Set the API key as an environment variable: GEMINI_API_KEY=your_key_here\r\n\r\n\r\n2. Pass the API key directly when initializing: GeoIntel(api_key=\"your_key_here\")\r\n\r\n\r\n3. Use the --api-key parameter in the command line\r\n\r\n\r\n\r\nGet your Gemini API key from Google AI Studio.\r\n\r\nPython Library\r\n```\r\nfrom geointel import GeoIntel\r\n\r\n# Initialize GeoIntel\r\ngeointel = GeoIntel()\r\n\r\n# Analyze an image and get JSON result\r\nresult = geointel.locate(image_path=\"image.jpg\")\r\n\r\n# Work with the JSON data\r\nif \"error\" in result:\r\n print(f\"Error: {result['error']}\")\r\nelse:\r\n # Access the first location\r\n if \"locations\" in result and result[\"locations\"]:\r\n location = result[\"locations\"][0]\r\n print(f\"Location: {location['city']}, {location['country']}\")\r\n \r\n # Get Google Maps URL\r\n if \"coordinates\" in location:\r\n lat = location[\"coordinates\"][\"latitude\"]\r\n lng = location[\"coordinates\"][\"longitude\"]\r\n maps_url = f\"https://www.google.com/maps?q={lat},{lng}\"\r\n```\r\n\r\nSee the examples directory for more detailed usage examples.\r\n\r\nFeatures\r\n\r\nAI-powered geolocation of images using Google's Gemini API\r\n\r\nGenerate Google Maps links based on image coordinates\r\n\r\nProvide confidence levels for location predictions\r\n\r\nSupport for additional context and location guesses\r\n\r\nExport results to JSON\r\n\r\nHandles both local image files and image URLs\r\n\r\n\r\nResponse Format\r\n\r\nThe API returns a structured JSON response with:\r\n\r\ninterpretation: Comprehensive analysis of the image\r\n\r\nlocations: Array of possible locations with:\r\n\r\nCountry, state, and city information\r\n\r\nConfidence level (High/Medium/Low)\r\n\r\nCoordinates (latitude/longitude)\r\n\r\nDetailed explanation of the reasoning\r\n\r\n\r\n\r\nDisclaimer:\r\n\r\nGeoIntel is intended for educational and research purposes only. While it uses AI models to estimate the location of where an image was taken, its predictions are not guaranteed to be accurate. Do not use this tool for surveillance, stalking, law enforcement, or any activity that may infringe on personal privacy, violate laws, or cause harm.\r\n\r\nThe author(s) and contributors are not responsible for any damages, legal issues, or consequences resulting from the use or misuse of this software. Use at your own risk and discretion.\r\n\r\nAlways comply with local, national, and international laws and regulations when using AI-based tools.\r\n\r\nContributing\r\n\r\n1. Fork the repository\r\n\r\n2. Create a new branch (git checkout -b feature/new-feature).\r\n\r\n3. Commit your changes (git commit -am 'Add new feature').\r\n\r\n4. Push to the branch (git push origin feature/new-feature).\r\n\r\n5. Create a pull request.\r\n\r\n\r\nLicense\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI powered geo-location to uncover the location of photos.",
"version": "0.1.11",
"project_urls": {
"Changelog": "https://github.com/atiilla/geointel/releases",
"Documentation": "https://github.com/atiilla/geointel#readme",
"Homepage": "https://github.com/atiilla/geointel",
"Issues": "https://github.com/atiilla/geointel/issues",
"Repository": "https://github.com/atiilla/geointel"
},
"split_keywords": [
"geolocation",
" ai",
" image-analysis",
" gemini",
" google-ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7930190fe50d79121987fd1d9a62e64e091545fd71ec7bd4fc18714141ddd653",
"md5": "7044a879a3dad64d7e6c99d0e1b08991",
"sha256": "383f8d8e51f4842e1b02ce79c23ef1080d87fce2fa7b74aa4bff63c6f66b3897"
},
"downloads": -1,
"filename": "geointel-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7044a879a3dad64d7e6c99d0e1b08991",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10212,
"upload_time": "2025-08-29T19:24:59",
"upload_time_iso_8601": "2025-08-29T19:24:59.448133Z",
"url": "https://files.pythonhosted.org/packages/79/30/190fe50d79121987fd1d9a62e64e091545fd71ec7bd4fc18714141ddd653/geointel-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "47fd287517b821c1ab54a3f93060fee54636bd83d3315e3bdab30de7baff6f86",
"md5": "9e7815d0f68e7e08cc480a5d1cc94e70",
"sha256": "87f4de900b84c36a8902485e626c7d583d051bcd7f80fc7467c5c2dc6de63f1c"
},
"downloads": -1,
"filename": "geointel-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "9e7815d0f68e7e08cc480a5d1cc94e70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12046,
"upload_time": "2025-08-29T19:25:01",
"upload_time_iso_8601": "2025-08-29T19:25:01.620445Z",
"url": "https://files.pythonhosted.org/packages/47/fd/287517b821c1ab54a3f93060fee54636bd83d3315e3bdab30de7baff6f86/geointel-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 19:25:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "atiilla",
"github_project": "geointel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
}
],
"lcname": "geointel"
}
JSON
