Lima Automotive Shipping API

Comprehensive car shipping and logistics API for international and domestic transport

API Overview

The Lima Automotive Shipping API provides comprehensive car shipping calculations for international and domestic transport. The API supports multiple regions, currencies, and shipping scenarios.

Base URL: https://your-api-domain.com
Content-Type: application/json
Response Format: JSON

Key Features

📖 Important Terminology

Understanding the terminology used in this API is critical for proper integration:

⚠️ "Dues" vs "Duty" vs "Customs Total"

The shipping industry uses overlapping terminology that can be confusing:

  • "Dues" (legacy field): In the API response, this means base customs duty amount
  • "Duty": The clearer term for base customs duty (use customsBreakdown.duty)
  • "Customs Total": The sum of ALL customs charges (duty + tariff + GST/MPF/HMF + brokerage + bond)

Customs Calculation Terms

Term Meaning Example
Duty (Base) Base import duty rate applied to cargo value 12.971% of $10,000 = $1,297.10
Tariff Additional country-pair tariff (ADDS to duty, not replaces) EU→US 12.5% of $10,000 = $1,250
CustomsTotal Total of all customs charges Duty + Tariff + GST/MPF/HMF + Brokerage + Bond
MPF Merchandise Processing Fee (USA only) 0.346% of cargo value
HMF Harbor Maintenance Fee (USA only) 0.125% of cargo value
GST Goods and Services Tax (Canada only, SEPARATE from duty) 5% of cargo value (independent)

Key Points

  • Tariffs are ADDITIVE: Duty + Tariff both apply to cargo value (e.g., 12.971% + 12.5% = 25.471% total)
  • Canada Special: Duty and GST are SEPARATE - both apply to full cargo value independently
  • USA Fees: Duty + Tariff + MPF + HMF all apply to cargo value, plus fixed fees (brokerage, bond)
  • Backward Compatible: API returns both legacy fields (Dues) and new clear naming (customsBreakdown.duty)

Example Calculation: France → USA ($10,000 EUR)

Cargo Value:  $11,600 USD (converted from EUR)

Base Duty (12.971%):     $1,504.80  ← Called "Dues" in legacy API
Tariff (12.5% EU→US):    $1,450.12  ← Additional, not replacement
MPF (0.346%):               $40.19
HMF (0.125%):               $14.50
                         ──────────
Percentage Fees:         $3,009.61

Brokerage (fixed):         $400.00
Bond (0.55%, min $250):    $250.00
                         ══════════
CustomsTotal:            $3,659.61  ← This is what "dues" means in shipping jargon

Recommended Approach

For New Integrations: Use the customsBreakdown object for clearer field names:
  • customsBreakdown.duty instead of Dues
  • customsBreakdown.total instead of CustomsTotal
  • customsBreakdown.percentageFeesSubtotal for sum of duty+tariff+GST/MPF/HMF
For Existing Integrations: Legacy fields still work - no changes required!

Authentication

The API has two types of endpoints:

Public Endpoints

Most API endpoints (shipping calculation, currency conversion, etc.) are publicly accessible and don't require authentication.

Admin Endpoints

Admin endpoints require JWT (JSON Web Token) authentication. To access admin endpoints:

  1. Login: POST to /admin/login with username and password
  2. Receive Token: Get JWT token from the response
  3. Include Token: Add to Authorization header: Bearer YOUR_JWT_TOKEN
// Example: Admin authentication
const response = await fetch('/admin/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        username: 'admin',
        password: 'your_password',
        remember: true
    })
});

const { token } = await response.json();

// Use token for admin endpoints
const customsData = await fetch('/admin/customs', {
    headers: {
        'Authorization': `Bearer ${token}`
    }
});
Token Expiration:
  • Default: 24 hours
  • With "remember": 7 days
  • Verify token: GET /admin/verify
Security Note:
  • Passwords are hashed using SHA256
  • Store tokens securely (localStorage/sessionStorage for web)
  • Tokens contain username and role information
  • Default root user is created automatically if no users exist

API Endpoints

Public Endpoints

POST /shipping

Calculate shipping fees for car transport between two locations.

POST /shipping

Request Parameters

Parameter Type Required Description
origin string/object Yes Origin address (string) or coordinates object with latitude/longitude
destination string/object Yes Destination address (string) or coordinates object with latitude/longitude
value number Yes Cargo value in input_currency
type string No Request type: "addressreq" (default) or "pointReq" for coordinates
inputCurrency string No Currency of input value (defaults to origin country currency)
currency string No Output currency (defaults to destination country currency)
insured string No Insurance type: "basic" (default), "comprehensive", or "no"
importType string No Import type for customs calculation
buyForMe boolean No Whether to include buy-for-me service (default: false)
insuredPrice number No Custom insured value (overrides cargo value for insurance)
year number No Car year (if provided, all three car details must be included)
make string No Car make (if provided, all three car details must be included)
model string No Car model (if provided, all three car details must be included)
Car Details Rule: If any of the car details (year, make, model) are provided, all three must be included.

Reverse Geocoding for Point Requests

Automatic Location Decoding: When using "type": "pointReq" with coordinate-based requests, the API automatically performs reverse geocoding to include human-readable location strings in the response.

Added Fields: Both Origin and Destination objects will include a location field containing the decoded address string.

Example: Coordinates (25.7616798, -80.1917902) will be decoded to "Miami, FL, USA"

Response Format

