openapi: 3.0.2
info:
  title: Pricing Insights API
  termsOfService: https://www.superdispatch.com/terms-of-service
  contact:
    name: API Support
    url: https://developer.superdispatch.com
    email: support@superdispatch.com
  version: 1.0.0
  description: >
    Optimize vehicle shipping costs with the **Pricing Insights API**, powered by Super Dispatch's advanced machine-learning algorithms.


    This API delivers real-time, market-driven pricing recommendations for every vehicle move on any route, leveraging historical trends, recent move data, and advanced analytics.


    Each recommendation includes a **Confidence Score**, a clear 0% to 100% metric indicating how closely the price aligns with historical data such as vehicle type, route, and recent moves, providing actionable insights to streamline operations and maximize profitability.


    ## Authentication


    We use API key authentication, which expects a static token to be passed via the `X-API-KEY` header.


    > 💡 The token is created by Super Dispatch. Please contact us for generation.


    ## Rate Limiting


    To ensure fair usage and prevent abuse, the Pricing Insights API enforces rate limiting. Each IP address is allowed up to 50 requests per 10 seconds. If this limit is exceeded, the API will return a `429 Too Many Requests` response. This rate limit helps maintain the performance and availability of the API for all users.


    ## Route Coverage and Limitations


    The Pricing Insights API supports pricing recommendations for routes within specific geographical coverage areas. Please note the following limitations:


    ##### Supported Routes


    - **Continental United States:** Routes within the contiguous United States (lower 48 states)

    - **Accessible Networks:** Locations with accessible road networks and reliable routing data

    - **Established Infrastructure:** ZIP codes in areas with established transportation infrastructure


    ##### Unsupported Route Types


    The API may return routing errors for the following scenarios:


    **Cross-Border Routes**


    Routes that cross international borders or involve non-mainland U.S. territories are not supported. This includes routes to/from:


    - Canada

    - Mexico

    - Alaska

    - Hawaii

    - Puerto Rico

    - Other U.S. territories


    **Remote/Rural Areas**


    Locations in extremely remote areas or regions with sparse road network data may not be accessible through our routing engine. This typically affects:


    - Very rural ZIP codes

    - Areas with limited transportation infrastructure


    **Inaccessible Locations**


    Areas that are not accessible by standard road transport, such as:


    - Locations requiring ferry access

    - Areas with no connecting roads

    - Regions outside our routing provider's coverage area

servers:
  - url: https://pricing-insights.superdispatch.com/
    description: The Production (live) server

