Utilities API Reference

Complete API documentation for all De. Utilities endpoints.

Base URL

https://api.dedot.app/realm/utilities

Authentication

All utility endpoints require authentication via API key:

bash

Authorization: Bearer YOUR_API_KEY

Delivery Fees Calculator

Calculate last-mile delivery costs with LSP integration.

POST /fares/delivery

Request Body:

typescript

{
  origin: {
    address?: string
    city?: string
    country: string
    zip?: string
    coordinates?: [number, number] // [lat, lng]
  }
  destination: {
    address?: string
    city?: string
    country: string
    zip?: string
    coordinates?: [number, number]
  }
  serviceLevel: 'SAME_DAY' | 'NEXT_DAY' | 'STANDARD' | 'EXPRESS'
  weight: {
    value: number
    unit: 'kg' | 'lb' | 'g' | 't'
  }
  dimensions?: {
    length: number
    width: number
    height: number
    unit: 'cm' | 'in' | 'm'
  }
  packageType?: string
}

Response:

typescript

{
  error: false
  status: 'UTILITY::FEE_CALCULATED'
  result: {
    totalFee: number
    currency: string
    breakdown: {
      baseFee: number
      distanceFee: number
      weightFee: number
      serviceFee: number
      fuelSurcharge?: number
      seasonalAdjustment?: number
    }
    serviceLevel: string
    estimatedDeliveryTime?: {
      min: { day: number }
      max: { day: number }
    }
    metadata: {
      accuracy: 'ESTIMATE' | 'STANDARD' | 'PRECISE'
      confidence: number // 0-1
      dataSource: 'LSP' | 'FALLBACK' | 'HYBRID'
      calculatedAt: number
      disclaimer: string
    }
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/fares/delivery \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "country": "NG",
      "city": "Lagos",
      "coordinates": [6.5244, 3.3792]
    },
    "destination": {
      "country": "NG",
      "city": "Abuja",
      "coordinates": [9.0765, 7.3986]
    },
    "serviceLevel": "NEXT_DAY",
    "weight": { "value": 5, "unit": "kg" }
  }'

Transport Fare Calculator

Multi-modal freight pricing with fleet capabilities.

POST /fares/transport

Request Body:

typescript

{
  origin: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  destination: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  transportMode: 'ROAD' | 'AIR' | 'SEA' | 'RAIL'
  vehicleType?: string // 'CONTAINER_TRUCK', 'CARGO_PLANE', etc.
  cargo: {
    weight: {
      value: number
      unit: 'kg' | 'lb' | 'g' | 't'
    }
    volume?: {
      value: number
      unit: 'm3' | 'ft3' | 'L'
    }
    type?: string
    hazardous?: boolean
  }
  urgency?: 'URGENT' | 'STANDARD' | 'ECONOMY'
}

Response:

typescript

{
  error: false
  status: 'UTILITY::FARE_CALCULATED'
  result: {
    baseFare: number
    distanceFare: number
    weightFare: number
    fuelSurcharge: number
    totalFare: number
    currency: string
    distance: {
      kilometer: number
      mile: number
    }
    estimatedDuration?: {
      hour: number
      day: number
    }
    availableVehicles?: number
    metadata: {
      accuracy: 'ESTIMATE' | 'STANDARD' | 'PRECISE'
      confidence: number
      dataSource: 'LSP' | 'FALLBACK' | 'HYBRID'
      calculatedAt: number
    }
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/fares/transport \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "country": "NG", "city": "Lagos" },
    "destination": { "country": "NG", "city": "Kano" },
    "transportMode": "ROAD",
    "vehicleType": "CONTAINER_TRUCK",
    "cargo": {
      "weight": { "value": 5000, "unit": "kg" }
    }
  }'

Ride-Hailing Fare Calculator

Real-time ride pricing with surge and nearby drivers.

POST /fares/ride

Request Body:

typescript