{
  "Origin": {
    "latitude": 25.7616798,
    "longitude": -80.1917902,
    "location": "Miami, FL, USA"
  },
  "OriginPort": null,
  "Destination": {
    "latitude": 40.7127753,
    "longitude": -74.0059728,
    "location": "New York, NY, USA"
  },
  "DestinationPort": null,
  "Freight": 1830,
  "CustomsTotal": 0,
  "Insurance": 230,
  "TotalCost": 3260,
  "CargoValue": 10000,
  "OceanTransport": 0,
  "LandTransport": 1830,
  "LandTransportOriginToPort": 0,
  "LandTransportPortToDestination": 0,
  "Brokerage": 0,
  "Dues": 0,
  "Bond": 0,
  "Currency": "USD",
  "ExchangeRate": 1.0,
  "InsuranceType": "basic",
  "importManagement": 1200,
  "buyForMe": false,
  "buyForMeFee": 0.025,
  "agencyFee": 0,
  "importType": null,
  "customsMode": "domestic",
  "insuranceBaseValue": 10000,
  "isDomestic": true,
  "inputCurrency": "USD",
  "originalValue": 10000,
  "carDetails": {
    "year": 2020,
    "make": "Porsche",
    "model": "911 Turbo S"
  },
  "callerInfo": {
    "host": "api.example.com",
    "userAgent": "Mozilla/5.0...",
    "remoteAddr": "192.168.1.1",
    "timestamp": "2024-01-01T12:00:00"
  },
  "Fees": {
    "transport": {
      "baseRate": 950,
      "ratePerKm": 0.5,
      "distance": 1760.0,
      "pickupRate": 0,
      "oceanRate": 0
    },
    "insurance": {
      "basicRate": 1.5,
      "comprehensiveRate": 1.75,
      "multiplier": 1.1,
      "type": "basic",
      "baseValue": 10000
    },
    "customs": {
      "brokerage": 0,
      "dues": 0,
      "bond": 0
    },
    "service": {
      "importManagement": 1200,
      "buyForMe": {
        "rate": 2.5,
        "applied": false
      }
    }
  },
  "ID": "875a157cc4d4b069"
}

GET /autocomplete

Get location suggestions for address autocomplete.

GET /autocomplete?q=query&limit=5

Query Parameters

Parameter Type Required Description
q string Yes Search query for location
limit number No Maximum number of suggestions (default: 5)

Response Example

{
  "suggestions": [
    {
      "label": "Miami, FL, USA",
      "address": "Miami, FL, USA",
      "country": "United States",
      "region": "Florida",
      "latitude": 25.7616798,
      "longitude": -80.1917902,
      "currency": "USD"
    }
  ]
}

POST /gps

Convert address to GPS coordinates.

POST /gps

Request Body

{
  "address": "Miami, FL, USA"
}

Response Example

{
  "latitude": 25.7616798,
  "longitude": -80.1917902,
  "cc": "USA",
  "currency": "USD"
}

GET /currencies

Get list of available currencies.

GET /currencies

Response Example

{
  "currencies": ["USD", "EUR", "GBP", "CAD", "AUD", "ZAR", "AED", "MXN"],
  "count": 8
}

POST /convert

Convert amount between currencies.

POST /convert

Request Body

{
  "amount": 1000,
  "from_currency": "USD",
  "to_currency": "EUR"
}

Response Example

{
  "amount": 1000,
  "from_currency": "USD",
  "to_currency": "EUR",
  "converted_amount": 859.0,
  "exchange_rate": 0.859
}

GET /rates

Get current exchange rates.

GET /rates

Response Example

{
  "base_currency": "USD",
  "rates": {
    "EUR": 0.859,
    "GBP": 0.789,
    "CAD": 1.35
  },
  "timestamp": 1640995200
}

POST /nearest-port

Find the nearest port to a given location.

POST /nearest-port

Request Body

{
  "location": {
    "latitude": 25.7616798,
    "longitude": -80.1917902
  },
  "type": "pointReq"
}

Response Example

{
  "location": {
    "address": "Miami, FL, USA",
    "coordinates": {
      "latitude": 25.7616798,
      "longitude": -80.1917902
    },
    "country_code": "USA",
    "currency": "USD"
  },
  "nearest_port": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Port of Miami",
    "address": "Port of Miami, Miami, FL, USA",
    "region": "USA",
    "coordinates": {
      "latitude": 25.7616798,
      "longitude": -80.1917902
    }
  },
  "distance": {
    "kilometers": 0.5,
    "miles": 0.31
  },
  "port_region": "USA"
}

GET /health

Health check endpoint with cache status.

GET /health

Response Example

{
  "status": "healthy",
  "ports_refresh_strategy": "time_based",
  "refresh_interval_seconds": 300,
  "ports_loaded": true,
  "ports_count": 150,
  "regions": ["USA", "Canada", "UK", "Europe", "Ireland", "South Africa", "Australia", "UAE", "Mexico"],
  "cache_age_seconds": 45.2,
  "cache_fresh": true
}

POST /customs-rates

Get all customs rates and fees between two locations (percentages and base numbers only, no cargo value required).

POST /customs-rates

Request Parameters

Parameter Type Required Description
origin string/object Yes Origin address (string) or coordinates object
destination string/object Yes Destination address (string) or coordinates object
type string No Request type: "addressreq" (default) or "pointReq"

Response Example - International

{
  "origin": {
    "country": "USA",
    "region": "USA"
  },
  "destination": {
    "country": "CAN",
    "region": "Canada"
  },
  "isDomestic": false,
  "fees": {
    "transport": {
      "pickupBase": 205,
      "pickupRatePerKm": 0.9,
      "oceanFee": 2900,
      "deliveryBase": 577,
      "deliveryRatePerKm": 0.31
    },
    "customs": {
      "brokerage": 390,
      "duesRate": 0.05,        // 5% - In Canada, this is GST
      "gstRate": 0.05,          // 5% - Same as dues for Canada
      "bondRate": 0,
      "bondMin": 0,
      "bondMax": 0,
      "mpfRate": null,
      "hmfRate": null,
      "tariffApplied": false,
      "tariffType": null,
      "tariffRate": null
    },
    "service": {
      "importManagement": 1200,
      "buyForMeRate": 0.025    // 2.5%
    },
    "insurance": {
      "basicRate": 0.015,       // 1.5%
      "comprehensiveRate": 0.0175, // 1.75%
      "multiplier": 1.1
    }
  }
}

Response Example - With Custom Tariff

