API Reference

Complete reference for all Oceanir REST API endpoints. All endpoints require authentication via API key.

Base URL

https://oceanir.ai/api/v1

Authentication

Include your API key in the x-api-key header:

x-api-key: orca_live_...

Credit costs

API calls deduct from your monthly credit allowance. Same unit as the web app, no separate metered billing. When you run out, top up with a credit pack or upgrade your plan.

FeatureTierCreditsNotes

Geolocation analysisD1, Surface1Region-level coordinates

Geolocation analysisD2, Standard3Block-level radius with visual evidence chain

Geolocation analysisD3, Forensic10Street-level lock with full reasoning + contradiction flags

Property search—4Parcel + ownership lookup

Bulk analysisPer image5CSV batch endpoint, deducted per processed image

Example: Pro (100 credits/month) covers ~10 D3 analyses, ~50 D2 analyses, or 100 D1 analyses per month. Mix and match as needed.

Endpoints

POST/api/v1/geolocateSubmit an image for geolocation analysis

GET/api/v1/geolocate/{id}Retrieve a previous geolocation result

GET/api/v1/creditsCheck your current credit balance

POST/api/v1/mesh/camerasQuery the camera intelligence network

GET/api/v1/mesh/cameras/{id}Get details for a specific camera

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 billing, reuse the same Idempotency-Key for every retry of one analysis.

Request body (JSON)

image_b64stringone ofBase64-encoded JPEG/PNG. Max 20MB.

image_urlstringone ofPublic URL to fetch the image from instead.

depthintegeroptional1 = Surface (region, 1 credit), 2 = Standard (block, 3), 3 = Forensic (street, 10). Default 1.

Example request

curl -X POST https://oceanir.ai/api/v1/geolocate \
  -H "Authorization: Bearer orca_live_YOUR_KEY" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/street.jpg",
    "depth": 2
  }'

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": "Rue de Créqui", "x": 0.41, "y": 0.32 }
  ],
  "model": "orca-2.1",
  "depth": 2,
  "timing_ms": 9120
}

confidence is 0–1. thinking and visual_clues are returned only at depth ≥ 2.

Errors

401Missing or invalid API key.

402Insufficient credits for the requested depth.

422No image_b64 or image_url provided.

429Rate limit exceeded — retry after retry_after seconds.

502Analysis failed upstream. Retry, or lower the depth.