What we can price, and what to send¶
One section per mode: what it covers, what it needs, and a complete request. Everything here is the API's own contract, the same table the tools are built from.
An assistant reads this from freightright://reference/cargo and
freightright://reference/codes; it is here so a person can read it too.
Choosing a mode¶
| Mode | What it is | Priced instantly? |
|---|---|---|
| FCL | Full container load, by sea. You pay for whole containers | Yes |
| LCL | Less than container load, by sea. Your goods share a container | Yes |
| AIR | Air freight, airport to airport or door to door | Yes |
| LTL | Less than truckload, by road, door to door inside the US and Canada | Yes |
| FTL | A full truck, door to door in the US, Canada and Mexico | No. A quote request |
A shipment's transport_mode is a different vocabulary: SEA is the kind of move FCL and LCL price, ROA/TRK the
kind LTL and FTL price. A price check creates nothing. It never becomes a shipment.
Where it starts and ends¶
Either end is a PORT (a UN/LOCODE like CNSHA, or an airport IATA code like PVG) or a DOOR (a postal code
and a country). Choosing PORT or DOOR is what decides the service scope; there is nothing else to ask for.
Never guess a code. freightright_find_locations turns "Shanghai" into CNSHA and PVG, and says which is the
airport.
FCL: containers¶
Containers are 20GP, 40GP, 40HC (high cube) and 45HC, as a type and a quantity, at most four entries.
FCL needs direction. IMPORT when you are buying the goods, EXPORT when you are selling them.
{
"mode": "FCL",
"origin": {"type": "PORT", "code": "CNSHA"},
"destination": {"type": "PORT", "code": "USLAX"},
"direction": "IMPORT",
"containers": [{"type": "40HC", "quantity": 2}],
"commodity": "Office chairs",
"insured_value_usd": "25000.00",
"customs_brokerage": true
}
FCL is priced for general cargo only. Hazardous or temperature-controlled goods are a quote request.
LCL and AIR: piece groups, or totals¶
A piece group is any number of identical pieces with the dimensions and weight of one of them. A uniform shipment is a single group, however many pallets it is. At most 50 groups.
{
"mode": "LCL",
"origin": {"type": "PORT", "code": "CNSHA"},
"destination": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
"direction": "IMPORT",
"pieces": [
{
"quantity": 4,
"package_type": "PALLET",
"length": "120", "width": "100", "height": "150", "dimension_unit": "CM",
"unit_weight": "400", "weight_unit": "KG"
}
],
"delivery_accessorials": ["LIFTGATE"]
}
When the piece dimensions are not known, send the shipment as totals instead. Never send both:
{"totals": {"pieces": 12, "weight": "1250.5", "weight_unit": "KG", "volume": "6.2", "volume_unit": "CBM"}}
LTL: handling units, door to door¶
LTL is a DOOR at both ends, inside the US and Canada, and always pieces with dimensions, and no totals. At most 30
groups. It takes no direction, no incoterm and no insurance: for insurance on a truckload, send a quote request
and say so in the note.
{
"mode": "LTL",
"origin": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
"destination": {"type": "DOOR", "postal_code": "10001", "country_code": "US"},
"pieces": [
{
"quantity": 2,
"package_type": "PALLET",
"length": "48", "width": "40", "height": "60", "dimension_unit": "IN",
"unit_weight": "400", "weight_unit": "LB",
"freight_class": "70"
}
],
"pickup_accessorials": ["LIFTGATE"],
"delivery_accessorials": ["RESIDENTIAL", "APPOINTMENT"]
}
A freight class is not a price setting
It is classified from the density, handling, stowability and liability of the goods. Leave it out and it is estimated from the dimensions and weight you gave. Choosing a lower class to get a cheaper price is a misdeclaration. The carrier reweighs the shipment and rebills it.
FTL: a quote request¶
Full truckload has no instant price. The equipment goes in containers as container sizes, which is how the API
takes it today, and everything else about the truck goes in the note.
{
"shipment": {
"mode": "FTL",
"origin": {"type": "DOOR", "postal_code": "90021", "country_code": "US"},
"destination": {"type": "DOOR", "postal_code": "64000", "country_code": "MX"},
"containers": [{"type": "40GP", "quantity": 1}],
"hazardous": true
},
"note": "Dry van, 42,000 lb, UN1993 class 3 packing group III. Needs insurance for USD 60,000."
}
Units and precision¶
Weight KG or LB · dimensions CM or IN · volume CBM or CFT. Decimals accepted: dimensions 2 places,
weight 3, volume 4, money 2. More than that is refused rather than rounded. A rounded weight is a different
shipment.
Extras¶
| What | Where | Which modes |
|---|---|---|
| Insurance | insured_value_usd, the commercial value in USD |
FCL, LCL, AIR only |
| Customs clearance | customs_brokerage, customs_bond (SINGLE or ANNUAL, US imports) |
FCL, LCL, AIR |
| Port charges | origin_port_charges, destination_port_charges |
FCL, LCL, AIR |
| Accessorials | pickup_accessorials, delivery_accessorials: LIFTGATE, RESIDENTIAL, LIMITED_ACCESS, INSIDE, APPOINTMENT |
Needs a DOOR at that end; FCL accepts RESIDENTIAL only |
| Hazardous | hazardous |
LCL, AIR, LTL, FTL. Never FCL |
| Temperature control | temperature_controlled |
LCL, AIR, FTL. Never LTL |