{
  "origin": {
    "country": "GER",
    "region": "Europe"
  },
  "destination": {
    "country": "USA",
    "region": "USA"
  },
  "fees": {
    "customs": {
      "brokerage": 400,
      "duesRate": 0.12,         // 12% - Custom tariff rate
      "standardDuesRate": 0.029714, // Original rate before tariff
      "tariffApplied": true,
      "tariffType": "country",  // Country-specific tariff
      "tariffRate": 0.12,       // 12%
      "bondRate": 0.0055,
      "bondMin": 250,
      "bondMax": 950,
      "mpfRate": 0.003464,
      "hmfRate": 0.00125
    }
  }
}
Note: This endpoint returns only rates and percentages, not calculated amounts. Use this to understand fee structures between any two locations without needing cargo values.

Admin Endpoints

Authentication Required: All admin endpoints require JWT authentication. Include the token in the Authorization header: Bearer YOUR_JWT_TOKEN

POST /admin/login

Authenticate admin user and receive JWT token.

POST /admin/login

Request Body

{
  "username": "admin",
  "password": "your_password",
  "remember": true  // Optional, extends token expiration
}

Response Example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin",
  "role": "admin",
  "expiresIn": "7d"  // or "24h" if remember is false
}
Password Hashing: Passwords are hashed using SHA256. The system automatically creates a root user if none exist.

GET /admin/verify

Verify admin token validity.

GET /admin/verify

Headers Required

Authorization: Bearer YOUR_JWT_TOKEN

Response Example

{
  "valid": true,
  "username": "admin",
  "role": "admin"
}

GET /admin/customs

Get all customs fees configuration and tariffs.

GET /admin/customs

Response Example

{
  "pickupFee": 205,
  "importManagement": 1200,
  "buyForMeFee": 0.025,
  "basicInsurance": 0.015,
  "comprehensiveInsurance": 0.0175,
  // USA fees
  "usaBrokerage": 400,
  "usaDues": 0.029714,
  "usaMPF": 0.003464,
  "usaHMF": 0.00125,
  "usaBondMin": 250,
  "usaBondMax": 950,
  "usaBondX": 0.0055,
  "usaDeliveryBase": 284,
  "usaDeliveryX": 0.637,
  // Canada fees (GST serves as dues)
  "canadaBrokerage": 390,
  "canadaGST": 0.05,  // Also serves as dues
  "canadaDeliveryBase": 577,
  "canadaDeliveryX": 0.31,
  // Other regions...
  "customsPairs": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "originCountry": "GER",
      "destinationCountry": "USA",
      "type": "country",
      "dutyRate": 0.12,
      "active": true
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "originRegion": "Europe",
      "destinationRegion": "USA",
      "type": "region",
      "dutyRate": 0.08,
      "active": true
    }
  ]
}

POST /admin/customs

Update customs fees configuration and tariffs.

POST /admin/customs

Request Body

{
  "pickupFee": 205,
  "importManagement": 1200,
  // ... all fee configurations
  "customsPairs": [
    {
      "type": "country",        // or "region"
      "originCountry": "GER",   // For country type
      "destinationCountry": "USA",
      "dutyRate": 0.12          // Replaces standard dues
    },
    {
      "type": "region",
      "originRegion": "Europe",  // For region type
      "destinationRegion": "USA",
      "dutyRate": 0.08
    }
  ]
}

Response Example

{
  "success": true,
  "message": "Customs fees updated successfully"
}
Tariff Priority: Country-specific tariffs take precedence over region-block tariffs. Tariffs are ADDITIVE - they add to the base duty rate, not replace it.

GET /admin/tariffs

Get all tariffs (active and inactive).

GET /admin/tariffs

Response Example

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "type": "country",
    "originCountry": "GER",
    "destinationCountry": "USA",
    "dutyRate": 0.12,
    "active": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  {
    "_id": "507f1f77bcf86cd799439012",
    "type": "region",
    "originRegion": "Europe",
    "destinationRegion": "USA",
    "dutyRate": 0.08,
    "active": false,  // Inactive tariff
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-02T00:00:00Z"
  }
]

DELETE /admin/tariffs/{origin}/{destination}

Deactivate a specific tariff.

DELETE /admin/tariffs/Europe/USA

Response Example

{
  "success": true,
  "message": "Tariff deactivated successfully"
}

GET /admin/audit

Get audit log of admin actions.

GET /admin/audit?limit=50

Query Parameters

Parameter Type Required Description
limit number No Number of entries to return (default: 100)

Response Example

[
  {
    "timestamp": "2024-01-01T12:00:00Z",
    "user": "admin",
    "action": "update_customs",
    "details": {
      "changes": {
        "usaBrokerage": {
          "old": 400,
          "new": 425
        }
      }
    },
    "ip": "192.168.1.1"
  }
]

POST /admin/create-user

Create a new admin user (requires existing admin authentication).

POST /admin/create-user

Request Body

{
  "username": "newadmin",
  "password": "secure_password",
  "role": "admin"  // Optional, defaults to "admin"
}

Response Example

{
  "success": true,
  "username": "newadmin",
  "message": "Admin user created successfully"
}

GET /admin

Admin panel web interface (requires authentication).

GET /admin
Note: This returns the HTML admin panel interface. Access via web browser with valid JWT token stored in localStorage.

GET /admin/login

Admin login page (HTML interface).

GET /admin/login
Note: This returns the HTML login page. Access via web browser to authenticate and receive JWT token.

Supported Regions

The API supports the following regions with specific rates and configurations:

USA

  • Currency: USD
  • Domestic Rate: $950 + $0.5/km
  • Ocean Fee: $800
  • Brokerage: $275
  • Dues: 2.5% of cargo value

Canada

  • Currency: CAD
  • Domestic Rate: $950 + $0.5/km
  • Ocean Fee: $800
  • Brokerage: $275
  • Dues: 2.5% of cargo value

UK

  • Currency: GBP
  • Domestic Rate: €950 + €0.5/km
  • Ocean Fee: €800
  • Brokerage: €275
  • Dues: 5% of cargo value (EUR)

