Want to learn more about the Box Calc service, visit the Box Calc web site.

Box Calc API Documentation

The Box Calc API is a JSON-RPC 2.0 web service located at: https://api.boxcalc.net/rpc

Clients

This is the list of ready-made clients that can take advantage of Box Calc's web services.

Methods

There are currently two methods available from this service: packing_list and shipping_options

packing_list( payload )

This service will pack up a list of items in to the best box possible, and then return a packing list.

Params

payload
Required. A hash object containing the parameters needed by this service.
api_key
Required. The API Key you received from the Box Calc web site.
box_types
Required. An array of hash objects containing the definition of each box type.
name
The name of the box type.
x
The inside measurement of one of the box dimensions.
y
The inside measurement of one of the box dimensions.
z
The inside measurement of one of the box dimensions.
weight
The weight of one of the box as it sits empty. We recommend using ounces for this, but the unit doesn't matter as long as you're consistent.
items
Required. An array of hash objects containing the definition of each item.
quantity
The number of copies of this item that need to be packed.
name
The name of the item.
x
The outside measurement of one of the item's dimensions.
y
The outside measurement of one of the item's dimensions.
z
The outside measurement of one of the item's dimensions.
weight
The weight of one of the item. It must be of the same unit type (ounces, grams, pounds) as the box types.

Example Request

{
   "method" : "packing_list",
   "params" : [
      {
      	 "api_key" : "xxx",
         "box_types" : [
            {
               "y" : 10,
               "weight" : 20,
               "name" : "A",
               "x" : 5,
               "z" : 8
            },
            {
               "y" : 6,
               "weight" : 7,
               "name" : "B",
               "x" : 4,
               "z" : 2
            }
         ],
         "items" : [
            {
               "item" : {
                  "y" : 1,
                  "weight" : 5,
                  "name" : "Banana",
                  "x" : 3,
                  "z" : 4.5
               },
               "quantity" : 5
            }
         ]
      }
   ],
   "jsonrpc" : "2.0",
   "id" : 1
}

Example Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : [
  	{
           "id" : "xxx",
	   "packing_list" : {
		"Banana" : 5
	   },
       	   "weight" : 45,
	   "name" : "A"
        }
    ]
}

shipping_options( payload )

This service will pack up a list of items in to the best box possible for each mail service you request, and then look up the postage for each of those shipping options, and return the complete list.

Params

payload
Required. A hash object containing the parameters needed by this service.
api_key
Required. The API Key you received from the Box Calc web site.
from
Required. A five digit US zip code that represents the origin of these packages.
to
Required. A five digit US zip code (if sending within the United States), or a country name (if sending outside the United States).
box_types
Required. An array of hash objects containing the definition of each box type.
name
The name of the box type.
x
The inside measurement of one of the box dimensions. This must be in inches.
y
The inside measurement of one of the box dimensions. This must be in inches.
z
The inside measurement of one of the box dimensions. This must be in inches.
weight
The weight of one of the boxes as it sits empty. This must be in ounces.
compatible_services
An array of service names that are compatible with this box type. Choose from the following list.
  • USPS Express
  • USPS Express Flat Rate Box
  • USPS Express Flat Rate Box Hold For Pickup
  • USPS Express Flat Rate Envelope
  • USPS Express Flat Rate Envelope Hold For Pickup
  • USPS Express Hold For Pickup
  • USPS Express Legal Flat Rate Envelope
  • USPS Express Legal Flat Rate Envelope Hold For Pickup
  • USPS Express Padded Flat Rate Envelope
  • USPS Express Padded Flat Rate Envelope Hold For Pickup
  • USPS First-Class Parcel
  • USPS Global Express Guaranteed
  • USPS Global Express Guaranteed Envelope
  • USPS Library
  • USPS Media
  • USPS Parcel Post
  • USPS Priority
  • USPS Priority DVD Flat Rate Box
  • USPS Priority Flat Rate Envelope
  • USPS Priority Gift Card Flat Rate Envelope
  • USPS Priority Large Flat Rate Box
  • USPS Priority Large Video Flat Rate Box
  • USPS Priority Legal Flat Rate Envelope
  • USPS Priority Medium Flat Rate Box
  • USPS Priority Padded Flat Rate Envelope
  • USPS Priority Small Flat Rate Box
  • USPS Priority Small Flat Rate Envelope
  • USPS Priority Window Flat Rate Envelope
items
Required. An array of hash objects containing the definition of each item.
quantity
The number of copies of this item that need to be packed.
name
The name of the item.
x
The outside measurement of one of the item's dimensions. This must be in inches.
y
The outside measurement of one of the item's dimensions. This must be in inches.
z
The outside measurement of one of the item's dimensions. This must be in inches.
weight
The weight of one of the item. This must be in ounces.

Example Request

{
   "method" : "packing_list",
   "params" : [
      {
      	 "api_key" : "xxx",
      	 "from" : "53716",
      	 "to" : "90210",
         "box_types" : [
            {
               "y" : 10,
               "weight" : 20,
               "name" : "A",
               "x" : 5,
               "z" : 8,
		"compatible_services" : [
		  "USPS First-Class Parcel", 
                  "USPS Parcel Post", 
                  "USPS Priority"
                ]
            },
            {
               "y" : 6,
               "weight" : 7,
               "name" : "B",
               "x" : 4,
               "z" : 2,
		"compatible_services" : [
                  "USPS Priority Medium Flat Rate Box"
                ]
            }
         ],
         "items" : [
            {
               "item" : {
                  "y" : 1,
                  "weight" : 5,
                  "name" : "Banana",
                  "x" : 3,
                  "z" : 4.5
               },
               "quantity" : 5
            }
         ]
      }
   ],
   "jsonrpc" : "2.0",
   "id" : 1
}

Example Response

{
    "jsonrpc" : "2.0",
    "id" : 1,
    "result" : {
	"USPS Parcel Post" : {
	  "number_of_parcels" : 1,
	  "weight" : 45,
	  "postage" : "11.12",
	  "parcels" : [	
  	    {
              "id" : "xxx",
              "shipping" : {
                "postage" : "11.12",
              },
	      "packing_list" : {
	        "Banana" : 5
	      },
       	      "weight" : 45,
	      "name" : "A"
            }
          ]
       },
       "USPS Priority" : {
         ...
       },
       "USPS Priority Flat Rate" : {
         ...
       }
    }
}