{
  pickup: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  dropoff: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  vehicleClass?: 'ECONOMY' | 'STANDARD' | 'COMFORT' | 'PREMIUM' | 'LUXURY' | 'XL' | 'SUV'
  passengerCount?: number
  requestTime?: number // Unix timestamp
  includeNearbyDrivers?: boolean
}

Response:

typescript

{
  error: false
  status: 'UTILITY::FARE_CALCULATED'
  result: {
    estimatedFare: {
      baseFare: number
      distanceFare: number
      timeFare: number
      surgeFare: number
      bookingFee: number
      totalBeforeSurge: number
      totalAfterSurge: number
      minimumFare: number
      currency: string
    }
    surgeInfo: {
      multiplier: number
      reason: string
      isActive: boolean
    }
    tripEstimate: {
      distance: { kilometer: number, mile: number }
      duration: { minute: number, hour: number }
      confidence: number
    }
    pickupEstimate: {
      eta: { minute: number }
      nearbyDrivers: number
      averageDistance?: number
    }
    metadata: {
      accuracy: 'ESTIMATE' | 'STANDARD' | 'PRECISE'
      confidence: number
      dataSource: 'LSP' | 'FALLBACK' | 'HYBRID'
      calculatedAt: number
    }
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/fares/ride \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup": {
      "country": "GH",
      "city": "Accra",
      "coordinates": [5.6037, -0.1870]
    },
    "dropoff": {
      "coordinates": [5.6500, -0.2000]
    },
    "vehicleClass": "ECONOMY",
    "includeNearbyDrivers": true
  }'

Vehicle Classes:

Class	Description	Base Fare	Per KM	Per Min
ECONOMY	Budget rides	$2.50	$0.90	$0.30
STANDARD	Regular comfort	$3.00	$1.10	$0.35
COMFORT	Enhanced comfort	$3.50	$1.30	$0.40
PREMIUM	Premium sedans	$5.00	$1.80	$0.55
LUXURY	Luxury vehicles	$8.00	$2.50	$0.80
XL	6+ passengers	$4.50	$1.50	$0.50
SUV	SUV vehicles	$5.50	$1.70	$0.60

Surge Multipliers:

Peak hours (7-9 AM, 5-7 PM): 1.5x
Weekend nights (Fri-Sat 10 PM-2 AM): 1.8x
Late night (2-5 AM): 1.3x
Normal: 1.0x

Cross-Border Fare Calculator

International shipping with customs and duties.

POST /fares/crossborder

Request Body:

typescript

{
  origin: {
    address?: string
    city?: string
    country: string
  }
  destination: {
    address?: string
    city?: string
    country: string
  }
  shipment: {
    weight: {
      value: number
      unit: 'kg' | 'lb' | 'g' | 't'
    }
    declaredValue: {
      amount: number
      currency: string
    }
    hsCode?: string // Harmonized System code
    description: string
    quantity: number
  }
  transportMode: 'ROAD' | 'AIR' | 'SEA' | 'RAIL'
  incoterms?: 'EXW' | 'FCA' | 'CPT' | 'CIP' | 'DAP' | 'DPU' | 'DDP' | 'FAS' | 'FOB' | 'CFR' | 'CIF'
}

Response:

typescript

{
  error: false
  status: 'UTILITY::FARE_ESTIMATED'
  result: {
    totalCost: {
      amount: number
      currency: string
    }
    breakdown: {
      transportFee: { amount: number, currency: string }
      customsDuty?: { amount: number, currency: string }
      vat?: { amount: number, currency: string }
      importTax?: { amount: number, currency: string }
      brokerageFee: { amount: number, currency: string }
      documentationFee: { amount: number, currency: string }
      inspectionFee?: { amount: number, currency: string }
      borderCrossingFee: { amount: number, currency: string }
      additionalFees?: Array<{
        name: string
        amount: { amount: number, currency: string }
      }>
    }
    currency: string
    duties?: {
      rate: number // Percentage
      amount: { amount: number, currency: string }
      hsCode?: string
    }
    requiredDocuments: string[]
    estimatedClearanceTime: {
      min: { day: number }
      max: { day: number }
    }
    validUntil: number
    metadata: {
      accuracy: 'ESTIMATE' | 'STANDARD' | 'PRECISE'
      confidence: number
      dataSource: 'LSP' | 'FALLBACK' | 'HYBRID'
      calculatedAt: number
      disclaimer: string
    }
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/fares/crossborder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "country": "US", "city": "Los Angeles" },
    "destination": { "country": "NG", "city": "Lagos" },
    "shipment": {
      "weight": { "value": 100, "unit": "kg" },
      "declaredValue": { "amount": 5000, "currency": "USD" },
      "hsCode": "8517.12",
      "description": "Mobile phones",
      "quantity": 50
    },
    "transportMode": "SEA",
    "incoterms": "CIF"
  }'

Distance Calculator

Multi-modal distance calculation.

POST /distance

Request Body:

typescript

{
  origin: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  destination: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  mode: 'ROAD' | 'AIR' | 'SEA' | 'RAIL'
}

Response:

typescript

{
  error: false
  status: 'UTILITY::DISTANCE_CALCULATED'
  result: {
    distance: {
      value: number // kilometers
      unit: 'km'
      miles: number
    }
    mode: string
    calculatedAt: number
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/distance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "country": "NG", "city": "Lagos" },
    "destination": { "country": "NG", "city": "Abuja" },
    "mode": "ROAD"
  }'

Zone Assignment

Geographic zone determination.

POST /zone

Request Body:

typescript

{
  location: {
    address?: string
    city?: string
    country: string
    coordinates?: [number, number]
  }
  serviceType?: 'DELIVERY' | 'WAREHOUSE' | 'TERMINAL'
}

Response:

typescript

{
  error: false
  status: 'UTILITY::ZONE_ASSIGNED'
  result: {
    zone: {
      id: string
      name: string
      type: string
      coverage: string
    }
    serviceType: string
    calculatedAt: number
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/zone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "country": "NG",
      "city": "Lagos",
      "coordinates": [6.5244, 3.3792]
    },
    "serviceType": "DELIVERY"
  }'

Nearby Vehicle Search

Geospatial search for available vehicles.

POST /nearby/search

Radius-based search for nearby vehicles.

Request Body:

typescript

{
  location: {
    lat: number
    lng: number
  }
  radius: number // meters
  vehicleType?: string
  status?: 'AVAILABLE' | 'BUSY' | 'OFFLINE'
  limit?: number
}

Response:

typescript

{
  error: false
  status: 'UTILITY::SEARCH_COMPLETE'
  result: {
    vehicles: Array<{
      id: string
      type: string
      status: string
      location: { lat: number, lng: number }
      distance: number // meters
    }>
    count: number
    searchRadius: number
    location: { lat: number, lng: number }
  }
}

POST /nearby/bounds

Bounding box search for vehicles.

Request Body:

typescript

{
  bounds: {
    northeast: { lat: number, lng: number }
    southwest: { lat: number, lng: number }
  }
  vehicleType?: string
  status?: 'AVAILABLE' | 'BUSY' | 'OFFLINE'
  limit?: number
}

POST /nearby/nearest

Find N nearest vehicles.

Request Body:

typescript

{
  location: {
    lat: number
    lng: number
  }
  count: number
  vehicleType?: string
  status?: 'AVAILABLE' | 'BUSY' | 'OFFLINE'
  maxDistance?: number // meters
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/nearby/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": { "lat": 5.6037, "lng": -0.1870 },
    "radius": 5000,
    "vehicleType": "SEDAN",
    "status": "AVAILABLE",
    "limit": 10
  }'

ETA Calculator

Arrival time estimation.

POST /eta

Request Body:

typescript

{
  origin: {
    coordinates: [number, number]
  }
  destination: {
    coordinates: [number, number]
  }
  mode: 'ROAD' | 'AIR' | 'SEA' | 'RAIL'
  departureTime?: number // Unix timestamp
}

Response:

typescript

