Gateway
Sign Up

API Documentation

Complete reference for all Gateway API endpoints.

Authentication

All endpoints use the X-API-Key header for authentication.

X-API-Key: YOUR_API_KEY

Don't have a key? Sign up free to get one instantly.

Base URL

https://api.gatewaylines.com

Endpoints

7 endpoints available

POST/api/tariff/public/calculate100/mo

Calculate US import duties for any HTS code and country of origin. Returns MFN rates, Section 301, IEEPA, reciprocal tariffs, and AD/CVD.

Request Body

hts_codestringrequiredHTS code (e.g., "8471.30.01")
country_codestringrequiredISO country code (e.g., "CN")
declared_valuenumberDeclared value in USD for duty calculation

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tariff_YOUR_KEY" \
  -d '{"hts_code": "8471.30.01", "country_code": "CN", "declared_value": 10000}'

Example Response

{
  "hts_code": "8471.30.01",
  "description": "Portable digital automatic data processing machines...",
  "country": "China",
  "base_duty_rate": "0%",
  "total_tariff_rate": 145,
  "total_duty": 14500,
  "tariff_breakdown": [
    { "type": "MFN", "rate": 0 },
    { "type": "IEEPA", "rate": 20 },
    { "type": "Reciprocal", "rate": 125 }
  ]
}
POST/api/tariff/public/ai-search100/mo

Describe a product in plain English and get the matching HTS code with AI classification.

Request Body

querystringrequiredProduct description (e.g., "laptop computer")
country_codestringCountry of origin for tariff context

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/ai-search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tariff_YOUR_KEY" \
  -d '{"query": "wireless bluetooth headphones", "country_code": "CN"}'

Example Response

{
  "results": [
    {
      "hts_code": "8518.30.20",
      "description": "Headphones, earphones and combined microphone/speaker sets",
      "confidence": 0.94,
      "base_duty_rate": "Free"
    }
  ]
}
POST/api/tariff/public/trackCredits-based

Track any ocean container worldwide. Returns real-time position, vessel info, ETAs, port events, and route timeline via satellite AIS data. Requires tracking credits (1 credit per new container, re-checks are free). Purchase credits on the Billing page.

Request Body

container_numberstringrequiredContainer number (e.g., "MSCU1234567")

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/track \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tariff_YOUR_KEY" \
  -d '{"container_number": "MSCU1234567"}'

Example Response

{
  "container_number": "MSCU1234567",
  "status": "IN_TRANSIT",
  "carrier": "MSC",
  "origin": { "port": "SHANGHAI", "locode": "CNSHA", "departure": "2026-01-15" },
  "destination": { "port": "LOS ANGELES", "locode": "USLAX", "arrival_eta": "2026-02-20", "ml_eta": "2026-02-21" },
  "position": { "lat": 32.5, "lng": -152.3 },
  "vessel": { "name": "MSC DITTE", "imo": 9754953 },
  "events": [
    { "description": "Loaded on vessel", "location": "SHANGHAI", "date": "2026-01-15" },
    { "description": "Departed origin", "location": "SHANGHAI", "date": "2026-01-16" }
  ],
  "tracking_credits": 9
}
POST/api/tariff/public/load-planner100/mo

Calculate container loading. Returns volume/weight utilization for 20ST, 40ST, 40HC containers, plus FCL vs LCL recommendation.

Request Body

cargo_itemsarrayrequiredArray of cargo items with dimensions
cargo_items[].namestringItem name
cargo_items[].lengthnumberrequiredLength in meters
cargo_items[].widthnumberrequiredWidth in meters
cargo_items[].heightnumberrequiredHeight in meters
cargo_items[].weightnumberrequiredWeight in kg
cargo_items[].quantitynumberrequiredNumber of units
container_typestring"20ST", "40ST", or "40HC" (default: all)

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/load-planner \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tariff_YOUR_KEY" \
  -d '{
    "cargo_items": [
      { "name": "Pallets", "length": 1.2, "width": 1.0, "height": 1.5, "weight": 800, "quantity": 10 }
    ]
  }'

