Shipping Price Estimates


The Shipping Price Estimates resource is RESTful and accepts a JSON request body via POST. This shipping rate calculator method returns estimate results.

POST https://api.uship.com/v2/estimate

 

Authentication

OAuth 2.0 flow for this endpoint https://developer.uship.com/docs/Client_Credentials.


Supported Categories

Create estimates for the following subcategories (subcommodities). Parent Commodities will not return estimates.

Parent Commodity Subcommodity Optional Corresponding Variant(s)
Boats

PowerBoats
SailBoats
PersonalWatercraft
OtherBoats

lengthInMeters
Household Goods Furniture weightInGrams
Motorcycles & Power Sports

AllTerrainVehicles
GoCartsDuneBuggies
MotorcyclesMopeds
OtherPowerSports
Snowmobiles 

weightInGrams (should be used when known)

Year, makeName, and modelName (MotorcyclesMopeds only)

Pets Cats
Dogs 
weightInGrams
Vehicle

CarsLightTrucks
OtherVehicles

weightInGrams (should be used when known)

Year, makeName, and modelName

Increase Estimate Accuracy

Providing more accurate information will generate more accurate estimates.

Examples include

  • Matching year, make and model information
  • If no matching year, make, and model information is available for a vehicle or it is older than 1981, providing the vehicle weight will provide a more accurate estimate than only providing the category.

The highest precision estimate returns based on the most specific origin and destination location information provided which will override less precise information provided. The hierarchy is as follows where the first set of data will be processed before subsequent data.

  • latitude and longitude
  • zip codes (postalCode)
  • city (majorMunicipality) and state (stateProvince)

 

Request

{
    "route": {
        "items": [
            {
                "address": {
                    "postalCode": "78704",
                    "country": "US"
                }
            },
            {
                "address": {
                    "postalCode": "85704",
                    "country": "US"
                }
            }
        ]
    },
    "items": [
        {
            "commodity": "CarsLightTrucks",
            "year": 1998,
            "makeName": "Ford",
            "modelName": "Ranger"
        }
    ]
}

 

Price Objects

The high, low, and average price.

 

Route Object

The array order is preserved.

  • The origin address is the first item in the route items array.
  • The destination address is the last item in the route items array.

You can mix and match the precision of the origin and destination addresses. For example, you could use latitude and longitude for the origin and city, state, and country for the destination.

Latitude and longitude are required unless

  • postalCode is provided with country OR
  • majorMunicipality and stateProvince are provided with country.

Also see Route Object for detailed descriptions. (Bolded below if required)

Field Type Usage
items
Array List of address items where order denotes the origin or the destination.
address
Container Wrapper for origin or destination location data.
latitude
Decimal When provided, must be paired with longitude.
longitude
Decimal When provided, must be paired with latitude.
majorMunicipality
String If provided, must be paired with stateProvince and country when latitude/longitude or postalCodes are not provided.
stateProvince
String If provided, must be paired with majorMunicipality and country when latitude/longitude or postalCodes are not provided.
postalCode
String Both origin and destination postalCodes are required with country when latitude/longitude or majorMunicipality and stateProvince are not provided.
country
String The country is always required unless latitude and longitude are provided.

Items Array

Field Type Usage
commodity
String

The subcategory of the item to return a shipping price estimate. GET https://api.uship.com/v2/lookups/commodities returns all parent and subcategory commodities. If there is more than one of the same item, specify the unit count. For multiple commodities, the estimate is calculated individually and provided as a sum.

unitCount
Integer The number of items estimated for the category provided.
year
String If provided, a year greater than 1981 that matches with the make and model.
makeName
String Match with year and model.
modelName
String Match with year and make.
lengthInMeters
Integer Positive number or decimal that is the length of the boat in meters.
weightInGrams
Integer Positive number or decimal that is the weight of the vehicle, motor vehicle, or furniture in grams. Providing the weight will return the best accuracy. The year, make, and model can be used as an alternative if the weight is unknown.

Response

Success Status: 200 OK

Sample JSON

{
   "route": {
     "distance": {
       "kilometers": 1445.1873,
       "label": "898 mi.",
       "shortLabel": "898 mi."
     },
     "items": [
       {
         "address": {
           "majorMunicipality": "Austin",
           "postalCode": "78704",
           "stateProvince": "TX",
           "stateProvinceLabel": "Texas",
           "country": "US",
           "countryLabel": "United States",
           "latitude": 30.244144,
           "longitude": -97.76286,
           "label": "Austin, TX",
           "shortLabel": "Austin, TX"
         }
       },
       {
         "address": {
           "majorMunicipality": "Tucson",
           "postalCode": "85704",
           "stateProvince": "AZ",
           "stateProvinceLabel": "Arizona",
           "country": "US",
           "countryLabel": "United States",
           "latitude": 32.32818,
           "longitude": -110.98608,
           "label": "Tucson, AZ",
           "shortLabel": "Tucson, AZ"
         }
       }
     ]
   },
   "price": {
     "value": 688.88,
     "label": "$688.88",
     "shortLabel": "$689",
     "currencyType": {
       "value": "USD",
       "label": "US Dollar",
       "shortLabel": "US Dollar"
     }
   },
   "lowPrice": {
     "value": 459.25,
     "label": "$459.25",
     "shortLabel": "$460",
     "currencyType": {
       "value": "USD",
       "label": "US Dollar",
       "shortLabel": "US Dollar"
     }
   },
   "highPrice": {
     "value": 918.51,
     "label": "$918.51",
     "shortLabel": "$919",
     "currencyType": {
       "value": "USD",
       "label": "US Dollar",
       "shortLabel": "US Dollar"
     }
   }
 }

 

Error Messages

Error code: 400

Message Fix
Unable to geocode route.

Supply either latitude and longitude unless origin and destination postalCodes are provided with country OR majorMunicipality and stateProvince are provided with country.

Country is required.

Supply the correct country code for the origin and destination objects. OR Supply the latitude and longitude.

The content you sent was invalid. Provide a supported subcommodity in the items array.