> ## Content Index
> Fetch the complete content index at: https://darkwebinformer.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# geospy: A Python tool using Google's Gemini API to uncover the location where photos were taken through AI-powered geo-location analysis
- URL: https://darkwebinformer.com/geospy-a-python-tool-using-googles-gemini-api-to-uncover-the-location-where-photos-were-taken-through-ai-powered-geo-location-analysis/
- Published: 2025-07-29T17:29:14.000Z
- Updated: 2025-09-04T22:20:53.000Z
- Author: Dark Web Informer
- Tags: OSINT, Tools

---

**GitHub:** <https://github.com/atiilla/geospy>

---

# geospy

Python tool using Google's Gemini API to uncover the location where photos were taken through AI-powered geo-location analysis.

[](https://asciinema.org/a/722241)

## Installation

[](https://github.com/atiilla/geospy?tab=readme-ov-file#installation)pip install geospyer

## Usage

[](https://github.com/atiilla/geospy?tab=readme-ov-file#usage)

### Command Line Interface

[](https://github.com/atiilla/geospy?tab=readme-ov-file#command-line-interface)geospyer --image path/to/your/image.jpg

#### Available Arguments

[](https://github.com/atiilla/geospy?tab=readme-ov-file#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

[](https://github.com/atiilla/geospy?tab=readme-ov-file#examples)

Basic usage:

geospyer --image vacation\_photo.jpg

With additional context:

geospyer --image vacation\_photo.jpg --context "Taken during summer vacation in 2023"

With location guess:

geospyer --image vacation\_photo.jpg --guess "Mediterranean coast"

Saving results to a file:

geospyer --image vacation\_photo.jpg --output results.json

Using a custom API key:

geospyer --image vacation\_photo.jpg --api-key "your-api-key-here"

### API Key Setup

[](https://github.com/atiilla/geospy?tab=readme-ov-file#api-key-setup)

GeoSpy 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: `GeoSpy(api_key="your_key_here")`
3. Use the `--api-key` parameter in the command line

Get your Gemini API key from [Google AI Studio](https://ai.google.dev/).

### Python Library

[](https://github.com/atiilla/geospy?tab=readme-ov-file#python-library)from geospyer import GeoSpy  
  
\# Initialize GeoSpy  
geospy = GeoSpy()  
  
\# Analyze an image and get JSON result  
result = geospy.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](https://github.com/atiilla/geospy/blob/main/examples) for more detailed usage examples.

## Features

[](https://github.com/atiilla/geospy?tab=readme-ov-file#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

[](https://github.com/atiilla/geospy?tab=readme-ov-file#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:

[](https://github.com/atiilla/geospy?tab=readme-ov-file#disclaimer)

GeoSpy 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

[](https://github.com/atiilla/geospy?tab=readme-ov-file#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

[](https://github.com/atiilla/geospy?tab=readme-ov-file#license)

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