JSON Responses | XML Responses | Parameters | Errors | Ajax Example | Widget Example

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


Limitations


Query Parameters

Parameter Required Default Example Notes
acc REQUIRED 111222333 Export / Import number for rates
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
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 &gtw=US &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 &gtw=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>

Error Responses

<errorResponse> <message>Error within piece dimensions.</message> <rateServiceVersion>0.8.120320</rateServiceVersion> </errorResponse>

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)

Example Web Page Using widget and ajax

Quote Test Page


DHL Country Codes

DHL Country Codes