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 }
  }'

Illustrative D2 response

{
  "success": true,
  "analysis_id": "example-analysis-id",
  "location": {
    "latitude": 45.77,
    "longitude": 4.8459,
    "country": "France",
    "city": "Lyon",
    "neighborhood": "6th arrondissement",
    "address": "Lyon, France"
  },
  "confidence": 0.79,
  "reasoning": "Street signage and architecture suggest Lyon. Confirm the area with independent evidence.",
  "visual_clues": [
    {
      "label": "French street signage",
      "detail": ""
    },
    {
      "label": "Stone facades",
      "detail": ""
    }
  ],
  "model": "orca-1.5",
  "depth": 2,
  "timing_ms": 9120
}

confidence is 0–1. thinking and visual_clues are returned only at depth ≥ 2. Each clue is { label, detail }. The detail may be empty. Image coordinates and contours are optional and appear only when available; integrations must also handle clues without them.

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