---
updatedAt: 2026-08-09T09:54:35.000Z
agentTools:
  projectIndex: https://apidocs.freightos.com/llms.txt
---

# Get price statistics (GET)

Retrieve price statistics using query parameters. You can query a single route by providing all route parameters, or query your subscription routes by omitting route parameters.

**Rate Limit**: 10 requests per minute
**Typical Response Time**: 2-16 seconds

**Route Quota**: Each subscription has a limit on unique routes you can query. Routes are uniquely identified by origin, destination, mode, and load tag. Only routes that return actual data (with coverage) count toward your quota. Once a route is stored with coverage, you can query it repeatedly without using quota. If you exceed your quota, you'll receive an error message indicating how many routes you're allowed and how many you requested.

OCEAN REGIONS = \[ "Gulf Area", "Red Sea", "Asia, Central", "Asia, Southern", "Asia, China, South-East Asia", "Africa, Sub-Saharan", "Africa, Northern", "Europe, Eastern", "Europe, Northern", "Europe, Southern", "Oceania, Australia", "Americas, US East", "Americas, US West", "Americas, Canada East", "Americas, Canada West", "Americas, Central", "Americas, South East", "Americas, South West" ]

AIR\_REGIONS = \[ "Middle East", "Asia, Southern", "Americas, Caribbean", "Europe, Southern", "Middle Africa", "Americas, South", "Americas, US West", "Europe, Northern", "Oceania, Australia", "Oceania, Pacific Islands", "Africa, Western", "Europe, Eastern", "Africa, Eastern", "Africa, Southern", "Americas, Central", "Asia, South-eastern", "Americas, Canada East", "Americas, Canada West", "Asia, Greater China", "Africa, Northern", "Asia, Central", "Asia, Japan", "Asia, Korea", "Europe, Russia", "Oceania, New Zealand", "Americas, US East", "Americas, US Central" ]

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Price Stats API",
    "description": "Returns price statistics in USD for shipping routes. Supports both GET and POST requests with flexible route specification modes.\n\n## How to Use?\n\n1. **Single Route**: Provide `origin`, `destination`, `mode`, and `load` parameters to get statistics for a specific route\n2. **Multiple Routes**: Use POST request with a `routes` array in the request body to query multiple routes at once\n3. **Subscription Routes**: Omit route parameters to automatically fetch price stats for all routes configured in your subscription\n\n## Route Quota System\n\n**Important**: Each subscription has a limit on the number of **unique routes** you can query. Understanding how routes are counted helps you manage your quota effectively.\n\n### What Counts as a Unique Route?\n\nA route is uniquely identified by the combination of:\n- **Origin** (e.g., `CNSHA`)\n- **Destination** (e.g., `USLAX`)\n- **Mode** (e.g., `FCL`, `Air` or `LCL`)\n- **Load Tag** (e.g., `40'`, `20'`, `40'HC`; always `ALL` for LCL)\n\n**Examples:**\n- `CNSHA → USLAX, FCL, 40'` = 1 unique route\n- `CNSHA → USLAX, FCL, 20'` = 1 unique route (different load tag)\n- `CNSHA → USLAX, Air, 40'` = 1 unique route (different mode)\n- `CNSHA → USLAX, LCL, ALL` = 1 unique route (different mode)\n- `GBSOU → ARBUE, FCL, 40'` = 1 unique route (different origin/destination)\n\n### How Quota Works\n\n- **Route Storage**: When you successfully query routes, they are automatically stored in your account\n- **Coverage Tracking**: Only routes that return actual data (with coverage) count toward your quota\n- **Re-querying**: Querying the same route again does **not** count against your quota if it's already stored with coverage\n- **New Routes**: Only routes you haven't queried before (or that don't have coverage) count as new\n\n### Quota Validation\n\nThe API performs two validation checks:\n\n1. **Request-Level Validation**: Counts unique routes in your current request and rejects if it exceeds your quota\n2. **Coverage-Based Validation**: Checks how many unique routes with coverage you currently have stored and validates that adding new routes won't exceed your limit\n\n**Example:**\n- Your quota: 10 unique routes\n- Currently stored: 7 routes with coverage\n- Your request: 5 routes (3 are new, 2 already exist)\n- Result: ✅ Allowed (7 + 3 = 10, within limit)\n\n**Important**: A route must return actual data (coverage) to count toward your quota. If a route query returns no data, it doesn't count against your limit.\n\n### Quota Limits\n\nYour subscription's `allowed_unique_routes` value determines your limit. This is set per subscription and cannot be changed via the API.\n\n**Common Scenarios:**\n- **Within Quota**: Request processes normally\n- **Exceeds Quota**: API returns error: `\"You are allowed to query up to X unique routes. Your request contains Y unique routes.\"`\n- **No Quota**: API returns error: `\"You are not allowed to query any routes with the current subscription\"`\n\n**To increase your quota**: Contact Freightos support with your customer ID or email.\n\n## What is Confidence Level?\n\nConfidence level represents the amount of data points used to calculate the percentiles for a specific route. Higher confidence levels indicate more reliable statistics.\n\n**For FCL Routes:**\n- **Low**: 1 or 2 data points\n- **Medium**: 3 or 4 data points\n- **High**: 5 to 9 data points\n- **Very High**: 10+ data points\n\n**For LCL Routes:** same bands as FCL.\n\n**For Air Routes:**\n- **Low**: 1 to 9 data points\n- **Medium**: 10 to 49 data points\n- **High**: 50 to 199 data points\n- **Very High**: 200+ data points\n\n## Rate Limits\n\n- **Limit**: 10 requests per minute per IP address\n- Returns HTTP 429 on limit exceeded\n\n## Additional Notes\n\n- All prices are in USD\n- Location codes must be valid IATA codes (for air) or UN/LOCODE codes (for ocean)\n- The API automatically handles route deduplication\n- Date format must be `YYYY-MM-DD`\n- If `from_date` is before your subscription start date, the API uses your subscription date range automatically",
    "version": "3.0.0",
    "contact": {
      "name": "Freightos Support"
    }
  },
  "servers": [
    {
      "url": "https://api.freightos.com/fd_external_apis",
      "description": "Production server"
    },
    {
      "url": "https://api.test-freightos.com/fd_external_apis",
      "description": "Development server"
    }
  ],
  "tags": [
    {
      "name": "Price Stats",
      "description": "Price statistics for shipping routes"
    }
  ],
  "paths": {
    "/price_stats/": {
      "get": {
        "tags": [
          "Price Stats"
        ],
        "summary": "Get price statistics (GET)",
        "description": "Retrieve price statistics using query parameters. You can query a single route by providing all route parameters, or query your subscription routes by omitting route parameters.\n\n**Rate Limit**: 10 requests per minute\n**Typical Response Time**: 2-16 seconds\n\n**Route Quota**: Each subscription has a limit on unique routes you can query. Routes are uniquely identified by origin, destination, mode, and load tag. Only routes that return actual data (with coverage) count toward your quota. Once a route is stored with coverage, you can query it repeatedly without using quota. If you exceed your quota, you'll receive an error message indicating how many routes you're allowed and how many you requested.",
        "operationId": "getPriceStats",
        "parameters": [
          {
            "name": "route_type",
            "in": "query",
            "required": false,
            "description": "Type of route to filter by. P2P (port to port), C2C (country to country), R2R (region to region), P2R (port to region), R2P (region to port), P2C (port to country), C2P (country to port), C2R (country to region), R2C (region to country). Defaults to P2P. Ports are UN/LOCODE for ocean or IATA for air, countries are two-letter ISO codes, regions are a three-letter region code or the full region name. Every type except P2P requires route_matching=exact. LCL supports P2P only.",
            "schema": {
              "type": "string",
              "enum": [
                "P2P",
                "C2C",
                "R2R",
                "P2R",
                "R2P",
                "P2C",
                "C2P",
                "C2R",
                "R2C"
              ],
              "example": "P2P"
            }
          },
          {
            "name": "from_date",
            "in": "query",
            "required": true,
            "description": "Start date for the statistics in YYYY-MM-DD format",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-02-01"
            }
          },
          {
            "name": "to_date",
            "in": "query",
            "required": true,
            "description": "End date for the statistics in YYYY-MM-DD format",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-11-03"
            }
          },
          {
            "name": "tradelanes_type",
            "in": "query",
            "required": false,
            "description": "Type of tradelane. Required if not specifying a single route (all 4 route parameters: origin, destination, mode, load)",
            "schema": {
              "type": "string",
              "enum": [
                "air",
                "ship",
                "lcl"
              ],
              "example": "ship"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "description": "Data version. Defaults to your subscription's default version",
            "schema": {
              "type": "string",
              "enum": [
                "daily",
                "weekly",
                "monthly"
              ],
              "default": "weekly",
              "example": "weekly"
            }
          },
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "description": "Origin location for the shipment. Accepts three formats: port code (e.g., 'CNSHA'), country code (e.g., 'CN'), or region (e.g., 'Asia, China, South-East Asia'). Required for single route queries along with destination, mode, and load.",
            "schema": {
              "type": "string",
              "example": "CNSHA"
            }
          },
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "description": "Destination location for the shipment. Accepts three formats: port code (e.g., 'USLAX'), country code (e.g., 'US'), or region (e.g., 'Americas, US West'). Required for single route queries along with destination, mode, and load.",
            "schema": {
              "type": "string",
              "example": "USLAX"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Transportation mode. Required for single route queries along with origin, destination, and load",
            "schema": {
              "type": "string",
              "enum": [
                "Air",
                "FCL",
                "LCL"
              ],
              "example": "FCL"
            }
          },
          {
            "name": "load",
            "in": "query",
            "required": false,
            "description": "Load tag identifier (e.g., 20', 40', 40'HC, 20DC, 40DC, 40HC). Required for single route queries along with origin, destination, and mode. The API automatically maps: 20DC → 20', 40DC → 40', 40HC → 40'HC. For LCL use ALL",
            "schema": {
              "type": "string",
              "example": "40'"
            }
          },
          {
            "name": "route_matching",
            "in": "query",
            "required": false,
            "description": "Route matching mode. Use 'exact' to return only exact route matches, or 'similar' to return averaged statistics across similar routes. Note: 'similar' mode is only available for port-to-port (P2P) route types; all other route types support 'exact' mode only.",
            "schema": {
              "type": "string",
              "enum": [
                "exact",
                "similar"
              ],
              "default": "similar",
              "example": "similar"
            }
          },
          {
            "name": "shipment_priority",
            "in": "query",
            "required": false,
            "description": "Filter by shipment priority",
            "schema": {
              "type": "string",
              "default": "ALL",
              "example": "ALL"
            }
          },
          {
            "name": "rate_type",
            "in": "query",
            "required": false,
            "description": "Type of rate to filter by. Requires special permissions for CONTRACT and ALL types. LCL supports SPOT only",
            "schema": {
              "type": "string",
              "enum": [
                "SPOT",
                "CONTRACT",
                "ALL"
              ],
              "default": "SPOT",
              "example": "SPOT"
            }
          },
          {
            "name": "include_change",
            "in": "query",
            "required": false,
            "description": "Include change metrics (volatility and change percentage) in the response",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": true
            }
          },
          {
            "name": "volume_band",
            "in": "query",
            "required": false,
            "description": "LCL only. Shipment size band in CBM: all (whole lane), lt1 (under 1 CBM), 1-3, 3-10, 10plus. Ignored for FCL and Air. lt1 returns data only with price_basis=total.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "lt1",
                "1-3",
                "3-10",
                "10plus"
              ],
              "default": "all",
              "example": "all"
            }
          },
          {
            "name": "price_basis",
            "in": "query",
            "required": false,
            "description": "LCL only. per_cbm returns USD per cubic metre; total returns USD for the whole shipment. Prices are all-in. Ignored for FCL and Air.",
            "schema": {
              "type": "string",
              "enum": [
                "per_cbm",
                "total"
              ],
              "default": "per_cbm",
              "example": "per_cbm"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "Single date parameter (alternative to from_date/to_date). Sets both from_date and to_date to this value",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2024-02-01"
            }
          },
          {
            "name": "tradelane",
            "in": "query",
            "required": false,
            "description": "Alias for tradelanes_type parameter",
            "schema": {
              "type": "string",
              "enum": [
                "air",
                "ship",
                "lcl"
              ]
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": [],
            "SecretKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceStatsResponse"
                },
                "examples": {
                  "standard": {
                    "summary": "Standard response example",
                    "value": {
                      "license": "https://www.freightos.com/freightos-data-terms-conditions/",
                      "currency": "US",
                      "data": [
                        {
                          "date": "2024-02-01",
                          "route_name": "CNSHA||USLAX||FCL||40'",
                          "confidence_level": "High",
                          "minimum_price": 1200.5,
                          "percentile_10_price": 1250,
                          "percentile_20_price": 1300,
                          "median_price": 1450,
                          "percentile_80_price": 1600,
                          "percentile_90_price": 1700,
                          "maximum_price": 1800,
                          "average_price": 1455.5,
                          "rate_quality": 150,
                          "volatility": "5.2%",
                          "change": "-8.25%"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error or quota exceeded. Common errors include: missing required parameters, invalid date format, route quota exceeded, or missing permissions for contract rates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "quota_exceeded": {
                    "summary": "Route quota exceeded",
                    "value": {
                      "error": "You are allowed to query up to 10 unique routes. Your request contains 15 unique routes.",
                      "dev_message": "Route quota validation failed"
                    }
                  },
                  "no_quota": {
                    "summary": "No quota available",
                    "value": {
                      "error": "You are not allowed to query any routes with the current subscription",
                      "dev_message": "Subscription has 0 allowed_unique_routes"
                    }
                  },
                  "missing_params": {
                    "summary": "Missing required parameters",
                    "value": {
                      "error": "Please provide origin, destination, mode, load to get data for a specific route"
                    }
                  },
                  "contract_rate_permission": {
                    "summary": "Contract rate permission denied",
                    "value": {
                      "error": "User does not have permissions to access contract rates"
                    }
                  },
                  "lcl_permission": {
                    "summary": "LCL permission denied",
                    "value": {
                      "error": "User does not have permissions to access LCL rates",
                      "details": null,
                      "dev_message": null
                    }
                  },
                  "lcl_spot_only": {
                    "summary": "LCL with CONTRACT or ALL rate type",
                    "value": {
                      "error": "LCL supports SPOT rates only",
                      "details": "rate_type must be SPOT for LCL",
                      "dev_message": null
                    }
                  },
                  "lcl_p2p_only": {
                    "summary": "LCL with a non-P2P route type",
                    "value": {
                      "error": "LCL supports P2P routes only",
                      "details": "route_type must be P2P (port to port) for LCL",
                      "dev_message": null
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "apikey",
        "description": "Your API key (recommended)"
      },
      "SecretKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "secret-key",
        "description": "Your API secret key (required)"
      }
    },
    "schemas": {
      "PriceStatsDataItem": {
        "type": "object",
        "description": "Price statistics for a single date. For LCL, prices are USD per CBM by default, or the shipment total with price_basis=total",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date of the price statistics",
            "example": "2024-02-01"
          },
          "route_name": {
            "type": "string",
            "description": "Route identifier in format origin||destination||mode||loadTag. LCL routes use origin||destination||LCL",
            "example": "CNSHA||USLAX||FCL||40'"
          },
          "confidence_level": {
            "type": "string",
            "enum": [
              "Low",
              "Medium",
              "High",
              "Very High"
            ],
            "description": "Data quality indicator based on number of data points",
            "example": "High"
          },
          "minimum_price": {
            "type": "number",
            "format": "float",
            "description": "Lowest rate in USD",
            "example": 1200.5
          },
          "percentile_10_price": {
            "type": "number",
            "format": "float",
            "description": "10th percentile rate in USD",
            "example": 1250
          },
          "percentile_20_price": {
            "type": "number",
            "format": "float",
            "description": "20th percentile rate in USD",
            "example": 1300
          },
          "median_price": {
            "type": "number",
            "format": "float",
            "description": "50th percentile (median) rate in USD",
            "example": 1450
          },
          "percentile_80_price": {
            "type": "number",
            "format": "float",
            "description": "80th percentile rate in USD",
            "example": 1600
          },
          "percentile_90_price": {
            "type": "number",
            "format": "float",
            "description": "90th percentile rate in USD",
            "example": 1700
          },
          "maximum_price": {
            "type": "number",
            "format": "float",
            "description": "Highest rate in USD",
            "example": 1800
          },
          "average_price": {
            "type": "number",
            "format": "float",
            "description": "Average rate in USD",
            "example": 1455.5
          },
          "rate_quality": {
            "type": "number",
            "format": "float",
            "description": "Number of rates used to calculate statistics",
            "example": 150
          },
          "volatility": {
            "type": "string",
            "description": "Price volatility percentage (included when include_change=true)",
            "example": "5.2%"
          },
          "change": {
            "type": "string",
            "description": "Price change percentage (included when include_change=true)",
            "example": "-8.25%"
          }
        }
      },
      "StandardResponse": {
        "type": "object",
        "description": "Standard response format (array of price statistics)",
        "properties": {
          "license": {
            "type": "string",
            "description": "License agreement URL",
            "example": "https://www.freightos.com/freightos-data-terms-conditions/"
          },
          "currency": {
            "type": "string",
            "description": "Currency of the rates",
            "default": "USD",
            "example": "USD"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceStatsDataItem"
            },
            "description": "Array of price statistics objects"
          }
        }
      },
      "PriceStatsResponse": {
        "$ref": "#/components/schemas/StandardResponse",
        "description": "Price statistics response."
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response structure",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message for end users",
            "example": "You are allowed to query up to 10 unique routes. Your request contains 15 unique routes."
          },
          "dev_message": {
            "type": "string",
            "description": "Detailed error message for developers (optional)",
            "example": "Route quota exceeded for user"
          }
        }
      }
    }
  }
}
```