components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    RecommendedPriceRequestSchema:
      type: object
      properties:
        pickup:
          type: object
          description: |
            Pickup location. You must provide either the city and state or the ZIP code.
            - If city and state are provided, zip is optional.
            - If zip is provided, city and state are optional.
          properties:
            city:
              type: string
              description: City
            state:
              type: string
              description: State (US state codes)
            zip:
              type: string
              description: Zip
          oneOf:
            - description: "Require zip."
              required: [zip]
            - description: "Require both city and state."
              required: [city, state]
        delivery:
          type: object
          description: |
            Delivery location. You must provide either the city and state or the ZIP code.
            - If city and state are provided, zip is optional.
            - If zip is provided, city and state are optional.
          properties:
            city:
              type: string
              description: City
            state:
              type: string
              description: State (US state codes)
            zip:
              type: string
              description: Zip
          oneOf:
            - description: "Require zip."
              required: [zip]
            - description: "Require both city and state."
              required: [city, state]
        trailer_type:
          type: string
          description: Trailer type
          enum:
            - open
            - enclosed
        vehicles:
          type: array
          description: List of vehicles
          items:
            type: object
            properties:
              type:
                type: string
                description: Type of the vehicle
                enum:
                  - sedan
                  - suv
                  - van
                  - coupe_2_doors
                  - pickup_2_doors
                  - pickup_4_doors
              is_inoperable:
                type: boolean
                description: Operability status of the vehicle
              make:
                type: string
                description: Make
              model:
                type: string
                description: Model
              year:
                type: string
                description: Year
            required:
              - type
              - is_inoperable
              - make
              - model
              - year
      required:
        - pickup
        - delivery
        - vehicles
    SuccessfulResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "success"
        data:
          type: object
          properties:
            price:
              type: number
              description: "Recommended price"
              example: 1272
            price_per_mile:
              type: number
              description: "Recommended price per mile."
              example: 0.02
            confidence:
              type: number
              description: "The Confidence Score reflects the reliability of each pricing recommendation, with 100 indicating the highest level of certainty based on available data."
              example: 69
              minimum: 0
              maximum: 100
            distance_miles:
              type: number
              description: "Total move distance in miles."
              example: 1450
            volume:
              type: number
              description: "Move count / lane volume signal behind the recommendation. May be null on low-volume or rural lanes."
              example: 42
              nullable: true
    SuccessfulResponseV2:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "success"
        data:
          type: object
          properties:
            price:
              type: number
              description: "Recommended price."
              example: 1272
            price_per_mile:
              type: number
              description: "Recommended price per mile."
              example: 0.88
            distance_miles:
              type: number
              description: "Total move distance in miles."
              example: 1450
            volume:
              type: number
              description: "Move count / lane volume signal behind the recommendation, derived from comparable moves on the lane over the trailing 90 days. May be null on low-volume or rural lanes."
              example: 42
              nullable: true
            confidence:
              type: number
              description: "The Confidence Score reflects the reliability of each pricing recommendation, with 100 indicating the highest level of certainty based on available data."
              example: 69
              minimum: 0
              maximum: 100
              nullable: true
            price_range_lower:
              type: number
              description: "Lower bound of the recommended price range, derived from comparable recent moves on the lane. May be null when there is insufficient data."
              example: 1150
              nullable: true
            price_range_upper:
              type: number
              description: "Upper bound of the recommended price range, derived from comparable recent moves on the lane. May be null when there is insufficient data."
              example: 1400
              nullable: true
            min_expected_time_to_dispatch:
              type: number
              description: "Lower estimate of how long the load is expected to take to dispatch (book) at the recommended price, in hours. Based on comparable recent moves on the lane; may be null when there is insufficient data."
              example: 1.5
              nullable: true
            max_expected_time_to_dispatch:
              type: number
              description: "Upper estimate of how long the load is expected to take to dispatch (book) at the recommended price, in hours. Based on comparable recent moves on the lane; may be null when there is insufficient data."
              example: 6.0
              nullable: true
            recent_moves:
              type: array
              description: "Recent comparable moves on this lane that informed the recommendation. Empty when no comparable moves are available."
              items:
                $ref: "#/components/schemas/RecentMove"
    RecentMove:
      type: object
      properties:
        delivered_date:
          type: string
          description: "Date when the move was delivered (YYYY-MM-DD)."
          example: "2026-04-28"
          nullable: true
        dispatched_date:
          type: string
          description: "Date when the move was dispatched (YYYY-MM-DD)."
          example: "2026-04-27"
          nullable: true
        posting_date:
          type: string
          description: "Date when the move was posted to the loadboard (YYYY-MM-DD)."
          example: "2026-04-27"
          nullable: true
        price:
          type: number
          description: "Final price the move was booked at."
          example: 400.0
          nullable: true
        posted_price:
          type: number
          description: "Price the move was originally posted at."
          example: 325.0
          nullable: true
        status:
          type: string
          description: "Status of the move."
          example: "invoiced"
          nullable: true
        pickup_city:
          type: string
          description: "Pickup city."
          example: "Reno"
          nullable: true
        pickup_state:
          type: string
          description: "Pickup state (US state code)."
          example: "NV"
          nullable: true
        pickup_zip:
          type: string
          description: "Pickup ZIP code."
          example: "89506"
          nullable: true
        delivery_city:
          type: string
          description: "Delivery city."
          example: "Gardena"
          nullable: true
        delivery_state:
          type: string
          description: "Delivery state (US state code)."
          example: "CA"
          nullable: true
        delivery_zip:
          type: string
          description: "Delivery ZIP code."
          example: "90248"
          nullable: true
        distance_miles:
          type: number
          description: "Move distance in miles."
          example: 490
          nullable: true
        vehicles:
          type: array
          description: "Vehicles included in the move."
          items:
            $ref: "#/components/schemas/RecentMoveVehicle"
    RecentMoveVehicle:
      type: object
      properties:
        type:
          type: string
          description: "Type of the vehicle."
          example: "sedan"
        year:
          type: integer
          description: "Vehicle year."
          example: 2023
          nullable: true
        make:
          type: string
          description: "Vehicle make."
          example: "toyota"
          nullable: true
        model:
          type: string
          description: "Vehicle model."
          example: "camry"
          nullable: true
        is_inoperable:
          type: boolean
          description: "Whether the vehicle is inoperable."
          example: false
        requires_enclosed_trailer:
          type: boolean
          description: "Whether the vehicle requires an enclosed trailer."
          example: false
    UnauthorizedResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            message:
              type: string
              example: "Token provided is invalid"
            details:
              type: array
              items:
                type: string
    TokenNotProvidedResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            message:
              type: string
              example: "Authorization header was not provided"
            details:
              type: array
              items:
                type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: "#/components/schemas/ValidationError"
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            type: string
        msg:
          type: string
        type:
          type: string
    RateLimitExceededResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            message:
              type: string
              example: "Too many requests"
    ForbiddenResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            message:
              type: string
              example: "The request cannot be completed because you have exceeded your quota"
    InvalidRouteResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            type:
              type: string
              example: "NO_ROUTE_AVAILABLE"
            message:
              type: string
              example: "Pickup or delivery location is not accessible by road."
            details:
              type: object
              properties:
                reason:
                  type: string
                  example: "The routing engine could not find a drivable path between the provided locations. One of the ZIP codes may be in a region without road access or outside supported routing coverage."
                next_steps:
                  type: array
                  items:
                    type: string
                  example:
                    - "Some locations may require special handling, such as ocean or air transport."
                    - "Consider splitting the route into separate legs—for example, to and from a nearby mainland or serviceable area."
                    - "If this is expected behavior, consider handling routing manually or using a different provider for this segment."
    SameZipCodesResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: string
              example: "fail"
        data:
          type: object
          properties:
            type:
              type: string
              example: "SAME_ZIP_CODES"
            message:
              type: string
              example: "Recommended Price isn't available when Pickup and Delivery ZIP codes are the same."
            details:
              type: object
              properties:
                reason:
                  type: string
                  example: "Pickup and Delivery ZIP codes must be different to generate a Recommended Price."
                next_steps:
                  type: array
                  items:
                    type: string
                  example:
                    - "Enter different ZIP codes for Pickup and Delivery locations."
                    - "If this is a local move, pricing may need to be handled manually or through a custom rate."

