swagger: '2.0'
info:
  version: 0.1.1
  title: paccurate.io
paths:
  /:
    post:
      description: |
        a pure-JSON endpoint for packing requests.
      produces:
      - application/json
      consumes:
      - application/json
      parameters:
      - name: pack
        in: body
        description: complete set of items, boxes, and parameters to pack.
        schema:
          $ref: "#/definitions/Pack"
      responses:
        200:
          description: Successful pack.
          schema:
            type: object
            title: PackResponse
            properties:
              boxes:
                description: List of boxes, packed, with their contained items.
                type: array
                items:
                  $ref: '#/definitions/Box'
              title:
                description: title of packing result, when applicable.
                type: string
              built:
                description: build timestamp of engine.
                type: string
              version:
                description: version of engine
                type: string
              lenBoxes:
                description: cardinality of all packed boxes
                type: integer
              lenItems:
                description: cardinality of all items
                type: integer
              lenLeftovers:
                description: cardinality of items unabled to be packed
                type: integer
              totalCost:
                description: total estimated cost of all packed boxes, when applicable, in cents.
                type: integer
              packTime:
                description: seconds spent in packing
                type: number
              renderTime:
                description: seconds spent in rendering and placement instruction creation of packing solution
                type: number
              totalTime:
                description: seconds spent generating response, total.
                type: number
              leftovers:
                description: items left over that could not be packed into any available boxes.
                type: array
                items:
                  $ref: '#/definitions/Item'
              scripts:
                description: additional javascripts for any image loading.
                type: string
              styles:
                description: additional styles for pack images
                type: string
              svgs:
                description: all box SVG images
                type: string
        400:
          description: Bad request. Malformed or some other problem occurred processing the request.
          schema:
            $ref: "#/definitions/Error"
        422:
          description: Invalid input. The request was well-formed, but the parameters were contradictory, invalid, or otherwise somehow unable to be processed. More information will be contained in the error details.
          schema: 
            $ref: "#/definitions/Error"
        429:
          description: Rate limited. Without an API key, only 10 unique requests are allowed per day for testing or demonstration purposes. Note that a randomized pack repeated is only a single unique request.
          schema: 
            $ref: "#/definitions/Error"
        500:
          description: Unexpected error.
          schema: 
            $ref: "#/definitions/Error"
