Batch Requests

RocketShipIt is capable of doing batch requests which sends simultaneous requests and returns the responses for all requests in a single response. This feature is useful when using programming languages without good support for concurrency (doing multiple things at once).

Any valid RocketShipIt API request can be added to a batch request.

The results will be returned in the order in which the response was received.

Each request within a batch can have an optional request_id field. This field will be returned in the batch response to help you determine which request is which.

request_id can be any string.

How long does it take?

The time it takes for a batch request to respond will be determined by the duration of the longest request within a batch.

For example:

Let's say you want to track four packages from four different shipping carriers. And, the requests look like this:

• UPS - Tracking Request - 400ms
• FedEx - Tracking Request - 1.2s
• USPS - Tracking Request - 1.0s
• DHL - Tracking Request - 1.0s

If you were to make these requests sequentially in a language like PHP you would expect a full response time of 3.6 seconds. But, using a batch request the full response time would be 1.2 seconds or the duration of the longest request.

Do I need batch requests?

If you program in a language with good support for concurrency you might not need it as you can make simultaneous RocketShipIt requests from within your code.

Batch requests can dramatically speed up workflows if you program in a language without good support for concurrency like PHP.

Batch Request properties

Field	Type	Description
batch	array: []	holds multiple requests
request_id	string: abc123	will be returned in the batch response to help you determine which request is which.
request	object: {}	holds the "normal" RocketShipIt API request

Example

{
  "batch": [
    {
      "request_id": "UPS Rates",
      "request": {
        "carrier": "UPS",
        "action": "GetAllRates",
        "params": {
          "key": "YOUR_UPS_API_KEY",
          "account_number": "YOUR_ACCOUNT_NUMBER",
          "username": "YOUR_USERNAME",
          ...
        }
      }
    },
    {
      "request_id": "FedEx Rates",
      "request": {
        "carrier": "FedEx",
        "action": "GetAllRates",
        "params": {
          "key": "YOUR_UPS_API_KEY",
          "account_number": "YOUR_ACCOUNT_NUMBER",
          "username": "YOUR_USERNAME",
          ...
        }
      }
    }
    ..
  ]
}

{
  "data": [
    {
      "request_id": "USPS Rates",
      "response": {
        "errors": null,
        "rates": [
          {
            "currency": "USD",
            "desc": "Priority Mail Express 2-Day Flat Rate Envelope Hold For Pickup",
            "est_delivery_time": "2018-12-17",
            "guaranteed": true,
            "package_type": "",
            "rate": 24.7,
            "rate_detail": null,
            "service_code": "27",
            "zone": "5"
          },
          ...
        ]
      }
    },
    {
      "request_id": "FedEx Rates",
      "response": {
        "errors": [
          {
            "code": "820",
            "description": "The destination state/province code has been changed.",
            "type": "NOTE"
          }
        ],
        "rates": [
          {
            "billing_weight": 2,
            "currency": "USD",
            "desc": "FedEx First Overnight®",
            "est_delivery_time": "2018-12-17T08:00:00-00:00",
            "package_type": "YOUR_PACKAGING",
            "rate": 100.66,
            "rate_detail": [
              {
                "amount": 6.8,
                "currency": "USD",
                "type": "FUEL"
              },
              {
                "amount": 93.86,
                "currency": "USD",
                "type": "TotalBaseCharge"
              }
            ],
            "service_code": "FIRST_OVERNIGHT"
          },
          ...
        ]
      }
    },
    {
      "request_id": "UPS Rates",
      "response": {
        "errors": null,
        "rates": [
          {
            "billing_weight": 5,
            "currency": "USD",
            "delivery_days": 1,
            "desc": "UPS Next Day Air Early AM",
            "est_delivery_time": "2018-12-15T09:30:00-00:00",
            "package_type": "",
            "rate": 136.67,
            "rate_detail": [
              {
                "amount": 16,
                "currency": "USD",
                "type": "ServiceOptionsCharges"
              },
              {
                "amount": 120.67,
                "currency": "USD",
                "type": "TransportationCharges"
              },
              {
                "amount": 0,
                "currency": "USD",
                "type": "376"
              },
              {
                "amount": 9.24,
                "currency": "USD",
                "type": "375"
              },
              {
                "amount": 111.43,
                "currency": "USD",
                "type": "BaseServiceCharge"
              }
            ],
            "saturday_delivery": true,
            "service_code": "14"
          },
          ...
        ]
      }
    }
  ],
  "meta": {
    "code": 200,
    "error_message": ""
  }
}