Europe

  • Currency: EUR
  • Domestic Rate: €950 + €0.5/km
  • Ocean Fee: €800
  • Brokerage: €275
  • Dues: 5% of cargo value

Ireland

  • Currency: EUR
  • Domestic Rate: €950 + €0.5/km
  • Ocean Fee: €800
  • Brokerage: €275
  • Dues: 5% of cargo value

South Africa

  • Currency: ZAR
  • Domestic Rate: R950 + R4/km
  • Ocean Fee: $4200
  • Brokerage: $275
  • Dues: 5% of cargo value

Australia

  • Currency: AUD
  • Domestic Rate: A$950 + A$3/km
  • Ocean Fee: $4600
  • Brokerage: $275
  • Dues: 5% of cargo value

UAE

  • Currency: AED
  • Domestic Rate: AED950 + AED3/km
  • Ocean Fee: $4600
  • Brokerage: $275
  • Dues: 5% of cargo value

Mexico

  • Currency: MXN
  • Domestic Rate: MXN950 + MXN0.5/km
  • Ocean Fee: $4200
  • Brokerage: $0 (import only)
  • Dues: 0% (import only)

Domestic vs International Logic

  • Domestic: Same region shipments (USA→USA, Europe→Europe, etc.)
  • USA↔Canada: Treated as domestic (neighboring countries)
  • International: Different region shipments (UAE→Europe, Australia→USA, etc.)

Customs Tariffs System

The API supports a flexible customs tariff system that allows for specific duty rates between country pairs or region blocks.

Tariff Types

Country-Specific Tariffs

Define custom duty rates between specific countries (e.g., Germany → USA: 12%)

  • Highest priority in calculation
  • Uses 3-letter country codes
  • Overrides region-block tariffs

Region-Block Tariffs

Define duty rates between regions (e.g., Europe → USA: 8%)

  • Applied when no country-specific tariff exists
  • Uses region names (Europe, USA, Canada, etc.)
  • Fallback for country-specific rates

Tariff Priority System

// Tariff application priority
1. Country-Specific Tariff (if exists)
   Example: GER → USA = 12%
   
2. Region-Block Tariff (if exists)
   Example: Europe → USA = 8%
   
3. Standard Region Dues (default)
   Example: USA standard = 2.971%

How Tariffs Work

Important: Tariffs ADD TO the base duty rate, they don't replace it.

Example: If USA standard duty is 12.971% and a tariff of 12.5% applies (EU→USA), the total customs duty will be 25.471% (12.971% + 12.5%).

Canada Duty and GST

In Canada, Duty and GST are SEPARATE

  • Base Duty Rate: Variable by origin country (e.g., 5% default, 6.1% from UAE)
  • GST Rate: 5% (always separate from duty)
  • Both apply independently: Both duty and GST are calculated from the full cargo value
  • Custom tariffs: Add to the base duty rate (e.g., 6.1% tariff + 5% base duty = 11.1% total duty)
  • API Response: Dues field shows duty only, GST field is separate

Tariff Management

Admin users can manage tariffs through the admin panel:

Example Tariff Scenarios

Scenario 1: Germany to USA (Country-Specific)

Origin: Germany (GER)
Destination: USA
Country Tariff: 12%
Region Tariff: 8% (Europe → USA)
Base Duty: 12.971%

Applied Rates: 
- Base Duty: 12.971%
- Country Tariff: 12% (country-specific wins over region)
- Total Duty Rate: 24.971% (12.971% + 12%)
- Plus MPF (0.346%) and HMF (0.125%)

Scenario 2: France to USA (Region-Block)

Origin: France (FRA)
Destination: USA
Country Tariff: None
Region Tariff: 12.5% (Europe → USA)
Base Duty: 12.971%

Applied Rates:
- Base Duty: 12.971%
- Region Tariff: 12.5%
- Total Duty Rate: 25.471% (12.971% + 12.5%)
- Plus MPF (0.346%) and HMF (0.125%)

Scenario 3: UAE to Canada (With Regional Tariff)

Origin: UAE
Destination: Canada
Country Tariff: None
Region Tariff: 6.1% (UAE → Canada)
Base Duty: 5%
GST: 5%

Applied Rates:
- Base Duty: 5%
- Region Tariff: 6.1%
- Total Duty: 11.1% (5% + 6.1%)
- GST: 5% (separate, calculated independently)
- Total Percentage Fees: 16.1% (11.1% duty + 5% GST)

API Response with Tariffs

// When a tariff is applied
{
  "Fees": {
    "customs": {
      "brokerage": 400,
      "dues": 1200,           // 12% of $10,000
      "tariffApplied": true,
      "tariffType": "country", // or "region"
      "tariffRate": 12,        // Percentage
      "standardDues": 297.10   // What it would have been without tariff
    }
  }
}

Fee Calculation Logic

Currency Calculation Flow

Important: All internal calculations are performed in USD, then converted to the output currency.

Flow: Input Currency → USD → Calculate → Output Currency

// Currency calculation flow
input_value_in_currency → convert_to_usd → calculate_costs_in_usd → convert_to_output_currency

// Example: EUR 10000 → USD 10859 → Calculate → USD 6240 → EUR 5750

CargoValue Preservation

Fixed Issue: CargoValue now correctly preserves the original input value in the input currency.

Previous Behavior: CargoValue was incorrectly converted to origin country currency.

Current Behavior: CargoValue maintains the original input value and currency.

Domestic Shipments (Same Region)

// Domestic calculation example (USA → USA)
direct_distance = calculateDistance(origin, destination)
transport = 950 + (0.5 × direct_distance)
freight = transport
ocean_fee = 0
customs_total = 0
import_management = 1200  // Lima Automotive service fee
total_cost = freight + insurance + import_management + agency_fee

International Shipments (Different Regions)

// International calculation example (UAE → Europe)
pickups = origin_to_port_distance
ocean_fee = max(origin_ocean_fee, destination_ocean_fee)
freight = pickups + ocean_fee
customs_total = brokerage + dues + bond
import_management = 1200  // Lima Automotive service fee
total_cost = freight + insurance + customs_total + import_management + agency_fee