{
  error: false
  status: 'UTILITY::ETA_CALCULATED'
  result: {
    estimatedArrival: number // Unix timestamp
    duration: {
      minute: number
      hour: number
    }
    distance: {
      kilometer: number
    }
    calculatedAt: number
  }
}

Example:

bash

curl -X POST https://api.dedot.app/realm/utilities/eta \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "coordinates": [6.5244, 3.3792] },
    "destination": { "coordinates": [9.0765, 7.3986] },
    "mode": "ROAD"
  }'

Error Responses

All endpoints return errors in this format:

typescript

{
  error: true
  status: 'ERROR_CODE'
  message: string
}

Common Error Codes:

UTILITY::VALIDATION_FAILED - Invalid request parameters
UTILITY::CALCULATION_FAILED - Calculation error
UTILITY::ESTIMATION_FAILED - Unable to estimate
UTILITY::INSUFFICIENT_DATA - Not enough data for calculation
AUTH::INVALID_API_KEY - Invalid or missing API key
AUTH::UNAUTHORIZED - No access to resource

Example Error:

json

{
  "error": true,
  "status": "UTILITY::VALIDATION_FAILED",
  "message": "Origin country is required"
}

Rate Limits

Free Tier: 100 requests/minute, 10,000 requests/month
Pro Tier: 1,000 requests/minute, 100,000 requests/month
Enterprise: Custom limits

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640000000

SDK Usage

For TypeScript/JavaScript applications, use the official SDK:

typescript

import { DeClient } from '@dedot/sdk'

const client = new DeClient({
  apiKey: 'your-api-key',
  workspace: 'your-workspace'
})

// All utilities available under client.realm.utilities
const deliveryFee = await client.realm.utilities.delivery.calculate({...})
const transportFare = await client.realm.utilities.transport.calculate({...})
const rideFare = await client.realm.utilities.ride.calculate({...})
const crossBorder = await client.realm.utilities.crossborder.calculate({...})
const distance = await client.realm.utilities.distance.calculate({...})
const zone = await client.realm.utilities.zone.assign({...})
const nearby = await client.realm.utilities.nearby.search({...})
const eta = await client.realm.utilities.eta.calculate({...})

View SDK Documentation →

Network Infrastructure

Order System

Operations

Utilities API Reference

Base URL

Authentication

Delivery Fees Calculator

POST /fares/delivery

Transport Fare Calculator

POST /fares/transport

Ride-Hailing Fare Calculator

POST /fares/ride

Cross-Border Fare Calculator

POST /fares/crossborder

Distance Calculator

POST /distance

Zone Assignment

POST /zone

Nearby Vehicle Search

POST /nearby/search

POST /nearby/bounds

POST /nearby/nearest

ETA Calculator

POST /eta

Error Responses

Rate Limits

SDK Usage

Utilities API Reference ​

Base URL ​

Authentication ​

Delivery Fees Calculator ​

POST /fares/delivery ​

Transport Fare Calculator ​

POST /fares/transport ​

Ride-Hailing Fare Calculator ​

POST /fares/ride ​

Cross-Border Fare Calculator ​

POST /fares/crossborder ​

Distance Calculator ​

POST /distance ​

Zone Assignment ​

POST /zone ​

Nearby Vehicle Search ​

POST /nearby/search ​

POST /nearby/bounds ​

POST /nearby/nearest ​

ETA Calculator ​

POST /eta ​

Error Responses ​

Rate Limits ​

SDK Usage ​

Utilities API Reference

Base URL

Authentication

Delivery Fees Calculator

POST /fares/delivery

Transport Fare Calculator

POST /fares/transport

Ride-Hailing Fare Calculator

POST /fares/ride

Cross-Border Fare Calculator

POST /fares/crossborder

Distance Calculator

POST /distance

Zone Assignment

POST /zone

Nearby Vehicle Search

POST /nearby/search

POST /nearby/bounds

POST /nearby/nearest

ETA Calculator

POST /eta

Error Responses

Rate Limits

SDK Usage