---
title: "Query freight rates"
method: POST
path: "/api/v1/external/rates/query"
tags: ["Rates"]
---

# Query freight rates

`POST /api/v1/external/rates/query`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/rates/query`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/rates/query/post.ts> (a function with typed inputs; its response is checked against the schema)

Query freight rates from your Query Bank with flexible location and container filtering.

**Location Filtering**:
- Use `origins` and `destinations` for door-to-door moves (inland points)
- Use `loadingPorts` and `dischargePorts` for port-to-port moves
- Combine both for door-to-port or port-to-door queries
- Region codes like USWC, USEC are supported for broader searches

**Rate Structure**:
Each rate includes:
- Route information with all legs (pre-carriage, main, on-carriage)
- Container rates with per-leg breakdown
- Applicable surcharges with container-specific amounts

**Pagination**:
Results are paginated with a default limit of 100 rates per request.

## Request body

- QueryBankRateQueryRequest
  - `origins` string[]: Inland origin codes or region codes (USWC, USEC, etc.) for door moves
  - `destinations` string[]: Inland destination codes or region codes for door moves
  - `loadingPorts` string[]: Port of loading codes (UN/LOCODE format)
  - `dischargePorts` string[]: Port of discharge codes (UN/LOCODE format)
  - `effectiveDate` string, date: Filter rates effective on or after this date
  - `expiryDate` string, date: Filter rates that haven't expired by this date
  - `containerType` 'dry' | 'reefer' | 'nor': Container type filter
  - `containerSizes` string[]: Container size filter
  - `carrierCodes` string[]: Filter by specific carrier SCAC codes
  - `commodityType` string: Filter by commodity type
  - `limit` integer: Maximum number of rates to return
  - `offset` integer: Number of rates to skip for pagination

## Response `200`

Rates retrieved successfully

- object
  - `success` boolean
  - `data` QueryBankRateQueryResponse
    - `rates` CombinedRate[]
      - `id` string, required: Unique identifier for the rate (hash for deduplication)
      - `placeOfReceipt` LocationInfo
        - `code` string, required: Location code (UN/LOCODE for ports)
        - `name` string: Location display name
        - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
      - `portOfLoading` LocationInfo, required
        - `code` string, required: Location code (UN/LOCODE for ports)
        - `name` string: Location display name
        - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
      - `portOfDischarge` LocationInfo, required
        - `code` string, required: Location code (UN/LOCODE for ports)
        - `name` string: Location display name
        - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
      - `placeOfDelivery` LocationInfo
        - `code` string, required: Location code (UN/LOCODE for ports)
        - `name` string: Location display name
        - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
      - `viaPorts` LocationInfo[]: Transshipment ports in order
        - `code` string, required: Location code (UN/LOCODE for ports)
        - `name` string: Location display name
        - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
      - `carrierCode` string, required: Carrier SCAC code
      - `carrierName` string: Carrier display name
      - `effectiveDate` string, date
      - `expiryDate` string, date
      - `commodityType` string
      - `transitTime` integer: Transit time in days
      - `legs` RateLeg[]: Rate breakdown by leg (pre-carriage, main, on-carriage)
        - `type` 'pre_carriage' | 'main' | 'on_carriage', required: Leg type
        - `origin` LocationInfo, required
          - `code` string, required: Location code (UN/LOCODE for ports)
          - `name` string: Location display name
          - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
        - `destination` LocationInfo, required
          - `code` string, required: Location code (UN/LOCODE for ports)
          - `name` string: Location display name
          - `type` 'port' | 'city' | 'address' | 'region', required: Type of location
        - `mode` 'truck' | 'rail' | 'barge' | 'ocean': Transport mode for this leg
        - `rates` LegContainerRate[]: Container rates for this specific leg
          - `containerSize` '20ft' | '40ft' | '40ft_hc' | '45ft', required
          - `containerType` 'dry' | 'reefer' | 'nor' | 'general', required
          - `amount` number, required: Rate amount
          - `currency` string, required: Currency code (ISO 4217)
      - `containerRates` CombinedContainerRate[], required: Container-specific pricing
        - `containerType` 'dry' | 'reefer' | 'nor', required
        - `containerSize` '20ft' | '40ft' | '40ft_hc' | '45ft', required
        - `amount` number, required: Total combined rate amount
        - `currency` string, required
        - `breakdown` object: Per-leg breakdown of the total amount
          - `preCarriage` number: Pre-carriage portion
          - `main` number: Ocean freight portion
          - `onCarriage` number: On-carriage portion
      - `surcharges` RateSurcharge[]: Applicable surcharges
        - `code` string, required: Surcharge code (e.g., BAF, CAF, THC)
        - `name` string, required: Surcharge display name
        - `applicability` 'inclusive' | 'subject_to' | 'not_subject_to' | 'not_applicable', required: Whether this surcharge is included in base rate or additional
        - `basis` string: Charging basis (e.g., per_container, per_bl, percentage)
        - `amount` number: Default surcharge amount (when not container-specific)
        - `currency` string
        - `containerRates` SurchargeContainerRate[]: Container-specific surcharge amounts
          - `containerSize` '20ft' | '40ft' | '40ft_hc' | '45ft', required
          - `containerType` 'dry' | 'reefer' | 'nor' | 'general' | 'all'
          - `amount` number, required
          - `currency` string, required
        - `percentage` number: Percentage-based surcharge (if applicable)
        - `applicablePorts` string[]: Specific ports this surcharge applies to
        - `effectiveDate` string, date
        - `expiryDate` string, date
      - `sourceId` string, required: Source ID where this rate originated
      - `sourceName` string, required: Source filename
    - `metadata` object
      - `totalRates` integer: Total number of matching rates
      - `sourcesSearched` integer: Number of sources searched
      - `queryTimeMs` integer: Query execution time in milliseconds

## Other responses

- `400`: Bad request - invalid query parameters
- `401`: Authentication required
- `403`: Insufficient permissions - requires rates:read scope

---

[API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)