geoseeer 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
geoseeer-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 GeoSeer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: geoseeer
3
+ Version: 0.1.0
4
+ Summary: Python client for the GeoSeer geolocation API
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://geoseeer.com
7
+ Project-URL: Documentation, https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk
8
+ Project-URL: Source, https://github.com/geoseeer/GeoSeer
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: requests<3,>=2.32.5
13
+ Dynamic: license-file
14
+
15
+ # GeoSeer AI image geolocation β€” geoseeer.com πŸŒπŸ”
16
+
17
+ [GeoSeer](https://geoseeer.com) analyzes images, multiple image clues, videos, and real-world event descriptions to suggest locations and explain the clues behind them. **Fast** provides rapid estimation, **Agent** uses tools and multi-step reasoning for a more extensive search, and **Event** investigates locations from text descriptions.
18
+
19
+ > Upload a photo, image set, or video, or enter an event description β†’ Review location candidates with coordinates, addresses, and reasoning.
20
+
21
+ ---
22
+
23
+ ## How It Works
24
+
25
+ 1. **Submit Input** πŸ“€ β€” Upload an image via the [web interface](https://geoseeer.com) or the [REST API](https://geoseeer.com/api-docs). GeoSeer supports single-image, multi-image, video, image URL, and text-based event analysis on the web.
26
+ 2. **AI Analysis** πŸ€– β€” GeoSeer's agentic analysis system examines visual clues β€” architectural styles, natural landmarks, vegetation patterns, street furniture, signage, satellite data, environmental context, and event-specific context when using Event mode.
27
+ 3. **Location Results** πŸ“ β€” Receive up to 8 location candidates ranked by confidence, each with GPS coordinates, human-readable address, and detailed reasoning explaining the analysis.
28
+
29
+ ### Architecture Overview
30
+
31
+ GeoSeer's agentic pipeline consists of three complementary analysis paths:
32
+
33
+ - **Fast Mode (GS-Fast)** β€” Proprietary geospatial estimation for rapid kilometer-level predictions
34
+ - **Agent Mode (GS-Agent)** β€” Multi-step reasoning and tool calling for more comprehensive pinpointing
35
+ - **Event Mode (GS-Event)** β€” Text-first event investigation for real-world incident and event-location searches
36
+
37
+ Shared system components include:
38
+
39
+ - **Input Processing** β€” Visual media ingestion with metadata extraction (EXIF data, timestamps, camera info)
40
+ - **Model Estimation** β€” Proprietary geospatial estimation model used by GS-Fast and as a signal source for deeper analysis
41
+ - **LVLM Analysis** β€” Large Vision-Language Model analysis for feature extraction and scene understanding
42
+ - **Normalization & Reasoning** β€” Multi-step reasoning that integrates signals from all sources
43
+ - **Tool Calling** β€” Satellite imagery, map data, web search, and reverse image search for verification
44
+ - **Final Reasoning** β€” Comprehensive analysis combining all evidence into precise location candidates
45
+
46
+ ---
47
+
48
+ ## Features
49
+
50
+ - 🧠 **Agentic AI Architecture** β€” Advanced multi-step reasoning with tool calling for pinpoint accuracy
51
+ - ⚑ **Three Processing Modes** β€” Fast for rapid estimation, Agent for a more extensive search, and Event for text-only investigation. Fast measured 10 seconds at API p50 in the October 14, 2026 tests; timing varies with input, load, and network conditions
52
+ - 🌐 **Global Coverage** β€” Geolocate photos, image sets, and video from anywhere on Earth
53
+ - πŸ“ **Event Search Support** β€” Run text-only event geolocation searches without requiring file upload
54
+ - πŸ”’ **Processing & Sharing** β€” Media is stored temporarily during analysis, and cleanup attempts to remove processing files afterward. Saving or sharing a result can retain result data and associated media separately
55
+ - πŸ”Œ **Developer API** β€” Simple REST API with streaming (SSE) support for easy integration
56
+ - 🏒 **Enterprise Ready** β€” Custom rate limits, white-label API access, and self-host support via [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
57
+
58
+ ---
59
+
60
+ ## Performance Benchmarks
61
+
62
+ Updated **November 16, 2026**. Accuracy uses IM2GPS3k, and costs use entry monthly consumer plans with fixed search allowances, falling back to entry prepaid credits when no such plan exists. See the [full results, sources, and methodology](https://geoseeer.com/benchmarks).
63
+
64
+ | Provider | IM2GPS3k accuracy @ 1 km | Latency | Reference paid cost / search |
65
+ |----------|-------------------------|---------|----------------------------------|
66
+ | **GeoSeer** | [**67%**](https://geoseeer.com/benchmarks#accuracy), Agent | **10s**, Fast Β· GeoSeer API p50 | [**$0.19**](https://geoseeer.com/#pricing), Starter $19/month / 100 web searches |
67
+ | GeoAxis | β€” No published IM2GPS3k result | 35s, Global Search Low Β· GeoAxis API | [$0.90](https://geoaxis.ai/pricing), prepaid credits, minimum $10 purchase |
68
+ | Oceanir | [22.52%](https://oceanir.ai/geoestimation), Manta Geo-Estimation | β€” API not tested | [$1.00](https://oceanir.ai/pricing), Starter $10/month / 10 Orca Max detailed analyses |
69
+ | Picarta | [44.8%](https://picarta.ai/picarta-v2), V2.1 | 12s, standard image search Β· Picarta API | [$0.60](https://picarta.ai/pricing), $59.90/month / 100 searches, rounded |
70
+ | GeoInfer | [50%](https://docs.geoinfer.com/faq), Global | [1s](https://geoinfer.com/en), published inference reference | [$0.10](https://geoinfer.com/en/pricing), $4.99 / 50 global predictions, rounded |
71
+
72
+ > Accuracy: GeoSeer tested the full [IM2GPS3k benchmark](https://github.com/lugiavn/revisiting-im2gps) itself; competitor figures are linked vendor-published results from separate evaluations. Model versions, training data, prediction-selection rules, and experimental conditions can differ. Oceanir's accuracy result describes Manta, which requires organizational access; its displayed cost covers public Orca Max analysis.
73
+ >
74
+ > Latency: GeoSeer tested its own, GeoAxis's, and Picarta's APIs. The p50 values retain the October 14, 2026 test snapshot and selected modes. GeoInfer's displayed 1s represents its advertised sub-second inference, rather than a GeoSeer-measured API p50. Oceanir's API has not been timed. GeoAxis now [advertises](https://geoaxis.ai/) approximately 5s for Instant and 20s for Low; these are separate provider-reported production timings.
75
+ >
76
+ > Cost: Apply the same rule to all providers: use the entry monthly consumer plan with a fixed search allowance; otherwise use the entry prepaid pack or published credit rate. Divide price by included complete searches, assuming full utilization before allowance or credit expiry. GeoSeer's denominator is its 100 web searches; its separate API allowance is not added. [GeoAxis](https://geoaxis.ai/pricing) and [GeoInfer](https://geoinfer.com/en/pricing) advertise unlimited consumer subscriptions, whose effective per-search costs depend on actual usage, so the table uses their prepaid rates. GeoInfer [uses one credit per global prediction](https://docs.geoinfer.com/faq). Higher tiers and larger packs are separate: [Oceanir Pro](https://oceanir.ai/pricing) includes 300 detailed analyses for $29/month (about $0.10 each at full utilization). Free allowances, trials, promotions, annual billing, and negotiated enterprise rates are excluded. Commercial API pricing can differ from these consumer search references.
77
+
78
+ Providers were selected for their popularity, strong geolocation accuracy, and public availability at the comparison date. Access-restricted services such as [GeoSpy (now Raven)](https://graylark.com/raven/faq) and broader enterprise platforms such as [Palantir Foundry](https://www.palantir.com/platforms/foundry/) fall outside this product comparison. Individual model access is identified in the methodology.
79
+
80
+ ---
81
+
82
+ ## Getting Started
83
+
84
+ ### On the Web
85
+
86
+ Visit [geoseeer.com](https://geoseeer.com) β€” new users can get started **for free**.
87
+
88
+ 1. Upload or drag & drop your image or video, or enter an event description
89
+ 2. Choose Fast mode for quick estimation, Agent mode for deeper analysis, or Event mode for text-only event investigation
90
+ 3. Optionally add context (country, source, time period, etc.)
91
+ 4. Get precise location results with confidence scores and reasoning
92
+
93
+ ### Via the API
94
+
95
+ Get your API key from the [Dashboard](https://geoseeer.com/dashboard), then send either a media-analysis request or a text-only event-analysis request:
96
+
97
+ ```bash
98
+ curl -X POST https://geoseeer.com/api/v1/analyze \
99
+ -H "X-API-Key: YOUR_API_KEY" \
100
+ -F "file=@photo.jpg" \
101
+ -F "analysis_mode=fast" \
102
+ -F "user_context=Beach photo from summer 2025"
103
+ ```
104
+
105
+ ### Python SDK
106
+
107
+ Install `geoseeer` on Python 3.11 or later and set `GEOSEER_API_KEY` to your GeoSeer API key.
108
+
109
+ ```bash
110
+ pip install geoseeer
111
+ ```
112
+
113
+ ```python
114
+ from geoseeer import GeoSeer
115
+
116
+ client = GeoSeer()
117
+ result = client.analyze(files="photo.jpg", context="A coastal city")
118
+ print(result["locations"])
119
+ ```
120
+
121
+ See the [Python SDK guide](https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk) for URL input, Event mode, and streaming, or the [API documentation](https://geoseeer.com/api-docs) for the full HTTP reference.
122
+
123
+ ---
124
+
125
+ ## Pricing
126
+
127
+ | Plan | Price | Includes |
128
+ |------|-------|----------|
129
+ | **Free** | $0 forever | Fast Mode access, 1 search/day on web, 10 total API calls |
130
+ | **Starter** | $19/month; or $9/month billed annually | All analysis modes, 100 searches/mo, 100 API calls/mo, priority processing |
131
+ | **Pro** | $69/month; or $29/month billed annually | Everything in Starter, unlimited web searches, 1,000 API calls/mo, white-label API access |
132
+ | **Enterprise** | Custom | Custom limits, white-label API access, self-host support β€” [enterprise.geoseeer.com](https://enterprise.geoseeer.com) |
133
+
134
+ > Eligible paid plans can purchase additional web-search or API credits from the dashboard at $0.20 per credit, sold in packs of five.
135
+
136
+ ---
137
+
138
+ ## Use Cases
139
+
140
+ - **OSINT & Investigations** β€” Verify photo locations for open-source intelligence work
141
+ - **Journalism & UGC Verification** β€” Authenticate user-generated content and news sources
142
+ - **Academic Research** β€” Study geospatial patterns, verify historical image locations
143
+ - **Supply Chain & Logistics** β€” Geolocate assets and shipment photos
144
+ - **AI Agent Infrastructure** β€” Integrate geolocation capabilities into autonomous AI systems
145
+ - **Enterprise Applications** β€” Build geolocation-powered features into your products
146
+
147
+ ---
148
+
149
+ ## About
150
+
151
+ GeoSeer is developed by **Shenzhen Ques Technology Co., Ltd.** ([quesx.com](https://quesx.com)) as part of the company's OSINT (Open-Source Intelligence) infrastructure ecosystem. Our mission is to make professional geolocation capabilities accessible to everyone β€” from individual investigators and researchers to AI agents and enterprise systems.
152
+
153
+ ---
154
+
155
+ ## Links
156
+
157
+ - 🌐 **Website**: [geoseeer.com](https://geoseeer.com)
158
+ - πŸ“– **API Docs**: [geoseeer.com/api-docs](https://geoseeer.com/api-docs)
159
+ - 🏒 **Enterprise**: [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
160
+ - πŸ“ **Blog**: [geoseeer.com/blog](https://geoseeer.com/blog)
161
+ - πŸ’Ό **Careers**: [geoseeer.com/careers](https://geoseeer.com/careers)
162
+
163
+ ### Social
164
+
165
+ - [X (Twitter)](https://x.com/GeoSeeer)
166
+ - [LinkedIn](https://www.linkedin.com/company/geoseer)
167
+ - [Instagram](https://www.instagram.com/geoseeer/)
168
+ - [TikTok](https://www.tiktok.com/@geoseeer)
169
+ - [YouTube](https://www.youtube.com/@geoseeer)
170
+ - [Facebook](https://www.facebook.com/profile.php?id=61583773556872)
171
+
172
+ ---
173
+
174
+ ## Contact
175
+
176
+ For inquiries, enterprise partnerships, or support, visit [geoseeer.com/about](https://geoseeer.com/about) or reach out through our social channels.
177
+
178
+ ---
179
+
180
+ Β© 2025-2026 GeoSeer. All rights reserved.
@@ -0,0 +1,166 @@
1
+ # GeoSeer AI image geolocation β€” geoseeer.com πŸŒπŸ”
2
+
3
+ [GeoSeer](https://geoseeer.com) analyzes images, multiple image clues, videos, and real-world event descriptions to suggest locations and explain the clues behind them. **Fast** provides rapid estimation, **Agent** uses tools and multi-step reasoning for a more extensive search, and **Event** investigates locations from text descriptions.
4
+
5
+ > Upload a photo, image set, or video, or enter an event description β†’ Review location candidates with coordinates, addresses, and reasoning.
6
+
7
+ ---
8
+
9
+ ## How It Works
10
+
11
+ 1. **Submit Input** πŸ“€ β€” Upload an image via the [web interface](https://geoseeer.com) or the [REST API](https://geoseeer.com/api-docs). GeoSeer supports single-image, multi-image, video, image URL, and text-based event analysis on the web.
12
+ 2. **AI Analysis** πŸ€– β€” GeoSeer's agentic analysis system examines visual clues β€” architectural styles, natural landmarks, vegetation patterns, street furniture, signage, satellite data, environmental context, and event-specific context when using Event mode.
13
+ 3. **Location Results** πŸ“ β€” Receive up to 8 location candidates ranked by confidence, each with GPS coordinates, human-readable address, and detailed reasoning explaining the analysis.
14
+
15
+ ### Architecture Overview
16
+
17
+ GeoSeer's agentic pipeline consists of three complementary analysis paths:
18
+
19
+ - **Fast Mode (GS-Fast)** β€” Proprietary geospatial estimation for rapid kilometer-level predictions
20
+ - **Agent Mode (GS-Agent)** β€” Multi-step reasoning and tool calling for more comprehensive pinpointing
21
+ - **Event Mode (GS-Event)** β€” Text-first event investigation for real-world incident and event-location searches
22
+
23
+ Shared system components include:
24
+
25
+ - **Input Processing** β€” Visual media ingestion with metadata extraction (EXIF data, timestamps, camera info)
26
+ - **Model Estimation** β€” Proprietary geospatial estimation model used by GS-Fast and as a signal source for deeper analysis
27
+ - **LVLM Analysis** β€” Large Vision-Language Model analysis for feature extraction and scene understanding
28
+ - **Normalization & Reasoning** β€” Multi-step reasoning that integrates signals from all sources
29
+ - **Tool Calling** β€” Satellite imagery, map data, web search, and reverse image search for verification
30
+ - **Final Reasoning** β€” Comprehensive analysis combining all evidence into precise location candidates
31
+
32
+ ---
33
+
34
+ ## Features
35
+
36
+ - 🧠 **Agentic AI Architecture** β€” Advanced multi-step reasoning with tool calling for pinpoint accuracy
37
+ - ⚑ **Three Processing Modes** β€” Fast for rapid estimation, Agent for a more extensive search, and Event for text-only investigation. Fast measured 10 seconds at API p50 in the October 14, 2026 tests; timing varies with input, load, and network conditions
38
+ - 🌐 **Global Coverage** β€” Geolocate photos, image sets, and video from anywhere on Earth
39
+ - πŸ“ **Event Search Support** β€” Run text-only event geolocation searches without requiring file upload
40
+ - πŸ”’ **Processing & Sharing** β€” Media is stored temporarily during analysis, and cleanup attempts to remove processing files afterward. Saving or sharing a result can retain result data and associated media separately
41
+ - πŸ”Œ **Developer API** β€” Simple REST API with streaming (SSE) support for easy integration
42
+ - 🏒 **Enterprise Ready** β€” Custom rate limits, white-label API access, and self-host support via [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
43
+
44
+ ---
45
+
46
+ ## Performance Benchmarks
47
+
48
+ Updated **November 16, 2026**. Accuracy uses IM2GPS3k, and costs use entry monthly consumer plans with fixed search allowances, falling back to entry prepaid credits when no such plan exists. See the [full results, sources, and methodology](https://geoseeer.com/benchmarks).
49
+
50
+ | Provider | IM2GPS3k accuracy @ 1 km | Latency | Reference paid cost / search |
51
+ |----------|-------------------------|---------|----------------------------------|
52
+ | **GeoSeer** | [**67%**](https://geoseeer.com/benchmarks#accuracy), Agent | **10s**, Fast Β· GeoSeer API p50 | [**$0.19**](https://geoseeer.com/#pricing), Starter $19/month / 100 web searches |
53
+ | GeoAxis | β€” No published IM2GPS3k result | 35s, Global Search Low Β· GeoAxis API | [$0.90](https://geoaxis.ai/pricing), prepaid credits, minimum $10 purchase |
54
+ | Oceanir | [22.52%](https://oceanir.ai/geoestimation), Manta Geo-Estimation | β€” API not tested | [$1.00](https://oceanir.ai/pricing), Starter $10/month / 10 Orca Max detailed analyses |
55
+ | Picarta | [44.8%](https://picarta.ai/picarta-v2), V2.1 | 12s, standard image search Β· Picarta API | [$0.60](https://picarta.ai/pricing), $59.90/month / 100 searches, rounded |
56
+ | GeoInfer | [50%](https://docs.geoinfer.com/faq), Global | [1s](https://geoinfer.com/en), published inference reference | [$0.10](https://geoinfer.com/en/pricing), $4.99 / 50 global predictions, rounded |
57
+
58
+ > Accuracy: GeoSeer tested the full [IM2GPS3k benchmark](https://github.com/lugiavn/revisiting-im2gps) itself; competitor figures are linked vendor-published results from separate evaluations. Model versions, training data, prediction-selection rules, and experimental conditions can differ. Oceanir's accuracy result describes Manta, which requires organizational access; its displayed cost covers public Orca Max analysis.
59
+ >
60
+ > Latency: GeoSeer tested its own, GeoAxis's, and Picarta's APIs. The p50 values retain the October 14, 2026 test snapshot and selected modes. GeoInfer's displayed 1s represents its advertised sub-second inference, rather than a GeoSeer-measured API p50. Oceanir's API has not been timed. GeoAxis now [advertises](https://geoaxis.ai/) approximately 5s for Instant and 20s for Low; these are separate provider-reported production timings.
61
+ >
62
+ > Cost: Apply the same rule to all providers: use the entry monthly consumer plan with a fixed search allowance; otherwise use the entry prepaid pack or published credit rate. Divide price by included complete searches, assuming full utilization before allowance or credit expiry. GeoSeer's denominator is its 100 web searches; its separate API allowance is not added. [GeoAxis](https://geoaxis.ai/pricing) and [GeoInfer](https://geoinfer.com/en/pricing) advertise unlimited consumer subscriptions, whose effective per-search costs depend on actual usage, so the table uses their prepaid rates. GeoInfer [uses one credit per global prediction](https://docs.geoinfer.com/faq). Higher tiers and larger packs are separate: [Oceanir Pro](https://oceanir.ai/pricing) includes 300 detailed analyses for $29/month (about $0.10 each at full utilization). Free allowances, trials, promotions, annual billing, and negotiated enterprise rates are excluded. Commercial API pricing can differ from these consumer search references.
63
+
64
+ Providers were selected for their popularity, strong geolocation accuracy, and public availability at the comparison date. Access-restricted services such as [GeoSpy (now Raven)](https://graylark.com/raven/faq) and broader enterprise platforms such as [Palantir Foundry](https://www.palantir.com/platforms/foundry/) fall outside this product comparison. Individual model access is identified in the methodology.
65
+
66
+ ---
67
+
68
+ ## Getting Started
69
+
70
+ ### On the Web
71
+
72
+ Visit [geoseeer.com](https://geoseeer.com) β€” new users can get started **for free**.
73
+
74
+ 1. Upload or drag & drop your image or video, or enter an event description
75
+ 2. Choose Fast mode for quick estimation, Agent mode for deeper analysis, or Event mode for text-only event investigation
76
+ 3. Optionally add context (country, source, time period, etc.)
77
+ 4. Get precise location results with confidence scores and reasoning
78
+
79
+ ### Via the API
80
+
81
+ Get your API key from the [Dashboard](https://geoseeer.com/dashboard), then send either a media-analysis request or a text-only event-analysis request:
82
+
83
+ ```bash
84
+ curl -X POST https://geoseeer.com/api/v1/analyze \
85
+ -H "X-API-Key: YOUR_API_KEY" \
86
+ -F "file=@photo.jpg" \
87
+ -F "analysis_mode=fast" \
88
+ -F "user_context=Beach photo from summer 2025"
89
+ ```
90
+
91
+ ### Python SDK
92
+
93
+ Install `geoseeer` on Python 3.11 or later and set `GEOSEER_API_KEY` to your GeoSeer API key.
94
+
95
+ ```bash
96
+ pip install geoseeer
97
+ ```
98
+
99
+ ```python
100
+ from geoseeer import GeoSeer
101
+
102
+ client = GeoSeer()
103
+ result = client.analyze(files="photo.jpg", context="A coastal city")
104
+ print(result["locations"])
105
+ ```
106
+
107
+ See the [Python SDK guide](https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk) for URL input, Event mode, and streaming, or the [API documentation](https://geoseeer.com/api-docs) for the full HTTP reference.
108
+
109
+ ---
110
+
111
+ ## Pricing
112
+
113
+ | Plan | Price | Includes |
114
+ |------|-------|----------|
115
+ | **Free** | $0 forever | Fast Mode access, 1 search/day on web, 10 total API calls |
116
+ | **Starter** | $19/month; or $9/month billed annually | All analysis modes, 100 searches/mo, 100 API calls/mo, priority processing |
117
+ | **Pro** | $69/month; or $29/month billed annually | Everything in Starter, unlimited web searches, 1,000 API calls/mo, white-label API access |
118
+ | **Enterprise** | Custom | Custom limits, white-label API access, self-host support β€” [enterprise.geoseeer.com](https://enterprise.geoseeer.com) |
119
+
120
+ > Eligible paid plans can purchase additional web-search or API credits from the dashboard at $0.20 per credit, sold in packs of five.
121
+
122
+ ---
123
+
124
+ ## Use Cases
125
+
126
+ - **OSINT & Investigations** β€” Verify photo locations for open-source intelligence work
127
+ - **Journalism & UGC Verification** β€” Authenticate user-generated content and news sources
128
+ - **Academic Research** β€” Study geospatial patterns, verify historical image locations
129
+ - **Supply Chain & Logistics** β€” Geolocate assets and shipment photos
130
+ - **AI Agent Infrastructure** β€” Integrate geolocation capabilities into autonomous AI systems
131
+ - **Enterprise Applications** β€” Build geolocation-powered features into your products
132
+
133
+ ---
134
+
135
+ ## About
136
+
137
+ GeoSeer is developed by **Shenzhen Ques Technology Co., Ltd.** ([quesx.com](https://quesx.com)) as part of the company's OSINT (Open-Source Intelligence) infrastructure ecosystem. Our mission is to make professional geolocation capabilities accessible to everyone β€” from individual investigators and researchers to AI agents and enterprise systems.
138
+
139
+ ---
140
+
141
+ ## Links
142
+
143
+ - 🌐 **Website**: [geoseeer.com](https://geoseeer.com)
144
+ - πŸ“– **API Docs**: [geoseeer.com/api-docs](https://geoseeer.com/api-docs)
145
+ - 🏒 **Enterprise**: [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
146
+ - πŸ“ **Blog**: [geoseeer.com/blog](https://geoseeer.com/blog)
147
+ - πŸ’Ό **Careers**: [geoseeer.com/careers](https://geoseeer.com/careers)
148
+
149
+ ### Social
150
+
151
+ - [X (Twitter)](https://x.com/GeoSeeer)
152
+ - [LinkedIn](https://www.linkedin.com/company/geoseer)
153
+ - [Instagram](https://www.instagram.com/geoseeer/)
154
+ - [TikTok](https://www.tiktok.com/@geoseeer)
155
+ - [YouTube](https://www.youtube.com/@geoseeer)
156
+ - [Facebook](https://www.facebook.com/profile.php?id=61583773556872)
157
+
158
+ ---
159
+
160
+ ## Contact
161
+
162
+ For inquiries, enterprise partnerships, or support, visit [geoseeer.com/about](https://geoseeer.com/about) or reach out through our social channels.
163
+
164
+ ---
165
+
166
+ Β© 2025-2026 GeoSeer. All rights reserved.
@@ -0,0 +1,18 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "geoseeer"
7
+ version = "0.1.0"
8
+ description = "Python client for the GeoSeer geolocation API"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ dependencies = ["requests>=2.32.5,<3"]
14
+
15
+ [project.urls]
16
+ Homepage = "https://geoseeer.com"
17
+ Documentation = "https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk"
18
+ Source = "https://github.com/geoseeer/GeoSeer"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,5 @@
1
+ """Python client for the hosted GeoSeer API."""
2
+
3
+ from .client import APIError, GeoSeer, GeoSeerError
4
+
5
+ __all__ = ["APIError", "GeoSeer", "GeoSeerError"]
@@ -0,0 +1,179 @@
1
+ """Client for GeoSeer's external Analyze endpoint."""
2
+
3
+ import json
4
+ import os
5
+ from collections.abc import Iterator, Sequence
6
+ from contextlib import ExitStack, contextmanager
7
+ from pathlib import Path
8
+ from typing import Any, Literal
9
+
10
+ import requests
11
+
12
+ FilePath = str | os.PathLike[str]
13
+ MediaMode = Literal["fast", "agent"]
14
+
15
+
16
+ class GeoSeerError(Exception):
17
+ """The API returned an error or an invalid response."""
18
+
19
+
20
+ class APIError(GeoSeerError):
21
+ """An unsuccessful HTTP response from GeoSeer."""
22
+
23
+ def __init__(self, response: requests.Response) -> None:
24
+ self.status_code = response.status_code
25
+ self.retry_after = response.headers.get("Retry-After")
26
+ try:
27
+ body = response.json()
28
+ except ValueError:
29
+ body = None
30
+ error = body.get("error") if isinstance(body, dict) else None
31
+ if not isinstance(error, dict):
32
+ error = {}
33
+ self.code = error.get("code")
34
+ self.details = error.get("details")
35
+ message = error.get("message") or f"GeoSeer returned HTTP {self.status_code}."
36
+ super().__init__(message)
37
+
38
+
39
+ class GeoSeer:
40
+ """Analyze local media, direct media URLs, or text using the GeoSeer API."""
41
+
42
+ def __init__(
43
+ self,
44
+ api_key: str | None = None,
45
+ *,
46
+ base_url: str | None = None,
47
+ timeout: float | tuple[float, float] = (15, 450),
48
+ ) -> None:
49
+ self._api_key = api_key if api_key is not None else os.getenv("GEOSEER_API_KEY")
50
+ if not self._api_key:
51
+ raise ValueError("Provide api_key or set GEOSEER_API_KEY.")
52
+ self._base_url = base_url or os.getenv("GEOSEER_BASE_URL") or "https://geoseeer.com/api/v1"
53
+ self._timeout = timeout
54
+
55
+ def analyze(
56
+ self,
57
+ *,
58
+ files: FilePath | Sequence[FilePath] | None = None,
59
+ urls: str | Sequence[str] | None = None,
60
+ event_text: str | None = None,
61
+ mode: MediaMode | None = None,
62
+ context: str | None = None,
63
+ ) -> dict[str, Any]:
64
+ """Return the JSON result for exactly one kind of input."""
65
+ with self._post(files, urls, event_text, mode, context, stream=False) as response:
66
+ try:
67
+ result = response.json()
68
+ except ValueError as exc:
69
+ raise GeoSeerError("GeoSeer returned invalid JSON.") from exc
70
+ if not isinstance(result, dict):
71
+ raise GeoSeerError("GeoSeer returned an unexpected JSON result.")
72
+ return result
73
+
74
+ @contextmanager
75
+ def stream(
76
+ self,
77
+ *,
78
+ files: FilePath | Sequence[FilePath] | None = None,
79
+ urls: str | Sequence[str] | None = None,
80
+ event_text: str | None = None,
81
+ mode: MediaMode | None = None,
82
+ context: str | None = None,
83
+ ) -> Iterator[Iterator[dict[str, Any]]]:
84
+ """Open a stream of decoded events. Use the result in a with block."""
85
+ with self._post(files, urls, event_text, mode, context, stream=True) as response:
86
+ content_type = response.headers.get("Content-Type", "").partition(";")[0]
87
+ if content_type.strip().lower() != "text/event-stream":
88
+ raise GeoSeerError("GeoSeer did not return an event stream.")
89
+ yield self._events(response)
90
+
91
+ def _post(
92
+ self,
93
+ files: FilePath | Sequence[FilePath] | None,
94
+ urls: str | Sequence[str] | None,
95
+ event_text: str | None,
96
+ mode: MediaMode | None,
97
+ context: str | None,
98
+ *,
99
+ stream: bool,
100
+ ) -> requests.Response:
101
+ if sum(value is not None for value in (files, urls, event_text)) != 1:
102
+ raise ValueError("Provide exactly one of files, urls, and event_text.")
103
+ if event_text is not None and (mode is not None or context is not None):
104
+ raise ValueError("event_text supplies its own mode and context.")
105
+ if mode not in (None, "fast", "agent"):
106
+ raise ValueError("Media mode must be fast or agent.")
107
+
108
+ fields: dict[str, Any] = {
109
+ "analysis_mode": "event" if event_text is not None else mode or "fast",
110
+ "stream": stream,
111
+ }
112
+ if context is not None:
113
+ fields["user_context"] = context
114
+
115
+ with ExitStack() as inputs:
116
+ if files is not None:
117
+ paths = [files] if isinstance(files, (str, os.PathLike)) else list(files)
118
+ if not 1 <= len(paths) <= 3:
119
+ raise ValueError("Provide one to three files.")
120
+ field_name = "file" if len(paths) == 1 else "files"
121
+ uploads = []
122
+ for filename in paths:
123
+ path = Path(filename)
124
+ file = inputs.enter_context(path.open("rb"))
125
+ uploads.append((field_name, (path.name, file)))
126
+ fields["stream"] = "true" if stream else "false"
127
+ body = {"files": uploads, "data": fields}
128
+ else:
129
+ if urls is not None:
130
+ media_urls = [urls] if isinstance(urls, str) else list(urls)
131
+ if not 1 <= len(media_urls) <= 3:
132
+ raise ValueError("Provide one to three URLs.")
133
+ if len(media_urls) == 1:
134
+ fields["url"] = media_urls[0]
135
+ else:
136
+ fields["urls"] = media_urls
137
+ else:
138
+ fields["event_text"] = event_text
139
+ body = {"json": fields}
140
+
141
+ response = requests.post(
142
+ f"{self._base_url.rstrip('/')}/analyze",
143
+ headers={"X-API-Key": self._api_key},
144
+ timeout=self._timeout,
145
+ allow_redirects=False,
146
+ stream=stream,
147
+ **body,
148
+ )
149
+
150
+ if response.status_code != 200:
151
+ with response:
152
+ raise APIError(response)
153
+ return response
154
+
155
+ @staticmethod
156
+ def _events(response: requests.Response) -> Iterator[dict[str, Any]]:
157
+ pending = b""
158
+ data_lines: list[bytes] = []
159
+ for chunk in response.iter_content(chunk_size=512):
160
+ lines = (pending + chunk).split(b"\n")
161
+ pending = lines.pop()
162
+ for line in lines:
163
+ line = line.removesuffix(b"\r")
164
+ if line.startswith(b"data:"):
165
+ data_lines.append(line[5:].removeprefix(b" "))
166
+ if line or not data_lines:
167
+ continue
168
+ try:
169
+ event = json.loads(b"\n".join(data_lines).decode("utf-8"))
170
+ except ValueError as exc:
171
+ raise GeoSeerError("GeoSeer returned an invalid stream event.") from exc
172
+ if not isinstance(event, dict):
173
+ raise GeoSeerError("GeoSeer returned an unexpected stream event.")
174
+ data_lines.clear()
175
+ terminal = event.get("type") in ("complete", "error", "cancelled")
176
+ yield event
177
+ if terminal:
178
+ return
179
+ raise GeoSeerError("The GeoSeer stream closed before a terminal event.")
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: geoseeer
3
+ Version: 0.1.0
4
+ Summary: Python client for the GeoSeer geolocation API
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://geoseeer.com
7
+ Project-URL: Documentation, https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk
8
+ Project-URL: Source, https://github.com/geoseeer/GeoSeer
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: requests<3,>=2.32.5
13
+ Dynamic: license-file
14
+
15
+ # GeoSeer AI image geolocation β€” geoseeer.com πŸŒπŸ”
16
+
17
+ [GeoSeer](https://geoseeer.com) analyzes images, multiple image clues, videos, and real-world event descriptions to suggest locations and explain the clues behind them. **Fast** provides rapid estimation, **Agent** uses tools and multi-step reasoning for a more extensive search, and **Event** investigates locations from text descriptions.
18
+
19
+ > Upload a photo, image set, or video, or enter an event description β†’ Review location candidates with coordinates, addresses, and reasoning.
20
+
21
+ ---
22
+
23
+ ## How It Works
24
+
25
+ 1. **Submit Input** πŸ“€ β€” Upload an image via the [web interface](https://geoseeer.com) or the [REST API](https://geoseeer.com/api-docs). GeoSeer supports single-image, multi-image, video, image URL, and text-based event analysis on the web.
26
+ 2. **AI Analysis** πŸ€– β€” GeoSeer's agentic analysis system examines visual clues β€” architectural styles, natural landmarks, vegetation patterns, street furniture, signage, satellite data, environmental context, and event-specific context when using Event mode.
27
+ 3. **Location Results** πŸ“ β€” Receive up to 8 location candidates ranked by confidence, each with GPS coordinates, human-readable address, and detailed reasoning explaining the analysis.
28
+
29
+ ### Architecture Overview
30
+
31
+ GeoSeer's agentic pipeline consists of three complementary analysis paths:
32
+
33
+ - **Fast Mode (GS-Fast)** β€” Proprietary geospatial estimation for rapid kilometer-level predictions
34
+ - **Agent Mode (GS-Agent)** β€” Multi-step reasoning and tool calling for more comprehensive pinpointing
35
+ - **Event Mode (GS-Event)** β€” Text-first event investigation for real-world incident and event-location searches
36
+
37
+ Shared system components include:
38
+
39
+ - **Input Processing** β€” Visual media ingestion with metadata extraction (EXIF data, timestamps, camera info)
40
+ - **Model Estimation** β€” Proprietary geospatial estimation model used by GS-Fast and as a signal source for deeper analysis
41
+ - **LVLM Analysis** β€” Large Vision-Language Model analysis for feature extraction and scene understanding
42
+ - **Normalization & Reasoning** β€” Multi-step reasoning that integrates signals from all sources
43
+ - **Tool Calling** β€” Satellite imagery, map data, web search, and reverse image search for verification
44
+ - **Final Reasoning** β€” Comprehensive analysis combining all evidence into precise location candidates
45
+
46
+ ---
47
+
48
+ ## Features
49
+
50
+ - 🧠 **Agentic AI Architecture** β€” Advanced multi-step reasoning with tool calling for pinpoint accuracy
51
+ - ⚑ **Three Processing Modes** β€” Fast for rapid estimation, Agent for a more extensive search, and Event for text-only investigation. Fast measured 10 seconds at API p50 in the October 14, 2026 tests; timing varies with input, load, and network conditions
52
+ - 🌐 **Global Coverage** β€” Geolocate photos, image sets, and video from anywhere on Earth
53
+ - πŸ“ **Event Search Support** β€” Run text-only event geolocation searches without requiring file upload
54
+ - πŸ”’ **Processing & Sharing** β€” Media is stored temporarily during analysis, and cleanup attempts to remove processing files afterward. Saving or sharing a result can retain result data and associated media separately
55
+ - πŸ”Œ **Developer API** β€” Simple REST API with streaming (SSE) support for easy integration
56
+ - 🏒 **Enterprise Ready** β€” Custom rate limits, white-label API access, and self-host support via [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
57
+
58
+ ---
59
+
60
+ ## Performance Benchmarks
61
+
62
+ Updated **November 16, 2026**. Accuracy uses IM2GPS3k, and costs use entry monthly consumer plans with fixed search allowances, falling back to entry prepaid credits when no such plan exists. See the [full results, sources, and methodology](https://geoseeer.com/benchmarks).
63
+
64
+ | Provider | IM2GPS3k accuracy @ 1 km | Latency | Reference paid cost / search |
65
+ |----------|-------------------------|---------|----------------------------------|
66
+ | **GeoSeer** | [**67%**](https://geoseeer.com/benchmarks#accuracy), Agent | **10s**, Fast Β· GeoSeer API p50 | [**$0.19**](https://geoseeer.com/#pricing), Starter $19/month / 100 web searches |
67
+ | GeoAxis | β€” No published IM2GPS3k result | 35s, Global Search Low Β· GeoAxis API | [$0.90](https://geoaxis.ai/pricing), prepaid credits, minimum $10 purchase |
68
+ | Oceanir | [22.52%](https://oceanir.ai/geoestimation), Manta Geo-Estimation | β€” API not tested | [$1.00](https://oceanir.ai/pricing), Starter $10/month / 10 Orca Max detailed analyses |
69
+ | Picarta | [44.8%](https://picarta.ai/picarta-v2), V2.1 | 12s, standard image search Β· Picarta API | [$0.60](https://picarta.ai/pricing), $59.90/month / 100 searches, rounded |
70
+ | GeoInfer | [50%](https://docs.geoinfer.com/faq), Global | [1s](https://geoinfer.com/en), published inference reference | [$0.10](https://geoinfer.com/en/pricing), $4.99 / 50 global predictions, rounded |
71
+
72
+ > Accuracy: GeoSeer tested the full [IM2GPS3k benchmark](https://github.com/lugiavn/revisiting-im2gps) itself; competitor figures are linked vendor-published results from separate evaluations. Model versions, training data, prediction-selection rules, and experimental conditions can differ. Oceanir's accuracy result describes Manta, which requires organizational access; its displayed cost covers public Orca Max analysis.
73
+ >
74
+ > Latency: GeoSeer tested its own, GeoAxis's, and Picarta's APIs. The p50 values retain the October 14, 2026 test snapshot and selected modes. GeoInfer's displayed 1s represents its advertised sub-second inference, rather than a GeoSeer-measured API p50. Oceanir's API has not been timed. GeoAxis now [advertises](https://geoaxis.ai/) approximately 5s for Instant and 20s for Low; these are separate provider-reported production timings.
75
+ >
76
+ > Cost: Apply the same rule to all providers: use the entry monthly consumer plan with a fixed search allowance; otherwise use the entry prepaid pack or published credit rate. Divide price by included complete searches, assuming full utilization before allowance or credit expiry. GeoSeer's denominator is its 100 web searches; its separate API allowance is not added. [GeoAxis](https://geoaxis.ai/pricing) and [GeoInfer](https://geoinfer.com/en/pricing) advertise unlimited consumer subscriptions, whose effective per-search costs depend on actual usage, so the table uses their prepaid rates. GeoInfer [uses one credit per global prediction](https://docs.geoinfer.com/faq). Higher tiers and larger packs are separate: [Oceanir Pro](https://oceanir.ai/pricing) includes 300 detailed analyses for $29/month (about $0.10 each at full utilization). Free allowances, trials, promotions, annual billing, and negotiated enterprise rates are excluded. Commercial API pricing can differ from these consumer search references.
77
+
78
+ Providers were selected for their popularity, strong geolocation accuracy, and public availability at the comparison date. Access-restricted services such as [GeoSpy (now Raven)](https://graylark.com/raven/faq) and broader enterprise platforms such as [Palantir Foundry](https://www.palantir.com/platforms/foundry/) fall outside this product comparison. Individual model access is identified in the methodology.
79
+
80
+ ---
81
+
82
+ ## Getting Started
83
+
84
+ ### On the Web
85
+
86
+ Visit [geoseeer.com](https://geoseeer.com) β€” new users can get started **for free**.
87
+
88
+ 1. Upload or drag & drop your image or video, or enter an event description
89
+ 2. Choose Fast mode for quick estimation, Agent mode for deeper analysis, or Event mode for text-only event investigation
90
+ 3. Optionally add context (country, source, time period, etc.)
91
+ 4. Get precise location results with confidence scores and reasoning
92
+
93
+ ### Via the API
94
+
95
+ Get your API key from the [Dashboard](https://geoseeer.com/dashboard), then send either a media-analysis request or a text-only event-analysis request:
96
+
97
+ ```bash
98
+ curl -X POST https://geoseeer.com/api/v1/analyze \
99
+ -H "X-API-Key: YOUR_API_KEY" \
100
+ -F "file=@photo.jpg" \
101
+ -F "analysis_mode=fast" \
102
+ -F "user_context=Beach photo from summer 2025"
103
+ ```
104
+
105
+ ### Python SDK
106
+
107
+ Install `geoseeer` on Python 3.11 or later and set `GEOSEER_API_KEY` to your GeoSeer API key.
108
+
109
+ ```bash
110
+ pip install geoseeer
111
+ ```
112
+
113
+ ```python
114
+ from geoseeer import GeoSeer
115
+
116
+ client = GeoSeer()
117
+ result = client.analyze(files="photo.jpg", context="A coastal city")
118
+ print(result["locations"])
119
+ ```
120
+
121
+ See the [Python SDK guide](https://github.com/geoseeer/GeoSeer/blob/main/API.md#python-sdk) for URL input, Event mode, and streaming, or the [API documentation](https://geoseeer.com/api-docs) for the full HTTP reference.
122
+
123
+ ---
124
+
125
+ ## Pricing
126
+
127
+ | Plan | Price | Includes |
128
+ |------|-------|----------|
129
+ | **Free** | $0 forever | Fast Mode access, 1 search/day on web, 10 total API calls |
130
+ | **Starter** | $19/month; or $9/month billed annually | All analysis modes, 100 searches/mo, 100 API calls/mo, priority processing |
131
+ | **Pro** | $69/month; or $29/month billed annually | Everything in Starter, unlimited web searches, 1,000 API calls/mo, white-label API access |
132
+ | **Enterprise** | Custom | Custom limits, white-label API access, self-host support β€” [enterprise.geoseeer.com](https://enterprise.geoseeer.com) |
133
+
134
+ > Eligible paid plans can purchase additional web-search or API credits from the dashboard at $0.20 per credit, sold in packs of five.
135
+
136
+ ---
137
+
138
+ ## Use Cases
139
+
140
+ - **OSINT & Investigations** β€” Verify photo locations for open-source intelligence work
141
+ - **Journalism & UGC Verification** β€” Authenticate user-generated content and news sources
142
+ - **Academic Research** β€” Study geospatial patterns, verify historical image locations
143
+ - **Supply Chain & Logistics** β€” Geolocate assets and shipment photos
144
+ - **AI Agent Infrastructure** β€” Integrate geolocation capabilities into autonomous AI systems
145
+ - **Enterprise Applications** β€” Build geolocation-powered features into your products
146
+
147
+ ---
148
+
149
+ ## About
150
+
151
+ GeoSeer is developed by **Shenzhen Ques Technology Co., Ltd.** ([quesx.com](https://quesx.com)) as part of the company's OSINT (Open-Source Intelligence) infrastructure ecosystem. Our mission is to make professional geolocation capabilities accessible to everyone β€” from individual investigators and researchers to AI agents and enterprise systems.
152
+
153
+ ---
154
+
155
+ ## Links
156
+
157
+ - 🌐 **Website**: [geoseeer.com](https://geoseeer.com)
158
+ - πŸ“– **API Docs**: [geoseeer.com/api-docs](https://geoseeer.com/api-docs)
159
+ - 🏒 **Enterprise**: [enterprise.geoseeer.com](https://enterprise.geoseeer.com)
160
+ - πŸ“ **Blog**: [geoseeer.com/blog](https://geoseeer.com/blog)
161
+ - πŸ’Ό **Careers**: [geoseeer.com/careers](https://geoseeer.com/careers)
162
+
163
+ ### Social
164
+
165
+ - [X (Twitter)](https://x.com/GeoSeeer)
166
+ - [LinkedIn](https://www.linkedin.com/company/geoseer)
167
+ - [Instagram](https://www.instagram.com/geoseeer/)
168
+ - [TikTok](https://www.tiktok.com/@geoseeer)
169
+ - [YouTube](https://www.youtube.com/@geoseeer)
170
+ - [Facebook](https://www.facebook.com/profile.php?id=61583773556872)
171
+
172
+ ---
173
+
174
+ ## Contact
175
+
176
+ For inquiries, enterprise partnerships, or support, visit [geoseeer.com/about](https://geoseeer.com/about) or reach out through our social channels.
177
+
178
+ ---
179
+
180
+ Β© 2025-2026 GeoSeer. All rights reserved.
@@ -0,0 +1,11 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/geoseeer/__init__.py
5
+ src/geoseeer/client.py
6
+ src/geoseeer.egg-info/PKG-INFO
7
+ src/geoseeer.egg-info/SOURCES.txt
8
+ src/geoseeer.egg-info/dependency_links.txt
9
+ src/geoseeer.egg-info/requires.txt
10
+ src/geoseeer.egg-info/top_level.txt
11
+ tests/test_client.py
@@ -0,0 +1 @@
1
+ requests<3,>=2.32.5
@@ -0,0 +1 @@
1
+ geoseeer
@@ -0,0 +1,141 @@
1
+ import io
2
+ import json
3
+ import os
4
+ import tempfile
5
+ import unittest
6
+ from pathlib import Path
7
+ from unittest.mock import patch
8
+
9
+ import requests
10
+
11
+ from geoseeer import APIError, GeoSeer, GeoSeerError
12
+
13
+
14
+ def response(body, *, status=200, content_type="application/json"):
15
+ result = requests.Response()
16
+ result.status_code = status
17
+ result.headers["Content-Type"] = content_type
18
+ result.raw = io.BytesIO(body)
19
+ return result
20
+
21
+
22
+ class GeoSeerTests(unittest.TestCase):
23
+ def setUp(self):
24
+ environment = patch.dict(os.environ, {"GEOSEER_API_KEY": "test-key"}, clear=True)
25
+ environment.start()
26
+ self.addCleanup(environment.stop)
27
+ sender = patch.object(requests.Session, "send")
28
+ self.send = sender.start()
29
+ self.addCleanup(sender.stop)
30
+ self.send.return_value = response(b'{"status":"success","locations":[]}')
31
+ self.client = GeoSeer()
32
+
33
+ def test_single_url_uses_hosted_api_and_environment_key(self):
34
+ result = self.client.analyze(urls="https://example.com/photo.jpg", context="A coast")
35
+ request = self.send.call_args.args[0]
36
+ self.assertEqual(request.method, "POST")
37
+ self.assertEqual(request.url, "https://geoseeer.com/api/v1/analyze")
38
+ self.assertEqual(request.headers["X-API-Key"], "test-key")
39
+ self.assertFalse(self.send.call_args.kwargs["allow_redirects"])
40
+ self.assertEqual(json.loads(request.body), {
41
+ "analysis_mode": "fast",
42
+ "stream": False,
43
+ "url": "https://example.com/photo.jpg",
44
+ "user_context": "A coast",
45
+ })
46
+ self.assertEqual(result, {"status": "success", "locations": []})
47
+
48
+ def test_event_uses_json_without_media_fields(self):
49
+ client = GeoSeer("explicit-key", base_url="https://example.com/api/v1/")
50
+ client.analyze(event_text="An event at Lusail Stadium")
51
+ request = self.send.call_args.args[0]
52
+ self.assertEqual(request.url, "https://example.com/api/v1/analyze")
53
+ self.assertEqual(request.headers["X-API-Key"], "explicit-key")
54
+ self.assertEqual(json.loads(request.body), {
55
+ "analysis_mode": "event",
56
+ "stream": False,
57
+ "event_text": "An event at Lusail Stadium",
58
+ })
59
+
60
+ def test_multiple_uploads_repeat_files_field(self):
61
+ with tempfile.TemporaryDirectory() as folder:
62
+ front = Path(folder) / "front.jpg"
63
+ side = Path(folder) / "side.png"
64
+ front.write_bytes(b"front image bytes")
65
+ side.write_bytes(b"side image bytes")
66
+ self.client.analyze(files=[front, str(side)], mode="agent")
67
+ request = self.send.call_args.args[0]
68
+ self.assertTrue(request.headers["Content-Type"].startswith("multipart/form-data;"))
69
+ self.assertEqual(request.body.count(b'name="files"'), 2)
70
+ self.assertIn(b'filename="front.jpg"', request.body)
71
+ self.assertIn(b"front image bytes", request.body)
72
+ self.assertIn(b'filename="side.png"', request.body)
73
+ self.assertIn(b"side image bytes", request.body)
74
+ self.assertIn(b'name="stream"\r\n\r\nfalse\r\n', request.body)
75
+
76
+ def test_invalid_input_does_not_send_a_request(self):
77
+ for arguments in (
78
+ {},
79
+ {"urls": []},
80
+ {"files": ["a"] * 4},
81
+ {"urls": "u", "files": "f"},
82
+ {"event_text": "e", "mode": "fast"},
83
+ ):
84
+ with self.subTest(arguments=arguments), self.assertRaises(ValueError):
85
+ self.client.analyze(**arguments)
86
+ self.send.assert_not_called()
87
+
88
+ def test_json_http_error_preserves_details_and_retry_header(self):
89
+ self.send.return_value = response(
90
+ b'{"error":{"code":"rate_limited","message":"Slow down","details":{"retry_after_seconds":3}}}',
91
+ status=429,
92
+ )
93
+ self.send.return_value.headers["Retry-After"] = "3"
94
+ with self.assertRaisesRegex(APIError, "Slow down") as exc:
95
+ self.client.analyze(urls="https://example.com/photo.jpg")
96
+ self.assertEqual(exc.exception.status_code, 429)
97
+ self.assertEqual(exc.exception.code, "rate_limited")
98
+ self.assertEqual(exc.exception.details, {"retry_after_seconds": 3})
99
+ self.assertEqual(exc.exception.retry_after, "3")
100
+ self.send.assert_called_once()
101
+
102
+ def test_stream_handles_keepalives_and_multiline_events(self):
103
+ first_data_line = b'data: {"type":"progress",\r'
104
+ # Put the first data line's CR and LF in separate read chunks.
105
+ comment = b":" + b" " * (509 - len(first_data_line)) + b"\r\n"
106
+ self.assertEqual(len(comment + first_data_line), 512)
107
+ self.send.return_value = response(
108
+ comment + first_data_line + '\ndata: "message":"ZΓΌrich"}\r\n\r\nevent: completed\n'
109
+ 'data: {"type":"complete","result":{"locations":[]}}\n\n'.encode(),
110
+ content_type="text/event-stream; charset=utf-8",
111
+ )
112
+ with self.client.stream(urls=["https://example.com/a.jpg", "https://example.com/b.jpg"]) as events:
113
+ self.assertEqual(list(events), [
114
+ {"type": "progress", "message": "ZΓΌrich"},
115
+ {"type": "complete", "result": {"locations": []}},
116
+ ])
117
+ request = self.send.call_args.args[0]
118
+ self.assertTrue(self.send.call_args.kwargs["stream"])
119
+ self.assertEqual(json.loads(request.body), {
120
+ "analysis_mode": "fast",
121
+ "stream": True,
122
+ "urls": ["https://example.com/a.jpg", "https://example.com/b.jpg"],
123
+ })
124
+ self.assertTrue(self.send.return_value.raw.closed)
125
+
126
+ def test_stream_reports_premature_end(self):
127
+ self.send.return_value = response(b'data: {"type":"progress"}\n\n', content_type="text/event-stream")
128
+ with patch.object(self.send.return_value, "close", wraps=self.send.return_value.close) as close:
129
+ with self.client.stream(event_text="An event") as events:
130
+ self.assertEqual(next(events), {"type": "progress"})
131
+ with self.assertRaisesRegex(GeoSeerError, "before a terminal event"):
132
+ next(events)
133
+ close.assert_called_once()
134
+
135
+ def test_stream_exposes_terminal_api_error(self):
136
+ event = {"type": "error", "error_code": "invalid_request", "message": "Analysis failed"}
137
+ self.send.return_value = response(
138
+ f"data: {json.dumps(event)}\n\n".encode(), content_type="text/event-stream",
139
+ )
140
+ with self.client.stream(event_text="An event") as events:
141
+ self.assertEqual(list(events), [event])