Lane Insight Lookup

Pull WardenIQ's learned intelligence on a specific lane — win/loss history, 4-signal scores, plain-English signals, and a ready-to-display summary. Call it from your TMS, load board, or quoting tool to show operators smarter pricing context inline.

GET /api/integrations/insights/lane

What you get back

A single authenticated request returns everything you need to display lane intelligence in your UI — no additional round trips, no computation required on your side. Here's a real example response:

{
  "found": true,
  "query": {
    "origin": "Atlanta, GA",
    "destination": "Dallas, TX",
    "equipment": "V"
  },
  "scope": "equipment",
  "history": {
    "total_quotes": 42,
    "wins": 28,
    "losses": 14,
    "win_rate_pct": 66.7,
    "months_active": 8,
    "avg_rate_usd": 2150.0
  },
  "scores": {
    "harmonic": 0.78,
    "integral": 0.82,
    "derivative": 0.15,
    "correlation": 0.45
  },
  "signals": {
    "strength": "strong",
    "trend": "heating",
    "consistency": "reliable",
    "timing": "aligned"
  },
  "summary": "Strong lane with heating trend — 66.7% win rate over 42 quotes. Competitive markups should win consistently."
}

Drop-in ready for your UI

The fastest integration: just display summary as an inline tooltip or badge next to the rate input in your quoting screen. One field, one sentence, zero additional logic.

The richer integration: use signals for color-coded badges (green/yellow/gray), history.win_rate_pct for a big stat, and the raw scores if you want to build your own visualizations. Your product designer picks how deep to go.

Query parameters

Parameter	Type	Description
origin	string (required)	Pickup city + state. Examples: `Atlanta, GA`, `Los Angeles, CA`. City/state matching is case-insensitive with whitespace tolerance.
destination	string (required)	Delivery city + state. Same format as origin.
equipment	string (optional)	Equipment type code, e.g. `V` (dry van), `R` (reefer), `F` (flatbed). If omitted, WardenIQ returns corridor-wide intelligence across all equipment types.

Response field reference

scope

Tells you which data source produced the result. Trust decreases from top to bottom:

equipment Exact match on origin + destination + equipment. Most authoritative.
corridor Same origin + destination, any equipment. Use when your equipment is uncommon on this lane.
market Fell back to the freight market (e.g. Atlanta metro → Dallas metro). Coarse but still useful for directional intelligence.
state State-to-state aggregate (GA → TX). Use with caution.
region Region-to-region aggregate (SE → SW). Weakest signal, effectively a sanity-check.

history

Raw historical counts from this tenant's quoting history:

total_quotes — every quote ever sent on this lane (won + lost + pending)
wins / losses — decided outcomes
win_rate_pct — wins / (wins + losses) × 100
months_active — distinct calendar months with at least one quote
avg_rate_usd — average quoted rate across all historical quotes

scores

The 4-signal WardenIQ scoring engine. Values are generally 0..1 range (unbounded for integral and correlation). See the overview for background on how these are computed:

harmonic — harmonic mean of win-rate and volume. Resists single-win fluke outliers.
integral — cumulative activity score. Higher = more sustained engagement over time.
derivative — rate of change in volume. Positive = heating, negative = cooling.
correlation — cross-correlation between quote volume and win rate. High positive = they move together (seasonal or well-timed lanes).

signals

Human-readable categorizations derived from the raw scores. If you just want to display a badge in your UI, these are what you want:

strength: strong / moderate / weak / emerging / none
trend: heating / cooling / stable / new
consistency: seasonal / reliable / inconsistent / new
timing: aligned / misaligned / neutral / insufficient

summary

A plain-English one-liner describing the lane, ready to display without further processing. This is the easiest integration point — just show this string next to the rate input.

curl example

curl "https://wardeniq.com/api/integrations/insights/lane?origin=Atlanta,%20GA&destination=Dallas,%20TX&equipment=V" \
  -H "Authorization: Bearer YOUR_SERVICE_TOKEN"

Note: this is a read endpoint, so it does not require HMAC signing. Only the service token is needed. See Authentication for how to generate a service token.

No-data responses

If WardenIQ has no historical data for the lane at any fallback level, the response looks like this:

{
  "found": false,
  "query": {
    "origin": "Albuquerque, NM",
    "destination": "Helena, MT",
    "equipment": "F"
  }
}

When found is false, display a neutral "no data" state in your UI and let the operator decide based on market conditions. Don't fall back to dummy data — that poisons the learning loop.

Use cases

Inline quoting assistant. Load the lane when the operator opens an RFQ. Display the summary + win rate + signal badges above the rate input. Takes ~50ms per call; cache for 15 minutes per lane.
Load board triage. When a load board pushes 100 new loads, call this endpoint for each and show a 🟢/🟡/⚪ badge so the operator focuses on the high-confidence lanes first.
Pricing guardrails. Before sending a quote, check if the signal is weak or cooling. If so, prompt the operator for confirmation before sending.
Executive reporting. Pull the top 20 hottest lanes (highest derivative) weekly and surface them in your ops dashboard.

Rate limit

10 requests per second per tenant. Cache results for 15 minutes per lane/equipment combination to stay well within the limit.