API Documentation

Integrate GeoSeer's powerful AI geolocation capabilities into your applications with our simple REST API.

Quick Start

Get started with the GeoSeer API in minutes:

FileURL
curl -X POST https://geoseeer.com/api/v1/analyze \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -F "image=@photo.jpg" \\
  -F "user_context=Beach photo from summer 2025"

Response Format

Returns up to 8 location candidates, ordered by confidence.

{
  "status": "success",
  "locations": [
    {
      "latitude": 48.8584,
      "longitude": 2.2945,
      "confidence": 0.95,
      "address": "Eiffel Tower, Paris, France",
      "reasoning": "The image shows the Eiffel Tower..."
    },
    {
      "latitude": 48.8530,
      "longitude": 2.3499,
      "confidence": 0.72,
      "address": "Notre-Dame, Paris, France",
      "reasoning": "Gothic cathedral architecture..."
    }
  ],
  "processing_time": "45.2s"
}

Streaming Format

Set stream: true for real-time Server-Sent Events (SSE) updates during analysis.

Event Types

processingProgress updates during analysis
branch_pointWhen engine searches multiple regions in parallel
branch_updateStatus change for a search branch
completedFinal result with candidates array
errorError occurred during processing

Example SSE Events

// Progress update
event: processing
data: {"type":"progress",
       "message":"Analyzing visual features",
       "branch_id":"main_llm_primary",
       "timestamp":1737312000.123}

// Final result
event: completed
data: {"type":"complete",
       "result":{
         "status":"success",
         "candidates":[{
           "rank":1,
           "coordinates":{"latitude":48.8584,"longitude":2.2945},
           "address":"Eiffel Tower, Paris",
           "confidence":0.95,
           "branch_id":"main_llm_primary"
         }],
         "processing_time":45.2
       }}

Implementation Examples

import requests
import sseclient  # pip install sseclient-py
import json

API_KEY = "YOUR_API_KEY"

def analyze_with_streaming(image_url):
    response = requests.post(
        "https://geoseeer.com/api/v1/analyze",
        headers={"X-API-Key": API_KEY, ...},
        json={"image_url": image_url, "stream": True},
        stream=True
    )

    client = sseclient.SSEClient(response)
    for event in client.events():
        data = json.loads(event.data)

        if event.event == "processing":
            print(f"[{data.get('branch_id', '')}] {data.get('message')}")
        elif event.event == "completed":
            result = data.get("result", {}})  # Contains candidates array
            return result
        elif event.event == "error":
            print(f"Error: {data.get('error')}")

API Key

Get your API key from the dashboard to start making requests.

Rate Limits

Free Plan
1 request/second
Starter Plan
1 request/second
Pro Plan
1 request/second
Enterprise Plan
Custom limits - visit enterprise.geoseeer.com

Supported Formats

JPGPNGWebPHEIC

Max file size: 10 MB

Endpoints

POST
/api/v1/analyze

Analyze an image. Set stream=true for real-time SSE progress updates, or stream=false for blocking response.

Error Codes

400Invalid request
401Unauthorized
402Credits depleted
413File too large
429Rate limited
500Server error