Ocean Fee Logic

Formula: ocean_fee = max(origin_ocean_fee, destination_ocean_fee)

The higher ocean fee between origin and destination regions is used.

When Ocean Transport is 0

Ocean transport fees are set to 0 for the following scenarios:

  • Domestic Shipments: Same region (USA→USA, Europe→Europe, etc.)
  • USA-Canada: Cross-border shipments between USA and Canada
  • Europe-Europe: Shipments within Europe (excluding Ireland)
  • UK-Europe: Shipments between UK and Europe (excluding Ireland)

Reason: These routes don't require ocean transport and use land-based logistics.

Insurance Calculation

// Insurance calculation with TWO different modes:

// MODE 1: When custom insured_price is provided by user
if insured == 'comprehensive':
    insurance = comprehensive_rate × insured_price  // No 1.1x, no freight
else:  // basic
    insurance = basic_rate × insured_price  // No 1.1x, no freight

// MODE 2: Default calculation (no custom insured_price)
if insurance_base_value == 0 or insured == 'no':
    insurance = 0
elif insured == 'comprehensive':
    insurance = comprehensive_rate × 1.1 × (cargo_value + freight)
else:  // basic
    insurance = basic_rate × 1.1 × (cargo_value + freight)

Insurance Rules

No Insurance: When insured = "no"

Zero Value: When cargo value or insured price is 0

Custom Insured Value (insured_price parameter):

  • Basic: 1.5% × insured_price (no multiplier, no freight)
  • Comprehensive: 1.75% × insured_price (no multiplier, no freight)
  • insuranceBaseValue in response = insured_price

Default Calculation (no custom insured_price):

  • Basic: 1.5% × 1.1 × (cargo_value + freight)
  • Comprehensive: 1.75% × 1.1 × (cargo_value + freight)
  • Risk Multiplier: 1.1 applied to default calculations
  • insuranceBaseValue in response = cargo_value + freight

Rounding Logic

All monetary values are rounded to 2 decimal places like regular currency

Example: $1234.56789 becomes $1234.57

API Examples

Example 1: Domestic USA Shipment

Request

POST /shipping
{
  "origin": {
    "latitude": 25.7616798,
    "longitude": -80.1917902
  },
  "destination": {
    "latitude": 40.7127753,
    "longitude": -74.0059728
  },
  "value": 10000,
  "type": "pointReq",
  "insured": "basic"
}

Response

{
  "Freight": 1830,
  "CustomsTotal": 0,
  "Insurance": 230,
  "TotalCost": 3260,
  "OceanTransport": 0,
  "LandTransport": 1830,
  "importManagement": 1200,
  "isDomestic": true,
  "Currency": "USD"
}

Example 2: International UAE to Europe

Request

POST /shipping
{
  "origin": {
    "latitude": 25.2048493,
    "longitude": 55.2707828
  },
  "destination": {
    "latitude": 48.8575475,
    "longitude": 2.3513765
  },
  "value": 10000,
  "type": "pointReq",
  "insured": "comprehensive",
  "currency": "EUR"
}

Response

{
  "Freight": 4645,
  "CustomsTotal": 344,
  "Insurance": 69,
  "TotalCost": 6258,
  "OceanTransport": 4600,
  "LandTransport": 245,
  "importManagement": 1200,
  "isDomestic": false,
  "Currency": "EUR"
}

Example 3: Address-based Request

Request

POST /shipping
{
  "origin": "Miami, FL, USA",
  "destination": "New York, NY, USA",
  "value": 15000,
  "insured": "basic",
  "buyForMe": true
}

Response

{
  "Freight": 1830,
  "CustomsTotal": 0,
  "Insurance": 345,
  "TotalCost": 4675,
  "OceanTransport": 0,
  "LandTransport": 1830,
  "importManagement": 1200,
  "agencyFee": 375,
  "buyForMe": true,
  "isDomestic": true,
  "Currency": "USD"
}

Error Handling

Common Error Responses

Error Type Status Code Description Example
Invalid JSON 400 Request body is not valid JSON {"error": "No JSON received"}
Missing Parameters 400 Required parameters are missing {"error": "Missing required parameter: value"}
Geocoding Failed 400 Could not find coordinates for address {"error": "Could not find coordinates for origin address: Invalid Address"}
Currency Conversion Failed 400 Failed to convert between currencies {"error": "Failed to convert 1000 USD to INVALID"}
Server Error 500 Internal server error {"error": "Internal server error", "ID": "abc123"}

Error Response Format

{
  "error": "Error description",
  "ID": "request_id_for_tracking"
}

Important Notes

  • All API calls are logged with request ID for debugging
  • Geocoding failures may occur for invalid or ambiguous addresses
  • Currency conversion depends on external exchange rate API availability
  • Port data is cached and refreshed every 5 minutes

Analytics & Caller Tracking

The API includes comprehensive analytics tracking to monitor usage, performance, and caller behavior.

Caller Information Tracking

The API automatically captures caller information from HTTP headers for analytics purposes:

{
  "callerInfo": {
    "host": "api.example.com",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    "remoteAddr": "192.168.1.1",
    "xForwardedFor": "203.0.113.1",
    "xRealIp": "203.0.113.1",
    "cfConnectingIp": "203.0.113.1",
    "timestamp": "2024-01-01T12:00:00"
  }
}

IP Address Detection Strategy

IP Detection Priority:

  1. CF-Connecting-IP - Cloudflare real IP
  2. X-Real-IP - Nginx real IP
  3. X-Forwarded-For - Proxy forwarded IP
  4. remote_addr - Direct connection IP

This strategy ensures accurate IP detection even when the API is hosted behind proxies or load balancers.

Request Analytics Data

Each API call is logged with comprehensive analytics data:

{
  "ID": "875a157cc4d4b069",
  "timestamp": "2024-01-01T12:00:00",
  "method": "POST",
  "path": "/shipping",
  "status": 200,
  "response_time_ms": 150,
  "input_currency": "USD",
  "output_currency": "EUR",
  "insured": "basic",
  "buyForMe": false,
  "carDetails": {
    "year": 2020,
    "make": "Porsche",
    "model": "911 Turbo S"
  },
  "origin": {
    "latitude": 25.7616798,
    "longitude": -80.1917902
  },
  "destination": {
    "latitude": 40.7127753,
    "longitude": -74.0059728
  },
  "value": 10000,
  "type": "pointReq",
  "customsMode": "domestic",
  "isDomestic": true
}

Analytics Use Cases

Data Privacy

Privacy Note: Caller information is collected for analytics purposes only. No personal data is stored or shared.

Data Retention: Analytics data is retained for operational and performance monitoring purposes.

Domestic Shipments

Domestic shipments occur when both origin and destination are within the same region (e.g., USA to USA, Europe to Europe). These shipments have simplified calculations and different cost structures compared to international shipments.

Domestic Shipment Identification

Automatic Detection: The API automatically detects domestic shipments based on region matching.

Response Field: isDomestic: true indicates a domestic shipment.

Domestic vs International Differences

Aspect Domestic International
Ocean Transport 0 (no ocean crossing) Calculated based on region
Ports None (direct transport) Origin and destination ports
Customs 0 (no customs fees) Brokerage + Dues + Bond
Land Transport Direct origin to destination Origin to port + port to destination
Import Management 1200 (service fee) 1200 (service fee)

Domestic Calculation Formula

// Domestic shipment calculation
direct_distance = calculateDistance(origin, destination)
transport = base_rate + (rate_per_km × direct_distance)
freight = transport
ocean_fee = 0
customs_total = 0
import_management = 1200  // Lima Automotive service fee
insurance = insurance_rate × (cargo_value + freight + import_management)
agency_fee = buy_for_me ? (cargo_value × 0.025) : 0
total_cost = freight + insurance + import_management + agency_fee

Region-Specific Domestic Rates

USA Domestic

  • Base Rate: $950
  • Per KM Rate: $0.5
  • Formula: 950 + (0.5 × distance_km)
  • Example: 1000 km = $950 + $500 = $1450

Canada Domestic

  • Base Rate: $950
  • Per KM Rate: $0.5
  • Formula: 950 + (0.5 × distance_km)
  • Example: 800 km = $950 + $400 = $1350

UK Domestic

  • Base Rate: €950
  • Per KM Rate: €0.5
  • Formula: 950 + (0.5 × distance_km)
  • Example: 600 km = €950 + €300 = €1250

Europe Domestic

  • Base Rate: €950
  • Per KM Rate: €0.5
  • Formula: 950 + (0.5 × distance_km)
  • Example: 750 km = €950 + €375 = €1325

Example: USA Domestic Shipment

Request

POST /shipping
{
  "origin": "Miami",
  "destination": "New York",
  "value": 10000,
  "insuredPrice": 15000,
  "year": 2020,
  "make": "Porsche",
  "model": "911 Turbo S",
  "buyForMe": true,
  "inputCurrency": "USD",
  "currency": "USD"
}

Response

{
  "Origin": {
    "latitude": 25.7616798,
    "longitude": -80.1917902,
    "location": "Miami, FL, USA"
  },
  "OriginPort": null,
  "Destination": {
    "latitude": 40.7127753,
    "longitude": -74.0059728,
    "location": "New York, NY, USA"
  },
  "DestinationPort": null,
  "Freight": 1830,
  "CustomsTotal": 0,
  "Insurance": 280,
  "TotalCost": 3560,
  "CargoValue": 10000,
  "OceanTransport": 0,
  "LandTransport": 1830,
  "LandTransportOriginToPort": 0,
  "LandTransportPortToDestination": 0,
  "Brokerage": 0,
  "Dues": 0,
  "Bond": 0,
  "Currency": "USD",
  "ExchangeRate": 1.0,
  "InsuranceType": "basic",
  "importManagement": 1200,
  "buyForMe": true,
  "buyForMeFee": 0.025,
  "agencyFee": 250,
  "importType": null,
  "customsMode": "domestic",
  "insuranceBaseValue": 15000,
  "isDomestic": true,
  "inputCurrency": "USD",
  "originalValue": 10000,
  "carDetails": {
    "year": 2020,
    "make": "Porsche",
    "model": "911 Turbo S"
  },
  "callerInfo": {
    "host": "localhost:8080",
    "userAgent": "PostmanRuntime/7.29.4",
    "remoteAddr": "127.0.0.1",
    "timestamp": "2025-08-20T17:15:50.000034"
  },
  "ID": "394bd8c3a2412758"
}

Cost Breakdown Analysis

Distance Calculation: Miami to New York ≈ 1760 km

Transport Cost: $950 + (0.5 × 1760) = $950 + $880 = $1830

Insurance: 1.5% × (15000 + 1830 + 1200) = 1.5% × 18030 = $270.45 → $280 (rounded up)

Buy-for-Me Fee: 2.5% × 10000 = $250

Total: $1830 + $280 + $1200 + $250 = $3560

Domestic Shipment Response Fields

Field Value Description
isDomestic true Indicates this is a domestic shipment
customsMode "domestic" Customs calculation mode
OceanTransport 0 No ocean transport for domestic shipments
OriginPort null No ports involved in domestic shipments
DestinationPort null No ports involved in domestic shipments
CustomsTotal 0 No customs fees for domestic shipments
Brokerage 0 No customs brokerage for domestic
Dues 0 No customs duties for domestic
Bond 0 No customs bond for domestic
LandTransport 1830 Direct transport cost (origin to destination)
LandTransportOriginToPort 0 No port involved
LandTransportPortToDestination 0 No port involved

Domestic Shipment Benefits

Common Domestic Routes

USA Routes

  • Miami → New York
  • Los Angeles → San Francisco
  • Chicago → Detroit
  • Houston → Dallas
  • Seattle → Portland