Example Response

{
  "cargo_summary": { "total_cbm": 18.0, "total_weight_kg": 8000, "total_pieces": 10 },
  "containers": [
    { "container_type": "20ST", "fits": true, "volume_utilization": 54.2, "weight_utilization": 28.4 },
    { "container_type": "40ST", "fits": true, "volume_utilization": 26.6, "weight_utilization": 27.9 },
    { "container_type": "40HC", "fits": true, "volume_utilization": 23.7, "weight_utilization": 28.0 }
  ],
  "recommendation": "Best fit: 20' Standard at 54.2% volume utilization.",
  "fcl_vs_lcl": "FCL"
}
POST/api/tariff/public/parcel-quote100/mo

Get instant USPS, UPS, and FedEx shipping rates for US domestic parcels. Returns sorted quotes by price. No label creation.

Request Body

ship_fromobjectrequiredOrigin address
ship_from.address_line1stringrequiredStreet address
ship_from.city_localitystringrequiredCity
ship_from.state_provincestringrequiredState (e.g., "CA")
ship_from.postal_codestringrequiredZIP code
ship_from.country_codestringrequired"US" (US domestic only)
ship_toobjectrequiredDestination address (same fields as ship_from)
packagesarrayrequiredArray of packages (max 5)
packages[].weightobjectrequired{ value: number, unit: "pound" | "ounce" }
packages[].dimensionsobject{ length, width, height, unit: "inch" }

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/parcel-quote \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tariff_YOUR_KEY" \
  -d '{
    "ship_from": {
      "address_line1": "123 Main St", "city_locality": "Miami",
      "state_province": "FL", "postal_code": "33101", "country_code": "US"
    },
    "ship_to": {
      "address_line1": "456 Oak Ave", "city_locality": "Los Angeles",
      "state_province": "CA", "postal_code": "90001", "country_code": "US"
    },
    "packages": [{ "weight": { "value": 5, "unit": "pound" } }]
  }'

Example Response

{
  "quotes": [
    { "carrier": "USPS", "service": "usps_priority_mail", "rate": { "amount": 8.95, "currency": "USD" }, "estimated_delivery_days": 3 },
    { "carrier": "UPS", "service": "ups_ground", "rate": { "amount": 12.45, "currency": "USD" }, "estimated_delivery_days": 5 },
    { "carrier": "FedEx", "service": "fedex_ground", "rate": { "amount": 11.20, "currency": "USD" }, "estimated_delivery_days": 4 }
  ],
  "route": { "from": "Miami, FL 33101", "to": "Los Angeles, CA 90001" }
}
POST/api/tariff/public/co25/week

Calculate carbon emissions for ocean freight shipments between any two ports. Returns Well-to-Wake (WtW), Tank-to-Wake (TtW), and Well-to-Tank (WtT) emissions in metric tons, plus flight and tree-offset equivalencies. Separate rate limit: 5/week free, unlimited for Pro.

Request Body

origin_portstringrequiredOrigin port UN/LOCODE (e.g., "CNSHA")
destination_portstringrequiredDestination port UN/LOCODE (e.g., "USLAX")
container_sizestring"20", "40", "40HC", or "45" (default: "40")
container_countnumberNumber of containers (default: 1, max: 999)
vessel_imostringVessel IMO number for vessel-specific calculation

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/co2 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gw_YOUR_KEY" \
  -d '{"origin_port": "CNSHA", "destination_port": "USLAX", "container_size": "40", "container_count": 2}'

Example Response

{
  "origin_port": "CNSHA",
  "destination_port": "USLAX",
  "distance_nm": 6252,
  "container_count": 2,
  "container_size": "40",
  "teu_factor": 2,
  "total_teu": 4,
  "calculation_method": "trade_lane",
  "emissions": {
    "per_teu": { "wtw_tons": 1.5432, "ttw_tons": 1.2105, "wtt_tons": 0.3327 },
    "total": { "wtw_tons": 6.1728, "ttw_tons": 4.842, "wtt_tons": 1.3308 }
  },
  "comparisons": {
    "flights_nyc_la_equivalent": 6.9,
    "trees_to_offset_annually": 281
  }
}
POST/api/tariff/public/port-congestion5 unlocks/mo

