API Reference

POST /api/v1/geolocate

Submit one image, get ranked coordinates with confidence and visual reasoning. Authenticate with your key in Authorization: Bearer <key> or x-api-key: <key> — both work. For retry-safe execution and billing, reuse the same Idempotency-Key for every retry of one analysis. A completed retry replays the original response without another model call or credit debit; using that key with a different payload returns HTTP 409.

Request body (JSON)

Example request

curl -X POST https://oceanir.ai/api/v1/geolocate \
  -H "Authorization: Bearer orc_YOUR_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/street.jpg",
    "batch_id": "batch_YOUR_BATCH_ID",
    "depth": 2,
    "scope": { "name": "Lyon", "lat": 45.764, "lng": 4.836, "radius_km": 60 }
  }'

200 response

{
  "success": true,
  "analysis_id": "an_8X2k...",
  "location": {
    "latitude": 45.7700,
    "longitude": 4.8459,
    "country": "France",
    "city": "Lyon",
    "neighborhood": "6th arrondissement",
    "address": "Rue de Créqui, 69006 Lyon"
  },
  "confidence": 0.88,
  "reasoning": "French street signage, Haussmann facades, plane trees...",
  "thinking": "<step-by-step cues — depth >= 2 only>",
  "visual_clues": [
    { "label": "Street sign", "detail": "" },
    { "label": "Haussmann facade", "detail": "" }
  ],
  "model": "orca-1.5",
  "batch_id": "batch_YOUR_BATCH_ID",
  "depth": 2,
  "timing_ms": 9120
}

confidence is 0–1. thinking and visual_clues are returned only at depth ≥ 2. Each clue is { label, detail }. detail is currently always empty, and clues carry no image coordinates — this example previously showed x and y fields the API has never returned.

The forensic object (depth 3 only)

At depth 3 the response carries an additional forensic object. This is what separates a forensic call from a standard one: instead of a single coordinate, you get the evidence the conclusion rests on, the evidence that argues against it, and the alternative locations that were considered and rejected. It is designed to be shown to a reviewer, not just consumed by a program.

"forensic": {
  "precision_tier": "block",
  "verification_status": "partially_verified",
  "supports": [
    "Street sign reads 'Rue de Créqui'",
    "Haussmann-era facade with 6th-arrondissement cornice detail"
  ],
  "contradictions": [
    "Bollard style is more common in Lyon 3e than 6e"
  ],
  "candidates": [
    {
      "label": "Rue Vendôme, Lyon 6e",
      "lat": 45.7688,
      "lng": 4.8441,
      "confidence": 62,
      "supports": ["Matching tree spacing"],
      "contradictions": ["Street sign does not match"]
    }
  ]
}

Confidence is reported as the model assesses it and is not inflated when evidence is thin. A low score with populated contradictions is the system telling you it is not certain, which is the signal you want in a claim, a dispute, or a moderation decision.

Errors