Canada Routes

  • Toronto → Montreal
  • Vancouver → Calgary
  • Ottawa → Toronto
  • Edmonton → Calgary
  • Winnipeg → Regina

Europe Routes

  • Paris → Lyon
  • Berlin → Munich
  • Rome → Milan
  • Madrid → Barcelona
  • Amsterdam → Brussels

UK Routes

  • London → Manchester
  • Birmingham → Liverpool
  • Edinburgh → Glasgow
  • Cardiff → Bristol
  • Leeds → Sheffield

Distance Calculation

Formula: Uses Haversine formula for accurate great-circle distance calculation

Units: Distances are calculated in kilometers

Accuracy: Provides precise distance for cost calculations

// Distance calculation example (Miami to New York)
miami_coords = {lat: 25.7616798, lng: -80.1917902}
ny_coords = {lat: 40.7127753, lng: -74.0059728}
distance_km = haversine_distance(miami_coords, ny_coords) ≈ 1760 km

// Transport cost calculation
transport_cost = 950 + (0.5 × 1760) = 950 + 880 = 1830 USD

Fees Breakdown & Calculation Details

The API response includes a comprehensive Fees object that provides all the percentages, rates, and values used in calculating the shipment cost. This transparency allows developers to understand exactly how costs are calculated and verify calculations.

Fees Object Structure

{
  "Fees": {
    "transport": { ... },      // Transport-related fees
    "insurance": { ... },      // Insurance calculation details
    "customs": { ... },        // Customs fees actually applied
    "service": { ... }         // Service fees
  }
}

Note: The Fees object only includes the fees that were actually used in the calculation, with standardized names that work universally across all regions and shipment types.

Transport Fees

{
  "transport": {
    "baseRate": 950,        // Base rate for domestic shipments
    "ratePerKm": 0.5,      // Rate per kilometer for domestic
    "distance": 1760.0,    // Calculated distance in kilometers
    "pickupRate": 205,     // Pickup fee for international (0 for domestic)
    "oceanRate": 4600      // Ocean transport rate (0 for domestic)
  }
}

Transport Calculation Examples

Domestic USA: $950 + ($0.5 × distance_km)

Example: 1760 km = $950 + ($0.5 × 1760) = $950 + $880 = $1830

International: pickup_rate + ocean_rate + delivery_fees

Insurance Fees

{
  "insurance": {
    "basicRate": 1.5,           // Basic insurance rate (1.5%)
    "comprehensiveRate": 1.75,  // Comprehensive insurance rate (1.75%)
    "multiplier": 1.1,          // Risk multiplier (only for default calculations)
    "type": "basic",            // Insurance type used in calculation
    "baseValue": 11830          // Base value: insured_price (if provided) OR (cargo_value + freight)
  }
}

Insurance Calculation Formula

Default Mode (no custom insured_price):

// Basic Insurance (Default)
insurance = basic_rate × multiplier × (cargo_value + freight)
insurance = 1.5% × 1.1 × (10000 + 1830) = 1.5% × 1.1 × 11830 = $195.20

// Comprehensive Insurance (Default)
insurance = comprehensive_rate × multiplier × (cargo_value + freight)
insurance = 1.75% × 1.1 × (10000 + 1830) = 1.75% × 1.1 × 11830 = $227.73

Custom Insured Value Mode (when insured_price is provided):

// Basic Insurance (Custom)
insurance = basic_rate × insured_price  // No 1.1x multiplier, no freight
insurance = 1.5% × 15000 = $225.00

// Comprehensive Insurance (Custom)
insurance = comprehensive_rate × insured_price  // No 1.1x multiplier, no freight
insurance = 1.75% × 15000 = $262.50

Customs Fees

{
  "customs": {
    "brokerage": 400,        // Customs brokerage fee actually applied
    "dues": 297.10,          // Customs duties actually applied
    "bond": 250              // Customs bond fee actually applied
  }
}

Customs Calculation Examples

USA Customs:

  • Brokerage: $400 (fixed)
  • Dues: 2.971% × cargo_value
  • Bond: min($250, max($950, 0.55% × cargo_value))

Example for $10,000 cargo:

  • Brokerage: $400
  • Dues: 2.971% × $10,000 = $297.10
  • Bond: min($250, max($950, 0.55% × $10,000)) = min($250, max($950, $55)) = $250
  • Total Customs: $400 + $297.10 + $250 = $947.10

Note: For domestic shipments, all customs fees will be 0.

Service Fees

{
  "service": {
    "importManagement": 1200,  // Lima Automotive service fee
    "buyForMe": {
      "rate": 2.5,             // Buy-for-me fee rate (2.5%)
      "applied": true          // Whether buy-for-me service is included
    }
  }
}

Service Fee Calculations

Import Management: Fixed $1,200 fee for all shipments

Buy-for-Me: 2.5% of cargo value when service is requested

Example: $10,000 cargo with buy-for-me = $10,000 × 2.5% = $250

Ocean Transport Fees

{
  "ocean": {
    "usa": 2900,        // USA ocean transport fee
    "canada": 2900,     // Canada ocean transport fee
    "uk": 2900,         // UK ocean transport fee
    "europe": 2900,     // Europe ocean transport fee
    "southAfrica": 4200, // South Africa ocean transport fee
    "australia": 4600,  // Australia ocean transport fee
    "uae": 4600,        // UAE ocean transport fee
    "mexico": 4200      // Mexico ocean transport fee
  }
}

Ocean Fee Selection Logic

Formula: ocean_fee = max(origin_ocean_fee, destination_ocean_fee)

Example: UAE (4600) to Europe (2900) = max(4600, 2900) = 4600

Reasoning: Higher fee covers the more expensive leg of the journey

Delivery Fees

{
  "delivery": {
    "usa": {
      "base": 284,      // Base delivery fee for USA
      "rate": 63.7      // Delivery rate per km (63.7%)
    },
    "canada": {
      "base": 577,      // Base delivery fee for Canada
      "rate": 31.0      // Delivery rate per km (31.0%)
    }
  }
}

