Rates API

Get Market Rate

Retrieve current market rates for one or more lanes. Maximum batch size is 10 requests per API call.

Endpoint

POST /api/v1/rates

Request Body Parameters

The request body should contain an array of rate requests (maximum 10 requests per call). Each rate request object should use the following format:

Parameter	Type	Required	Description
originTerminal	string	Yes	Exact terminal name from our terminals list. Use the Terminals API to search for valid terminal names.
originType	string	No	Origin type ("marine" or "rail", defaults to "marine")
destinationCity	string	Yes	Destination city name (letters, spaces, hyphens, apostrophes)
destinationState	string	Yes	Destination state (2-letter code)
destinationZip	string	Yes	Destination ZIP code (5-digit or ZIP+4 format)

To find valid terminal names for your rate requests, use our Terminals API. The Terminals API provides search functionality to find terminals by name, location, or type. You can search for terminals using:

Text search across terminal names
Filter by terminal type (marine, rail, intermodal)
Location-based search using coordinates
City, state, and ZIP code filters

For example, to find terminals in Port Elizabeth:

curl -X GET 'https://api.drayrates.ai/api/v1/terminals/search?query=port+elizabeth' \
  -H 'x-api-key: YOUR_API_KEY'

Example Request

curl -X POST 'https://api.drayrates.ai/api/v1/rates' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "originTerminal": "APM Elizabeth Terminal",
      "originType": "marine",
      "destinationCity": "Chicago",
      "destinationState": "IL",
      "destinationZip": "60632"
    }
  ]'

Response Format

{
  "status": "success",
  "data": [
    {
      "origin": {
        "terminal": "APM Elizabeth Terminal",
        "type": "marine",
        "city": "Elizabeth",
        "state": "NJ",
        "coordinates": [40.6789, -74.1234]
      },
      "destination": {
        "city": "Chicago",
        "state": "IL",
        "zip": "60632",
        "coordinates": [41.8781, -87.6298]
      },
      "analysis": {
        "suggestedRate": 2500,
        "ratePerMile": 2.5,
        "confidenceScore": 85,
        "distance": 800,
        "rateRange": {
          "min": 2200,
          "max": 2800
        },
        "trend": "stable",
        "activity": "high",
        "timeline": {
          "entries": [
            {
              "date": "2024-01-01",
              "rate": 2400
            }
          ]
        }
      }
    }
  ]
}

Input Validation Rules

The API enforces the following validation rules for each rate request in the array:

originTerminal must be a valid terminal name from our terminals list
destinationCity must contain only letters, spaces, hyphens, and apostrophes
destinationCity cannot exceed 100 characters
destinationState must be a valid 2-letter US state code
destinationZip must be a valid 5-digit or 9-digit (ZIP+4) format
Maximum of 10 requests per API call

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or validation errors
400	Bad Request - Batch size exceeds limit of 10 requests
400	Bad Request - Invalid terminal name
400	Bad Request - Unable to geocode destination address
400	Bad Request - Unable to calculate distance
401	Unauthorized - Missing organization context
400	Bad Request - Organization missing billing information
429	Too Many Requests - API usage limit exceeded

Error Response Examples

Validation Errors

{
  "error": {
    "code": 400,
    "message": "Validation errors in requests",
    "errors": [
      {
        "index": 0,
        "errors": [
          "originTerminal must be a valid terminal name from our terminals list",
          "destinationCity must contain only letters, spaces, hyphens, and apostrophes"
        ]
      }
    ]
  }
}

Usage Limit Exceeded

{
  "error": {
    "code": 429,
    "message": "API usage limit exceeded. Current usage: 95, Limit: 100"
  }
}

Invalid Terminal

{
  "error": {
    "code": 400,
    "message": "Invalid terminal: Invalid Terminal Name"
  }
}

Geocoding Error

{
  "error": {
    "code": 400,
    "message": "Unable to geocode destination address: Chicago, IL"
  }
}

Resources
Find what you need here