Query real-time congestion data for 500+ ports worldwide. Returns congestion score, vessel counts, wait times, and 30-day history. Free tier: 5 port unlocks/month (24h visibility each). Pro tier: unlimited access to all ports.

Request Body

listbooleanSet true to list all ports (congestion blurred for free tier unless unlocked)
unlocodestringSingle port UN/LOCODE (e.g., "USLAX"). Uses an unlock credit for free tier.

Example Request

curl -X POST https://api.gatewaylines.com/api/tariff/public/port-congestion \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gw_YOUR_KEY" \
  -d '{"unlocode": "USLAX"}'

Example Response

{
  "unlocode": "USLAX",
  "name": "Los Angeles",
  "city": "Los Angeles",
  "country": "United States",
  "congestion": { "score": 62, "level": "High", "trend": "increasing", "trend_pct": 5.2 },
  "vessels": { "anchored": 12, "in_port": 38 },
  "wait_times": {
    "berth_wait_hours": 18,
    "dwell_time_hours": 72,
    "anchor_wait_hours": 14.5,
    "seven_day_avg_hours": 16.2,
    "thirty_day_avg_hours": 15.8
  },
  "capacity": { "total_berths": 82, "container_berths": 51, "annual_teu": 9200000 },
  "history": [
    { "score": 58, "date": "2026-02-03T00:00:00Z" },
    { "score": 62, "date": "2026-03-05T00:00:00Z" }
  ],
  "tier": "free",
  "locked": false,
  "expires_at": "2026-03-06T15:00:00Z",
  "unlocks": { "used": 1, "limit": 5, "remaining": 4, "resets": "2026-04-01" }
}

Error Codes

400Bad request - missing or invalid parameters
401Unauthorized - invalid or missing API key
403Forbidden - endpoint not available on your plan
404Not found - resource does not exist
429Rate limit exceeded - usage resets monthly
502Bad gateway - upstream service temporarily unavailable
500Server error - contact [email protected]

Rate Limits

Free Tier

100 API calls per month across general endpoints. Some endpoints have their own separate limits.

Tariff Calculator100/month (shared pool)
AI HTS Search100/month (shared pool)
3D Load Planner100/month (shared pool)
Parcel Quotes100/month (shared pool, US domestic only)
CO2 Emissions Calculator5/week (separate counter)
Port Congestion5 unlocks/month, 24h data per unlock (separate counter)
Container TrackingRequires tracking credits (from $15/mo)
Parcel LabelsRequires funded courier balance

Tariff Pro ($199/mo)

10,000 API calls per month. Includes built-in calculator, branded reports, and AI explanations.

All general endpoints10,000/month (shared pool)
CO2 Emissions CalculatorUnlimited
Port CongestionUnlimited (all 500+ ports)
Container TrackingRequires tracking credits (from $15/mo)
Parcel LabelsRequires funded courier balance

Need higher limits? Contact [email protected]

SDK Examples

JavaScript / Node.js

const res = await fetch('https://api.gatewaylines.com/api/tariff/public/calculate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tariff_YOUR_KEY'
  },
  body: JSON.stringify({
    hts_code: '8471.30.01',
    country_code: 'CN',
    declared_value: 10000
  })
})
const data = await res.json()
console.log(data.total_duty) // 14500

Python

import requests

res = requests.post(
    'https://api.gatewaylines.com/api/tariff/public/calculate',
    headers={'X-API-Key': 'tariff_YOUR_KEY'},
    json={
        'hts_code': '8471.30.01',
        'country_code': 'CN',
        'declared_value': 10000
    }
)
data = res.json()
print(data['total_duty'])  # 14500

Need Help?

Our team is ready to help you integrate Gateway into your systems.

Contact SupportGet API Key