api

TERRA API

Overview

The TERRA API accepts an image and returns a geographic prediction with confidence scoring, evidence summary, and model consensus data. Four ML models run in parallel (SigLIP, StreetCLIP, OSV-5M, PLONK), retrieval from a 5M+ reference index, and Gemini reasoning produce the final result.

POST /api/v1/predict/upload

Upload an image file for geolocation prediction.

POST/api/v1/predict/upload

Content-Type: multipart/form-data

Parameters

fileFile (required)JPEG, PNG, or WebP image. Max 20MB.

Example Request

bash

curl -X POST https://geolocator-api-dev-xxx.run.app/api/v1/predict/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@photo.jpg"

Example Response

json

{
  "request_id": "pred_a1b2c3d4...",
  "status": "success",
  "top_prediction": {
    "latitude": 47.3769,
    "longitude": 8.5417,
    "country": "CH",
    "region": "Zürich",
    "city": "Zürich"
  },
  "confidence": 0.82,
  "uncertainty_radius_meters": 12400,
  "evidence_summary": "Swiss urban streetscape...",
  "candidate_predictions": [...],
  "model_consensus": {...},
  "timing_breakdown_ms": {...}
}

Response Fields

request_idstringUnique prediction identifier

statusstring"success" or "error"

top_predictionobjectBest prediction with lat, lon, country, region, city

confidencefloatComposite confidence score 0.0–1.0

uncertainty_radius_metersintUncertainty radius in meters

evidence_summarystringHuman-readable evidence explanation

evidence_sourcestring"model_consensus" or "visual_analysis"

candidate_predictionsarrayRanked alternative predictions

model_consensusobjectPer-model outputs (StreetCLIP, OSV-5M, PLONK)

timing_breakdown_msobjectPer-stage timing in milliseconds

Rate Limits

60 requests per minute per IP. Returns 429 when exceeded.

Error Codes

400Invalid image format or both image and image_url provided

413Image exceeds 20MB limit

422Image could not be decoded

429Rate limit exceeded

500Internal service error