Delivery Fee Calculation

// USA Delivery
delivery_fee = base + (rate × distance_km)
delivery_fee = 284 + (63.7% × distance_km)

// Canada Delivery
delivery_fee = base + (rate × distance_km)
delivery_fee = 577 + (31.0% × distance_km)

Complete Cost Calculation Example

Domestic USA Shipment: Miami to New York

// Input
cargo_value = 10000
distance = 1760 km
insured_price = 15000
buy_for_me = true

// Transport Cost
transport = 950 + (0.5 × 1760) = 950 + 880 = 1830

// Insurance (Basic)
insurance_base = 15000 + 1830 + 1200 = 18030
insurance = 1.5% × 1.1 × 18030 = 0.015 × 1.1 × 18030 = 297.50 → 300 (rounded up)

// Buy-for-Me Fee
agency_fee = 2.5% × 10000 = 250

// Total Cost
total = transport + insurance + import_management + agency_fee
total = 1830 + 300 + 1200 + 250 = 3580

// Final Response
{
  "Freight": 1830,
  "Insurance": 300,
  "importManagement": 1200,
  "agencyFee": 250,
  "TotalCost": 3580,
  "Fees": {
    "transport": {
      "baseRate": 950,
      "ratePerKm": 0.5,
      "distance": 1760.0
    },
    "insurance": {
      "basicRate": 1.5,
      "multiplier": 1.1,
      "baseValue": 15000
    },
    "service": {
      "importManagement": 1200,
      "buyForMe": {
        "rate": 2.5,
        "applied": true
      }
    }
  }
}

Fees Object Benefits

Regional Fee Variations

Note: Fees vary by region and are stored in the customs database. The API automatically selects the appropriate rates based on origin and destination regions.

Updates: Fee rates can be updated in the database without requiring API code changes.

Response Field Reference

Field Type Description
Origin object Origin coordinates with latitude/longitude and location string (for pointReq)
Destination object Destination coordinates with latitude/longitude and location string (for pointReq)
OriginPort object/null Nearest port to origin (null for domestic)
DestinationPort object/null Nearest port to destination (null for domestic)
Freight number Total freight cost (transport for domestic, pickups+ocean for international)
CustomsTotal number Total customs charges (brokerage + duty + tariff + GST/MPF/HMF + bond)
Insurance number Insurance premium amount
TotalCost number Total shipping cost (freight + insurance + customs + service fees)
CargoValue number Cargo value in origin country currency
OceanTransport number Ocean transport fee (0 for domestic)
LandTransport number Total land transport cost
LandTransportOriginToPort number Origin to port transport cost (0 for domestic)
LandTransportPortToDestination number Port to destination transport cost (0 for domestic)
Brokerage number Customs brokerage fee
Dues number Base customs duty amount (legacy field - use customsBreakdown.duty for clarity)
Tariff number Additional tariff amount (country/region-specific, adds to duty)
MPF number Merchandise Processing Fee (USA only, 0 for others)
HMF number Harbor Maintenance Fee (USA only, 0 for others)
GST number Goods and Services Tax (Canada only, 0 for others - separate from duty)
Bond number Customs bond fee
Currency string Output currency code
ExchangeRate number USD to output currency exchange rate
InsuranceType string Insurance type used ("basic", "comprehensive", "no")
importManagement number Lima Automotive service fee
buyForMe boolean Whether buy-for-me service is included
buyForMeFee number Buy-for-me fee rate (2.5%)
agencyFee number Agency fee amount
importType string/null Import type for customs calculation
customsMode string Customs calculation mode ("domestic", "default", "customs_waived")
insuranceBaseValue number Base value used for insurance calculation. When custom insured_price is provided, this equals the insured_price. When using default calculation, this equals (cargo_value + freight)
isDomestic boolean Whether shipment is domestic (same region)
ID string Unique request ID for tracking
callerInfo object Information about the caller (host, user agent, remote address, timestamp)
carDetails object/null Car details (year, make, model) if provided in the request
inputCurrency string Currency of the input value
originalValue number Original cargo value in input currency
Rates object NEW: Percentage rates breakdown (shows rates even when cargo value is 0)
  └─ dutyRate number Base duty rate percentage (e.g., 12.971 for 12.971%)
  └─ tariffRate number Additional tariff rate percentage (e.g., 12.5 for 12.5%)
  └─ gstRate number GST rate for Canada (e.g., 5.0 for 5%)
  └─ mpfRate number MPF rate for USA (e.g., 0.346 for 0.346%)
  └─ hmfRate number HMF rate for USA (e.g., 0.125 for 0.125%)
  └─ bondRate number Bond rate for USA (e.g., 0.55 for 0.55%)
  └─ insuranceRate number Insurance rate based on type (e.g., 1.5 for 1.5%)
customsBreakdown object NEW: Clear breakdown of customs charges with intuitive naming (recommended for new integrations)
  └─ duty number Base duty amount (same as Dues field, clearer naming)
  └─ tariff number Additional tariff amount (country/region-specific)
  └─ gst number GST amount (Canada only)
  └─ mpf number MPF amount (USA only)
  └─ hmf number HMF amount (USA only)
  └─ brokerage number Customs brokerage fee
  └─ bond number Customs bond amount
  └─ percentageFeesSubtotal number Sum of percentage-based fees (duty+tariff+gst+mpf+hmf)
  └─ total number Total customs charges (same as CustomsTotal)
  └─ note string Explanatory text about customs calculation

Technical Details

Data Sources

Caching Strategy

Performance Optimizations

Rate Limits

  • Google Maps API: Subject to Google's rate limits
  • Exchange Rate API: Free tier limitations
  • Recommendation: Implement client-side caching for repeated requests

Support & Contact

API Status

Check API health: GET /health

View dashboard: GET /dashboard

Monitoring

All API calls are logged with:

  • Request parameters and response data
  • Response time and status codes
  • Error details and stack traces
  • Unique request IDs for tracking

Updates

This API is actively maintained and updated. Check the health endpoint for current status and cache information.