GeoInfer Python SDK

The official Python client library for the GeoInfer API — AI-powered image geolocation without GPS, EXIF, or metadata.

What is GeoInfer?

GeoInfer determines where a photo was taken by analysing its visual content alone — no GPS signal, no EXIF data, no metadata required. Results are delivered in under a second, with global coverage including remote regions, conflict zones, and GPS-denied environments.

The API exposes two model families:

Note: Accuracy models are region-specific and generally whitelisted — they are not available to the general public. Contact geoinfer.com to enquire about access.

Requirements

• Python 3.9 or later
• A GeoInfer API key — get one at geoinfer.com

Installation

pip install geoinfer

Quick start

from geoinfer import GeoInfer

client = GeoInfer(api_key="geo_...")

# List models your API key has access to
for m in client.predictions.models():
    print(m.model_id, m.model_type, f"{m.credits_per_use} credit(s)")

# Global model — returns geographic clusters
result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
top = result.prediction.clusters[0]
print(top.location.name, top.center.latitude, top.center.longitude)

# Accuracy / regional model — returns ranked predictions
result = client.predictions.predict("photo.jpg", model_id="pais_vasco_v0_1")
top = result.prediction.top_prediction
if top:
    print(top.latitude, top.longitude, f"{top.confidence:.1%} confidence")

Authentication

Pass your API key at client construction. It is sent as the X-GeoInfer-Key header on every request.

client = GeoInfer(api_key="geo_...")

API keys can be managed from your dashboard at geoinfer.com.

Model access

Available models are determined by your API key — some models are public and some are whitelisted per account. models() returns only the models your key has access to:

models = client.predictions.models()
for m in models:
    print(m.model_id, m.model_type, m.credits_per_use)

The model list is fetched on first use and cached for 5 minutes. Passing a model_id that is unknown to your account or disabled raises InvalidModelError immediately — before any prediction request is made.

Async support

AsyncGeoInfer mirrors the synchronous client and is safe to use in any asyncio application:

import asyncio
from geoinfer import AsyncGeoInfer

async def main():
    async with AsyncGeoInfer(api_key="geo_...") as client:
        result = await client.predictions.predict("photo.jpg", model_id="global_v0_1")
        top = result.prediction.clusters[0]
        print(top.location.name, top.center.latitude, top.center.longitude)

asyncio.run(main())

File input

predict() accepts five input forms:

from pathlib import Path

# URL — the SDK fetches the image and uploads it automatically
client.predictions.predict("https://example.com/photo.jpg", model_id="global_v0_1")

# Path string
client.predictions.predict("photo.jpg", model_id="global_v0_1")

# pathlib.Path
client.predictions.predict(Path("photo.jpg"), model_id="global_v0_1")

# Raw bytes (already loaded into memory)
with open("photo.jpg", "rb") as f:
    client.predictions.predict(f.read(), model_id="global_v0_1")

# Binary file-like object (streamed)
with open("photo.jpg", "rb") as f:
    client.predictions.predict(f, model_id="global_v0_1")

URL inputs are fetched client-side and uploaded as bytes — the image is not stored or cached. Any http:// or https:// string is treated as a URL. File objects must be opened in binary mode ("rb"); passing a text-mode object raises TypeError.

Maximum file size: 10 MB.

Credits

Each prediction consumes credits according to the model used. Check your balance at any time:

summary = client.credits.summary()
print(summary.summary.total_available)    # total credits available now
print(summary.subscription.remaining)     # subscription allowance remaining
print(summary.summary.topup_credits)      # one-time top-up balance

Credits consumed are reported on every PredictionResponse:

result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
print(f"Used {result.credits_consumed} credit(s). ID: {result.prediction_id}")

Rate limits

Rate-limit metadata is attached to every PredictionResponse:

result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
rl = result.rate_limit
print(f"{rl.remaining} requests remaining, window resets in {rl.reset}s")

When the limit is exceeded RateLimitError is raised with a retry_after attribute:

import time
from geoinfer import RateLimitError

try:
    result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
except RateLimitError as e:
    if e.retry_after:
        time.sleep(e.retry_after)

Error handling

All SDK exceptions inherit from GeoInferError.

from geoinfer import (
    GeoInferError,
    AuthenticationError,
    InsufficientCreditsError,
    InvalidModelError,
    RateLimitError,
)

try:
    result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
except InvalidModelError as e:
    print(e.message)                  # includes a list of your available model IDs
except RateLimitError as e:
    if e.retry_after:
        time.sleep(e.retry_after)
except InsufficientCreditsError:
    print("Top up credits at geoinfer.com")
except AuthenticationError:
    print("Check your API key at geoinfer.com")
except GeoInferError as e:
    print(e.message_code, e.message)

Context managers

Both clients support context managers for deterministic connection cleanup:

# Sync
with GeoInfer(api_key="geo_...") as client:
    result = client.predictions.predict("photo.jpg", model_id="global_v0_1")

# Async
async with AsyncGeoInfer(api_key="geo_...") as client:
    result = await client.predictions.predict("photo.jpg", model_id="global_v0_1")

Configuration

Type safety

All response objects are immutable frozen dataclasses. Narrow on result.prediction.result_type to get the specific prediction type:

from geoinfer.types import CoordinatePredictionResult, AccuracyPredictionResult

result = client.predictions.predict("photo.jpg", model_id="global_v0_1")
if isinstance(result.prediction, CoordinatePredictionResult):
    print(result.prediction.clusters[0].location.name)
elif isinstance(result.prediction, AccuracyPredictionResult):
    print(result.prediction.top_prediction.confidence)

License

Apache 2.0 — see LICENSE.