Optimal Ship API
Document Scope
This document contains information related to the optimal ship quote tool API
Audience
This document is for anyone that ships internationally, it provides a way to be able to receive rates on their web page. These rates are provided by optimal ship. This document defines request parameter as well as examples of how to use the API.
Features
- Country to Country Shipping
- Remote Area Service Determination
- Chargeable weight calculation from shipment weight and piece dimensions/weight
- Correct handling of Over Size and Over Weight packages
- Response includes
- Base Charge
- Total Charge
- Fee Summary
- Chargeable Weight
- Uses KG or LB based on country origin
- XML or JSON response format
Limitations
- All Dimensions are in Inches
Query Parameters
| Parameter | Required | Default | Example | Notes |
|---|---|---|---|---|
| acc | REQUIRED | 111222333 | Export / Import number for rates | |
| dir | OPTIONAL | IB | Direction of shipment (IB/OB/3C) | |
| gtw | OPTIONAL | US | CA | DHL Country Code for shipping gateway (Country of shipping origin) |
| zip | OPTIONAL | 34405 | Zipcode of shipping origin (Florida Only) | |
| dst | REQUIRED | AL | DHL Country Code for shipping destination | |
| cty | OPTIONAL | TROPOJE | Destination city. Used for Remote Area Service lookup. Only necessary for countries not using postal codes. Can be provided for every request. | |
| pst | OPTIONAL | 13460 | Destination postal code. Used for Remote Area Service lookup. Only necessary for countries using postal codes. Can be provided for every request. | |
| wgt | CONDITIONAL | 5.2 | Shipment weight (LBS if gtw is US or PR) (KGS if gtw is anything else) LBS will be rounded to a whole weight. KGS will be rounded to nearest half KG. May be omitted if piece information is entered | |
| pcs | CONDITIONAL | 10|6|8|4 | Piece dimensions (Length, Width, Height, Weight) provided as four pipe separated values. May be omitted if shipment weight is provided. Decimal values for all dimensions are allowed. Assumed to be LBS (if gtw is US or PR) KGS for all other countries.Length Width and Height are in Inches. Multiple pieces, no limit, are provided as semi-colon separated values. E.g. 10|6|8|4;12|8|10|6;8|8|4|3 Will select the higher of either total weight or dimensional weight. dimensional weight is calculated by (Length * Width * Height) / 139 | |
| prd | REQUIRED | P | 'P' for Express packages, 'X' for Express Documents (cannot use pcs dimensions, wgt must be under .5 lbs, shipment must be from the US ) 'D' for Documents over .5 lbs If the total weight is over 5 lbs it will be set to 'P' | |
| svp | OPTIONAL | 0 | 250 | Shipment insurance amount (Shipment Value Protection) |
| ddp | OPTIONAL | N | N | Flag requesting Delivery Duty Paid service |
| nds | OPTIONAL | N | N | Flag requesting Neutral Delivery Service |
| fsc | OPTIONAL | Varies | 12.5 | Fuel Surcharge Rate. Currently hard coded into rating service, but can be overridden in request URL. Provide value as 12.5 for 12.5%.Do not provide a factor such as 0.125 instead. |
| schgtype | OPTIONAL | FLT | Shipper surcharge type: FLT (flat) or PCT (percentage). Percentage follows same rule as fsc parameter( 10.5 = 10.5%). Use 12.5 and not 0.125 for 12.5%. Needs schgbort and schgamnt in order to work | |
| schgbort | OPTIONAL | B | Shipper surcharge target: B (base) or T (total) | |
| schgamnt | OPTIONAL | 10 | Shipper surcharge amount: amount to add | |
| dg | OPTIONAL | Y | Send Y if sending Dangerous Goods | |
| res | OPTIONAL | Y | Send Y if shipment is a Residential Drop Off | |
| prep | OPTIONAL | Y | Send Y for Shipping Prep Services | |
| json | OPTIONAL | Y | Tells whether you want the response in JSON or XML. Y = JSON, N = XML, Default is XML |
JSON Responses
Responses in JSON format
URL Example: www.optimalship.com/rates/rates.php?
acc=111222333
&dst=AL
&pcs=10|8|6|8
&prd=P
>w=US
&json=Y
www.optimalship.com/rates/rates.php? acc= 111222333 & dst= AL & pcs= 10|8|6|8;12|8|4|5.3 & prd= P & gtw= US & svp= 1500 & cty= TROPOJE & &json= Y
({
"ratingResponse":
{
"baseRate":"106.17",
"totalCharge":"106.17"
},
"fees":
[
["Fuel Surcharge","0.00"]
],
"info":
{
"chargeableWeight":8,
"countryZone":"E",
"rateServiceVersion":"0.8.120320"
}
})
www.optimalship.com/rates/rates.php? acc= 111222333 & dst= AL & pcs= 10|8|6|8;12|8|4|5.3 & prd= P & gtw= US & svp= 1500 & cty= TROPOJE & &json= Y
({
"ratingResponse":
{
"baseRate":"154.20",
"totalCharge":"198.45"
},
"fees":
[
["Remote Area Service","30.00"],
["Shipment Value Protection","14.25"],
["Fuel Surcharge","0.00"]
],
"info":
{
"chargeableWeight":"13.5",
"countryZone":"E",
"rateServiceVersion":"0.8.120320"
}
})
Error Responses
({
"errorResponse":
{
"message":"Error within piece dimensions.",
"rateServiceVersion":"0.8.120320"
}
})
| Error Message | Direction |
|---|---|
| Destination country not supported | Destination country not recognized |
| Error within piece dimensions | Piece information has too many or too few dimensions. |
| Letter weight exceeds .5 maximum | Letter service is .5 LBS or more. |
| Letter rate requires use of envelope | Piece information was supplied for product code X |
| International Shipping Only | gtw and dst = US |
| Invalid Value | Unable to find a specified value in the database. (check to make sure your export/import number are correct) |
Ajax Example using jQuery
$.ajax({
type: 'GET',
data: {"acc" : account, "gtw" : shipfrom, "dst" : shipto, "prd" : "P", "pcs" : pcsString, "svp" : insurance, "pst" : city},
url: "http://www.optimalship.com/rates/rates.php?",
dataType: 'jsonp',
success: function(data){
var text = "base rate: $" + data.ratingResponse['baseRate'] + "< br />";
text += "total charge: $" + data.ratingResponse['totalCharge'] + "< br />";
var chargeFee = '';
for(var i = 0; i < data.fees.length; i++){
var feecharge = data.fees[i][1];
var fee = data.fees[i][0];
chargeFee += fee + " : $" + feecharge + "< br />";
}
text += chargeFee;
text += "Charged Weight: " + data.info['chargeableWeight'];
if(shipfrom == 'US' || shipfrom == 'PR'){
text += ' LBS';
}else{
text += ' KGS';
}
$('#price').html(text);
}
});
XML Example
URL Example: www.optimalship.com/rates/rates.php?
acc=111222333
&dst=AL
&pcs=10|8|6|8
&prd=P
>w=US
&json=N
<ratingResponse>
<baseRate>111.62</baseRate>
<totalCharge>114.97</totalCharge>
<fees>
<fee charge="3.35">Fuel Surcharge</fee>
</fees>
<info>
<chargeableWeight>8</chargeableWeight>
<countryZone>E</countryZone>
<baseCountryTransitDays>3</baseCountryTransitDays>
<rateServiceVersion>0.8.120320</rateServiceVersion>
</info>
</ratingResponse>
www.optimalship.com/rates/rates.php? acc= 111222333 & dst= AL & pcs= 10|8|6|8;12|8|4|5.3 & prd= P & gtw= US & svp= 1500 & cty= TROPOJE &json= N
<ratingResponse>
<baseRate>154.98</baseRate>
<totalCharge>209.65</totalCharge>
<fees>
<fee charge="34.00">Remote Area Service</fee>
<fee charge="15.00">Shipment Value Protection</fee>
<fee charge="5.67">Fuel Surcharge</fee>
</fees>
<info>
<chargeableWeight>14</chargeableWeight>
<countryZone>E</countryZone>
<baseCountryTransitDays>3</baseCountryTransitDays>
<rateServiceVersion>0.8.120320</rateServiceVersion>
</info>
</ratingResponse>
www.optimalship.com/rates/rates.php? acc= 111222333 & dst= AL & pcs= 10|8|6|8;12|8|4|5.3 & prd= P & gtw= US & svp= 1500 & cty= TROPOJE &json= N
Error Responses
| Error Message | Direction |
|---|---|
| Destination country not supported | Destination country not recognized |
| Error within piece dimensions | Piece information has too many or too few dimensions. |
| Letter weight exceeds .5 maximum | Letter service is .5 LBS or more. |
| Letter rate requires use of envelope | Piece information was supplied for product code X |
| International Shipping Only | gtw and dst = US |
| Invalid Value | Unable to find a specified value in the database. (check to make sure your export/import number are correct) |