definitions:
  Error:
    type: object
    required:
    - message
    - code
    properties:
      message:
        type: string
      details:
        type: string
      code:
        type: integer
        minimum: 100
        maximum: 600
  Pack:
    type: object
    properties:
        key:
          description: issued API key.
          type: string
        layFlat:
          description: aligns all items laying flat. If possible, it may create a "brick-laying" pattern to increase stability.
          type: boolean
          default: false
        interlock:
          description: alternates layFlat orientation by layer, so as to create an interlocked placement pattern and improve item stability.
          type: boolean
          default: false
        corners:
          type: boolean
          description: only pack items at valid corner points of other items (optimal)
          default: true
        itemSets:
          description: item set definitions if not creating random items.
          type: array
          items:
            $ref: "#/definitions/ItemSet"
        boxTypes:
          description: box type definitions for packing, will override boxTypeSets defined.
          type: array
          items:
            $ref: "#/definitions/BoxType"
        usableSpace:
          description: estimate of percentage space in boxes that is usable, i.e., not packing material.
          minimum: 0
          maximum: 1
          default: 0.50
          type: number
        boxTypeSets:
          description: predefined box types to be used, separated by commas. Will be overridden by boxTypes. Acceptable values are <ul><li>"fedex"--FedEx OneRate</li><li>"usps"--USPS Priority Flat Rate</li><li>"pallet"--full-, half-, and quarter-sized 48"x40" pallets.
          type: array
          items:
            $ref: "#/definitions/BoxTypeSet"
        eye:
          description: The x,y,z coordinates of the virtual eye looking at the package for visualization purposes. Default is isometric, "1,1,1". To generate a side view, one could use "0.001,1.0,0.001".
          allOf:
          - $ref: "#/definitions/Point"
        packOrigin:
          description: the x,y,z coordinates of an optional packing origin. A packing origin is used to create more balanced packing for situations where load needs to be considered. E.g., for a 40"x48" pallet, a packOrigin representing the middle of the pallet, "0,20,24", would cause placement to minimize the distance of the packed items from the center of the pallet.
          allOf:
          - $ref: "#/definitions/Point"
        zone:
          description: <b>[experimental]</b> the shipping zone in order to use basic zone-based price optimization.
          type: integer
          minimum: 1
        rules:
          type: array
          description: Array of packing rules.
          items:
            $ref: "#/definitions/Rule"
        random:
          description: create random items
          type: boolean
          default: false
        n:
          description: number of random items to generate and the quantity of each if "random" is set to true. a value of 5 would create 5 different items with a quantity of 5 each, making the total item quantity equal to n&sup2;
          type: integer
          default: 5
        randomMaxDimension:
          description: maximum item dimension along a single axis for randomly generated items.
          type: integer
          default: 10
        randomMaxWeight:
          description: maximum item weight for randomly generated items.
          type: integer
          default: 10
        seed:
          type: boolean
          description: if random is selected, seed the random number generator to deterministically generate random items to pack.
          default: true
        imgSize:
          description: width of rendered SVGs in pixels.
          type: integer
          default: 400
        template:
          description: template name for markup generation.
          type: string
          enum:
          - demo.tmpl
          - shipapp.tmpl
          - boat.tmpl
        includeScripts:
          description: "include inline javascripts and styles for base template"
          type: boolean
          default: true
        includeImages:
          description: "include inline images, default is always on"
          type: boolean
          default: true
        coordOrder:
          description: If placementStyle is set to "default", coordOrder sets the placement priority of axes ascendingly. "0,1,2" would search for placement points along the Z(length,"2"), then Y(width,"1"), and finally X(height"0"). Keep in mind that in the default rendering the "up" direction is X and the other axes follow the right-hand rule.
          
           This is useful for different packing methods. E.g., Utilizing "2,0,1" would pack a shipping container first in the Y(width) direction, then in the X(height) direction, and finally in the Z(length) direction, replication a floor-to-ceiling, front-to-back loading method.
          type: array
          items:
            type: integer
          maxLength: 3
          minLength: 3
        cohortPacking:
          description: if selected, will ensure that all like items will be packed together, in no more than [cohortMax] different groups within a single container.
          type: boolean
          default: false
        cohortMax:
          description: the maximum number of contiguous cohorts for a given item type within a single container. E.g., if you pack 40 chairs in a single container, a cohortMax of 2 could yield one (all 40 chairs in a single block if space is availabe) or two (say, 25 chairs in one corner and 15 in the other) contiguous cohorts.
          default: 2
          type: integer
        allowableOverhang:
          description: The amount an item can overhang lower items that it is placed upon. The units are whatever units the box and item dimensions are given in. By convention, inches.
          default: -1.0
          type: number
        placementStyle:
          description: How to place items. 'default' will defer to coordOrder, 'corner' minimizes distance to rear, bottom corner, 'wedge' minimizes distance to middle of bottom, back edge, 'mound' minimizes distance to center of carton bottom.
          type: string
          default: default
          enum:
          - default
          - corner
          - wedge
          - mound
          - orb
        sequenceSort:
          type: boolean
          description: Whether or not the items should be initially sorted by their sequence value instead of their volume. This is not always useful, as the default "biggest-first" volume sort is very effective for items, and constraining by maxSequenceDistance is applied regardless of this field. That said, for doing custom pre-sorts such as weight-based instead of volume based, this value should be set to true.
          default: false
        sequenceHeatMap:
          type: boolean
          description: Colorize items solely by their sequence value, light when sequence is high, dark when it is low. Useful for indicating item bin location, weight, or other sequence property that may not be apparent from the default visualization.
          default: false
        maxSequenceDistance:
          type: integer
          description: This is the maximum distance allowable between two sequence values of items packed in a common box. E.g., "Distance" for an item sequence composed of aisle/bin combinations of "0401" and "1228" has a sequence distance of \|1228 - 401\| = 827
  BoxProperties:
    type: object
    properties:
      name:
        type: string
        description: name for the type of box.
      price:
        type: integer
        description: Fixed price of the container, in whole units of currency, default USD cents. This can represent the cost of a flat rate carton, the cost of the actual carton materials, or it can include any other flat fees that may need to be added on a <i>per-carton</i> basis, such as handling, accessorial surchages, oversize fees, etc. This value is <i>added</i> to any rate table rates defined for the carton.
        minimum: 0
      weightTare:
        type: number
        description: weight of the container when empty or otherwise unladen, i.e., of the box itself.
        minimum: 0
        default: 0
      weightMax:
        type: number
        description: maximum allowable gross weight for the box, i.e., all packed item weights plus the weightTare.
        minimum: 0
      dimensions: 
        description: the [height,length,width] of the box.
        allOf:
        - $ref: "#/definitions/Point"
      rateTable:
        description: An optional rate table definition for improved carton selection and pricing optimization. Defaults are included using retail rates for FedEx and UPS if carrier and service is provided, but optimization can be improved with more data passed in a carton's specific rate table. Methods are <ol><li>Provide carrier, service, and zone.</li><li>Provide all acceptable weights and prices to use for the carton, similar to actual carrier rate tables.</li><li>Provide the coefficients required for a simple linear weight-dependent pricing model.</li></ol>
        allOf:
        - $ref: "#/definitions/RateTable"
    required:
    - weightMax
    - dimensions
  BoxType:
    description: box types to be used for packing.
    allOf:
    - $ref: "#/definitions/BoxProperties"
  BoxTypeSet:
    description: "box type sets for useful defaults."
    type: string
    enum:
    - usps
    - fedex
    - pallet
    - customer
  Box:
    description: A completed, packed box.
    allOf:
    - $ref: "#/definitions/BoxProperties"
    - type: object
      properties:
        id: 
          type: integer
        items: 
          title: items
          type: array
          items:
            $ref: "#/definitions/Item"
        volumeMax:
          type: number
          description: total volume of the box.
          minimum: 0
        volumeUsed:
          type: number
          description: utilized volume of the box.
          minimum: 0
        volumeRemaining:
          type: number
          description: remaining volume of the box.
          minimum: 0
        volumeUtilization:
          type: number
          minimum: 0
          maximum: 1
          description: percentage of volume utilized by packed items.
        weightUsed: 
          type: number
          description: utilized weight of the box.
          minimum: 0
        weightNet:
          type: number
          description: total weight of box's contents, not including the box's empty (tare) weight.
          minimum: 0
        weightRemaining:
          type: number
          description: remaining weight of the box.
          minimum: 0
        weightUtilization:
          type: number
          description: percentage of weight utilized by packed items.
          minimum: 0
          maximum: 1
        dimensionalWeight:
          type: number
          description: the calculated dimensional weight of this box, if applicable.
        dimensionalWeightUsed:
          type: boolean
          description: whether or not dimensional weight was used for this box.
        svg:
          type: string
          description: raw svg of visualization.
  ItemProperties:
    type: object
    description: "general properties of an item"
    properties:
      refId:
        type: integer
        description: item type reference identifier passed backed from request.
      name:
        type: string
        description: name or description of item for your reference.
      color:
        type: string
        description: designated color name for the item in pack visualizations.
      weight:
        type: number
        description: weight of this single packed item.
      sequence:
        type: string
        description: A sequence value for the item. This is intended for aisle-bin locations, e.g., aisle 11 bin 20 can be '1120'. Combined with maxSequenceDistance, you can restrict cartons to only have contents from within a certain range. This is very helpful for cartonization when picking efficiency is paramount. Sequence can also be used to pre-sort items for efficient packing on any arbitrary number, such as item weight instead of the default item volume.
      dimensions: 
        description: the length, width, and height of the item.
        allOf:
        - $ref: "#/definitions/Point"
    required:
    - weight
    - dimensions
  Item:
    description: a specific, packed item.
    allOf: 
    - $ref: "#/definitions/ItemProperties"
    - type: object
      properties:
        index:
          type: integer
          description: the sequence at which the item was packed.
        message:
          type: string
          description: any relevant information or warnings about the packing of the item.
        origin:
          description: the [x,y,z] placement point of the back-bottom corner of the item.
          allOf:
          - $ref: "#/definitions/Point"
  ItemSet:
    description: set of items sharing a common type.
    allOf:
    - $ref: "#/definitions/ItemProperties"
    - type: object
      properties:
        quantity:
          type: integer
          description: "quantity of items of this type in this item set"
  Rule:
    description: "Rule definition for packing constraints."
    type: object
    properties:
      itemRefId:
        type: integer
        description: reference ID for the item the rule applies to.
      targetItemRefIds:
        description: target item reference IDs that the rule applies to.
        type: array
        items:
          type: integer
      operation:
        type: string
        enum: 
        - exclude
        - exclude-all
        - pack-as-is
        - irregular
        - lock-orientation
        description: |
          Rule type for this definition. Valid operation values include
          <ul>
            <li>
              <h3>exclude</h3>
              <p><b>itemRefId</b> is excluded from being packed in the same carton with all <b>targetItemRefIds</b></p>
              <pre>{
            "operation": "exclude",
            "itemRefId": 0,
            "targetItemRefIds": [1,2]
          }</pre>


            </li>
            <li>
              <h3>exclude-all</h3>
              <p><b>itemRefId</b> is excluded from being packed in the same carton with all items without its refId</p>
              <pre>{
            "operation": "exclude-all",
            "itemRefId": 0
          }</pre>


            </li>
            <li>
              <h3>pack-as-is</h3>
              <p>Each individual item with <b>itemRefId</b> is packed in a carton matching its exact dimensions, i.e., it is assumed the item is ship-ready and bypasses being placed in a box. If you have an item quantity of 6, it will place the items in 6 boxes.</p>
              <pre>{
            "operation": "pack-as-is",
            "itemRefId": 0
          }</pre>


            </li>
            <li>
              <h3>irregular</h3>
              <p>There are two types of irregular item packings right now, "nesting" and "roll".</p>
              <ul>
                <li>
                  <h4>"nesting"</h4> 
                  <p>"nesting" is where the first item has full dimensions, and subsequent items have diminished dimensions. E.g.,
                  a flower pot may have dimensions of 6" x 6" x 6", but additional flower pots can nest in the first pot, and have
                  effective dimensions of 1" x 6" x 6". These cases are almost always have a single direction that nesting can occur
                  in--two pots must both be right-side up and one on top of the other if they are to nest--so the rule options must
                  reflect these restrictions.<p/>
                  <p><b>"options"</b> contents:</p>
                  <table>
                    <tr><th>key</th><th>value</th><th>description</th></tr>
                    <tr><td>type</td><td>"nesting"</td></tr>
                    <tr><td>additionalDimensionsX</td><td><i>number</i></td></tr>
                    <tr><td>additionalDimensionsY</td><td><i>number</i></td></tr>
                    <tr><td>additionalDimensionsZ</td><td><i>number</i></td></tr>
                    <tr><td>nestingOrientation</td><td>0, 1, or 2</td><td>axis index of direction of stacking (0 for vertical/X/"dinner plates", 1 for shorter-horizontal/Y/"shopping carts", 2 for long-horizontal/Z/"newsstand magazines")</td></tr>
                    <tr><td>nestingLimit</td><td><i>integer</i></td><td>total number of nested items allowed in a single "stack"</td></tr>
                  </table>
                  <pre>{
            "operation": "irregular",
            "itemRefId": 0,
            "options": {
              "type": "nesting",
              "additionalDimensionsX": 1.0,
              "additionalDimensionsY": 6.0,
              "additionalDimensionsZ": 6.0,
              "nestingOrientation": 0,
              "nestingLimit": 5
            }
          }</pre>
                </li>
                <li>
                  <h4>"roll"</h4> 
                  <p>A rolled irregular item is simply where the item dimensions X, Y, and Z, represent the thickness, width, and total
                  length of a material meant to be rolled up (possibly on a spool, dowel, etc.) and shipped as such. Marked this way, the bounding box
                  of the roll cylinder will be used as its shipping dimensions. E.g., a roll has a width 60 inches and a diameter of 12 inches,
                  it will be shipped as if it were a 12" x 12" x 60" item. Rolls can have a maximum allowable diameter, and any rolls that must be
                  split will have their weights calculated on a pro-rated basis of the total length and weight in the item contents.<p/>
                  <p><b>"options"</b> contents:</p>
                  <table>
                    <tr><th>key</th><th>value</th><th>description</th></tr>
                    <tr><td>type</td><td>"roll"</td></tr>
                    <tr><td>innerDiameter</td><td><i>number</i></td><td>the inner diameter of any dowel or tube used that serves as the initial diameter of the roll.</td></tr>
                    <tr><td>spoolWeight</td><td><i>number</i></td><td>the additional weight of each spool or dowel if applicable</td></tr>
                    <tr><td>maxDiameter</td><td><i>number</i></td><td>the maximum acceptable diameter of a resultant roll.</td></tr>
                    <tr><td>maxWeight</td><td><i>number</i></td><td>the maximum acceptable weight of a resultant roll.</td></tr>
                    <tr><td>minRollLength</td><td><i>number</i></td><td>the minimum length above which rolling will occur. E.g., if less than 12" remain, ship it flat without rolling.</td></tr>
                  </table>
                <pre>{
            "operation": "irregular",
            "itemRefId": 0,
            "options": {
              "type": "roll",
              "innerDiameter": 1.0,
              "spoolWeight": 1.0,
              "maxDiameter": 8.0,
              "maxWeight": 150,
              "minRollLength": 12
            }
          }</pre>
                </li>
              </ul>
            </li>
            <li>
              <h3>lock-orientation</h3>
              <p><b>itemRefId</b> is locked from rotation of its original dimensions, with axes of rotation excepted by <b>freeAxes</b></p>
              <p><b>"options"</b> contents:</p>
                 <table>
                   <tr><th>key</th><th>value</th><th>description</th></tr>
                   <tr><td>freeAxes</td><td>array</td><td>Array of axis indices to be allowed rotational freedom. E.g., [0] for only yaw allowed, [0,1] for yaw and roll.</td></tr>
                 </table>
              <pre>{
            "operation": "lock-orientation",
            "itemRefId": 0,
            "options": {
              "freeAxes": [0,1]
            }
          }</pre>


            </li>
          </ul>
      options: 
        type: object
        description: additional key-value options to pass for rule based on operation type.
      parameters:
        type: array
        description: array of supplementary parameters to pass for rule, mostly deprecated. may be different from options.
        items:
          type: string
    required:
    - operation
  Point:
    description: "vector definition used for points, dimensions, and other spacial purposes."
    type: object
    title: Point
    properties:
      x:
        description: x coordinate, used as height.
        type: number
        default: 0.0
      y:
        description: y coordinate, used as width.
        type: number
        default: 0.0
      z: 
        description: z coordinate, used as length.
        type: number
        default: 0.0
  RateTable:
    type: object
    title: RateTable
    properties:
      carrier:
        type: string
        description: "carrier name for rate table to use"
      service:
        type: string
        description: "service name for rate table to use"
      zone:
        type: string
        description: "zone of rate table to use"
      rates:
        description: list of prices to use for the weight that corresponds to its index, e.g., [10, 15, 20] would be $10 for 1lb, $15 for 2lbs, $20 for 3lbs.
        type: array
        items:
          type: number
      weights:
        description: list of weights to use for the rate that corresponds to its index, e.g., [1, 2, 3] would mean 1lb for the minimum rate ($10), 2lbs for the second rate ($15), and 3lbs for the highest rate ($20). Note that if the highest value from this list is less than the weightMax of the carton, all carton weights exceeding the maximum from this list up to the carton weightMax will not pro-rate but will be estimated at the maximum value in the rate table.
        type: array
        items:
          type: number
      priceIncreaseRate:
        description: Instead of providing the full rate table, you can list a carton "basePrice" and a carton "priceIncreaseRate". These two values will be used in a simple linear model to guess carton price, i.e., <pre>cartonPrice = priceIncreaseRate * cartonWeight + basePrice</pre> Oftentimes, this will be enough to get accurate carton selections without needing to send complete customer-based rates. It's worth considering, as the prices are only estimates to be used in carton selection, with final rating of cartons happening outside of paccurate. This is the predicted rate of increase for a weight-based pricing model. The simplest way to find a servicable value is to take <pre>priceIncreaseRate = (maximumPrice - minimumPrice)/(maximumWeight - minimumWeight)</pre> In the example above, this would yield <pre>priceIncreaseRate = ($20-$10)/(3lbs-1lb)<br/>priceIncreaseRate = $10/2lbs<br/>priceIncreaseRate = $5/lb</pre>
        type: number
      basePrice:
        description: The basePrice can be found by estimating the lowest weight-based rate available for a given service, in the example above, solving for basePrice for a $10, 1lb package with the already-solved priceIncreaseRate yields <pre>$10 = $5/lb * 1lb + basePrice<br/>$10 = $5 + basePrice<br/>basePrice = $5</pre>
        type: number 
      dimFactor:
        type: number
        description: This is the Dimensional Weight divisor. It is given in units of volume per unit weight, e.g., the standard of "139" represents 139 cubic inches per pound, and is used to convert the total volume of a carton into a functional minimum weight to be used when rating the carton. E.g., a carton with dimensions 10" x 10" x 13.9" would yield a volume of 1390 cubic inches. This yields <pre>cartonEffectiveMinimumWeight = 1390in&sup3; / 139in&sup3;/lb<br/>cartonEffectiveMinimumWeight = 10lbs</pre>