tags:
  - name: Pricing Insights
    description: Endpoints for getting pricing recommendations

paths:
  /api/v1/recommended-price:
    post:
      tags:
        - Pricing Insights
      summary: Recommended Price
      description: >
        <p>This endpoint calculates and returns the recommended price based on the specified location and vehicle details.</p>

        <h5>Confidence Score</h5>
        <p>The Confidence Score reflects the reliability of each pricing recommendation, with 100 indicating the highest level of certainty based on available data.</p>

        <ul>
          <li><b>0&#8208;59% Low Confidence:</b> Pricing Recommendations based on minimal data. Review similar orders on the Super Loadboard for additional insights is recommended.</li>
          <li><b>60&#8208;84% Medium Confidence:</b> Pricing Recommendations supported by relevant data. Minor adjustments may be required; reviewing similar orders on the Super Loadboard is recommended.</li>
          <li><b>85&#8208;100% High Confidence:</b> Pricing Recommendations backed by comprehensive market data, offering highly reliable pricing with minimal need for additional review.</li>
        </ul>
      operationId: get_recommended_price_api_v1_recommended_price_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendedPriceRequestSchema"
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessfulResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/TokenNotProvidedResponse"
                  - $ref: "#/components/schemas/UnauthorizedResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SameZipCodesResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "429":
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitExceededResponse"
        "404":
          description: Invalid Route
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidRouteResponse"
  /api/v2/recommended-price:
    post:
      tags:
        - Pricing Insights
      summary: Recommended Price (v2)
      description: >
        <p>Calculates and returns the recommended price for the specified location and vehicle details, along with richer market context than <code>/api/v1/recommended-price</code>.</p>

        <p>In addition to the recommended price, the v2 response includes a recommended price range (<code>price_range_lower</code> / <code>price_range_upper</code>), an estimated time-to-dispatch range in hours (<code>min_expected_time_to_dispatch</code> / <code>max_expected_time_to_dispatch</code>), and a list of recent comparable moves (<code>recent_moves</code>) that informed the recommendation.</p>

        <h5>Confidence Score</h5>
        <p>The Confidence Score reflects the reliability of each pricing recommendation, with 100 indicating the highest level of certainty based on available data.</p>

        <ul>
          <li><b>0&#8208;59% Low Confidence:</b> Pricing Recommendations based on minimal data. Review similar orders on the Super Loadboard for additional insights is recommended.</li>
          <li><b>60&#8208;84% Medium Confidence:</b> Pricing Recommendations supported by relevant data. Minor adjustments may be required; reviewing similar orders on the Super Loadboard is recommended.</li>
          <li><b>85&#8208;100% High Confidence:</b> Pricing Recommendations backed by comprehensive market data, offering highly reliable pricing with minimal need for additional review.</li>
        </ul>
      operationId: get_recommended_price_api_v2_recommended_price_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendedPriceRequestSchema"
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessfulResponseV2"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/TokenNotProvidedResponse"
                  - $ref: "#/components/schemas/UnauthorizedResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SameZipCodesResponse"
                  - $ref: "#/components/schemas/InvalidRouteResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "429":
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitExceededResponse"