RESOURCE | Nesting Template Efficiencies

POST '/dielines/{dieline_id}/nesting-template-efficiencies'

Calculate the optimal number of dielines (num_x and num_y) that can fit on a sheet for each available nesting template. This endpoint helps you determine the most efficient nesting template for your sheet dimensions before creating a nesting.

Request Parameters

dieline_id string

The unique identifier of the dieline for which to calculate efficiencies. required
Example: "di_fwe4iu3vngty"

variables object

Key-value pairs including values for sheet dimensions that define the layout for calculating efficiencies. required

unit enum	Unit required Possible values are: "mm" "in"
sheet_width length	Width of the sheet required Example: 1000.00
sheet_height length	Height of the sheet required Example: 700.00
sheet_margin_top length	Margin from the top edge of the sheet optional Example: 15.00 Default is 0.00
sheet_margin_bottom length	Margin from the bottom edge of the sheet optional Example: 20.00 Default is 0.00
sheet_margin_side length	Margin from both left and right edges of the sheet optional Example: 10.00 Default is 0.00

Response Object

Returns a "nesting_template_efficiencies" object.

Objects | nesting_template_efficiencies

Represents the calculated efficiencies (optimal num_x and num_y) for each nesting template available for the specified dieline and sheet dimensions.

type string

"nesting_template_efficiencies"

dieline_id string

The unique identifier of the dieline.
Example: "di_fwe4iu3vngty"

dieline_template_id string

Unique identifier for the dieline template that this dieline is based on.
Example: "becf-30203"

variables object

The variables used for the calculation.

{ "unit": "mm", "sheet_width": 1000.0, "sheet_height": 700.0, "sheet_margin_top": 15.0, "sheet_margin_bottom": 20.0, "sheet_margin_side": 10.0 }

efficiencies object

A map of nesting template IDs to their calculated efficiencies. Each key is a nesting template ID (e.g., "lt_xyz123abc" for LayoutTemplate or "lg_abc456def" for LayoutTemplateGroup), and each value is an object containing:

num_x integer

The optimal number of dielines that fit along the x-axis (width) of the sheet.
Example: 9

num_y integer

The optimal number of dielines that fit along the y-axis (height) of the sheet.
Example: 8

efficiency object

The material utilization efficiency - what percentage of the sheet area is used by the nested dielines.

value number	The efficiency percentage (0-100). Example: 72.0
type string	The type of value. Value: "percentage"

Note: Templates that cannot calculate efficiency (e.g., missing output formulas) will have a null value.

nesting_templates array

An array of nesting template objects, each containing all the information needed to create a nesting. This allows you to select the most efficient template and create a nesting in a single workflow without making a separate call to list nesting templates.

Each nesting template object contains:

type string	"nesting_template"
id string	The unique identifier for the nesting template. Same ID used in the efficiencies object. Example: "lt_NJYkRajK70"
nesting_template_components array	Array of component objects describing the parts of the nesting template.
variables array	Array of variable definitions required to create a nesting. Includes sheet dimension variables (sheet_width, sheet_height, margins), num_x, num_y, and any template-specific options like margin_x and margin_y.
images array	Array of image objects with SVG preview URLs for the template.
links array	HATEOAS links including the create_nesting action URL.

See the Nesting Templates documentation for full details on the nesting_template object structure.

nesting_template_components array

A unique list of all nesting template components across all templates. Each component represents a part of the dieline that can be nested (e.g., "Hard cardboard of the box").

Each component object contains:

type string	"nesting_template_component"
id string	A parameterized identifier for the component. Example: "hard-cardboard-of-the-box"
name string	Human-readable name of the component. Example: "Hard cardboard of the box"
category string	The material category of the component. Example: "hard_cardboard"

Code Examples


curl -i -X POST \
https://api.diecuttemplates.com/dielines/di_fwe4iu3vngty/nesting-template-efficiencies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_DIELINES_API_KEY_HERE>" \
  -H "Dielines-Api-Version: 1.0" \
  -d '{
  "variables": {
    "unit": "mm",
    "sheet_width": 1000.0,
    "sheet_height": 700.0,
    "sheet_margin_top": 15.0,
    "sheet_margin_bottom": 20.0,
    "sheet_margin_side": 10.0
  }
}'


require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.diecuttemplates.com/dielines/di_fwe4iu3vngty/nesting-template-efficiencies')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['Dielines-Api-Version'] = '1.0'
request['Authorization'] = 'Bearer <YOUR_DIELINES_API_KEY_HERE>'

params = {
  "variables": {
    "unit": "mm",
    "sheet_width": 1000.00,
    "sheet_height": 700.00,
    "sheet_margin_top": 15.00,
    "sheet_margin_bottom": 20.00,
    "sheet_margin_side": 10.00
  }
}

request.body = params.to_json

response = http.request(request)
puts response.read_body


$url = 'https://api.diecuttemplates.com/dielines/di_fwe4iu3vngty/nesting-template-efficiencies';
$data = [
    "variables" => [
        "unit" => "mm",
        "sheet_width" => 1000.00,
        "sheet_height" => 700.00,
        "sheet_margin_top" => 15.00,
        "sheet_margin_bottom" => 20.00,
        "sheet_margin_side" => 10.00
    ]
];

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Dielines-Api-Version: 1.0',
    'Authorization: Bearer <YOUR_DIELINES_API_KEY_HERE>'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo 'Response: ' . $response;
}

curl_close($ch);

Example Response, Status = 200

application/json

{
  "nesting_template_efficiencies": {
    "type": "nesting_template_efficiencies",
    "dieline_id": "di_fwe4iu3vngty",
    "dieline_template_id": "becf-30203",
    "variables": {
      "unit": "mm",
      "sheet_width": 1000.0,
      "sheet_height": 700.0,
      "sheet_margin_top": 15.0,
      "sheet_margin_bottom": 20.0,
      "sheet_margin_side": 10.0
    },
    "efficiencies": {
      "lt_NJYkRajK70": {
        "num_x": 9,
        "num_y": 8,
        "efficiency": {
          "value": 72.0,
          "type": "percentage"
        }
      },
      "lt_2lY22jOYP6": {
        "num_x": 7,
        "num_y": 6,
        "efficiency": {
          "value": 58.5,
          "type": "percentage"
        }
      },
      "lg_xyz789abc": null
    },
    "nesting_templates": [
      {
        "type": "nesting_template",
        "id": "lt_NJYkRajK70",
        "nesting_template_components": [
          {
            "type": "nesting_template_component",
            "id": "hard-cardboard-of-the-box",
            "name": "Hard cardboard of the box",
            "category": "hard_cardboard"
          }
        ],
        "variables": [
          {
            "type": "dieline_template_variable",
            "name": "sheet_width",
            "description": "Width of the sheet",
            "data_type": "length",
            "required": true,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_height",
            "description": "Height of the sheet",
            "data_type": "length",
            "required": true,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_top",
            "description": "Margin from the top edge of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_bottom",
            "description": "Margin from the bottom edge of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_side",
            "description": "Margin from both left and right edges of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "num_x",
            "description": "Number of dielines on the x axis.",
            "data_type": "integer",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "num_y",
            "description": "Number of dielines on the y axis",
            "data_type": "integer",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "margin_x",
            "description": "Horizontal spacing ",
            "data_type": "length",
            "required": false,
            "default_value": {
              "value": "0.0",
              "unit": "mm"
            },
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "margin_y",
            "description": "Vertical spacing",
            "data_type": "length",
            "required": false,
            "default_value": {
              "value": "0.0",
              "unit": "mm"
            },
            "children": []
          }
        ],
        "images": [
          {
            "type": "svg",
            "url": "https://example.com/nesting_template.svg"
          }
        ],
        "links": [
          {
            "rel": "create_nesting",
            "href": "/dielines/di_fwe4iu3vngty/nestings/lt_NJYkRajK70",
            "method": "POST"
          }
        ]
      },
      {
        "type": "nesting_template",
        "id": "lt_2lY22jOYP6",
        "nesting_template_components": [
          {
            "type": "nesting_template_component",
            "id": "hard-cardboard-of-the-box",
            "name": "Hard cardboard of the box",
            "category": "hard_cardboard"
          }
        ],
        "variables": [
          {
            "type": "dieline_template_variable",
            "name": "sheet_width",
            "description": "Width of the sheet",
            "data_type": "length",
            "required": true,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_height",
            "description": "Height of the sheet",
            "data_type": "length",
            "required": true,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_top",
            "description": "Margin from the top edge of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_bottom",
            "description": "Margin from the bottom edge of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "sheet_margin_side",
            "description": "Margin from both left and right edges of the sheet",
            "data_type": "length",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "num_x",
            "description": "Number of dielines on the x axis.",
            "data_type": "integer",
            "required": false,
            "children": []
          },
          {
            "type": "dieline_template_variable",
            "name": "num_y",
            "description": "Number of dielines on the y axis",
            "data_type": "integer",
            "required": false,
            "children": []
          }
        ],
        "images": [
          {
            "type": "svg",
            "url": "https://example.com/nesting_template.svg"
          }
        ],
        "links": [
          {
            "rel": "create_nesting",
            "href": "/dielines/di_fwe4iu3vngty/nestings/lt_2lY22jOYP6",
            "method": "POST"
          }
        ]
      }
    ],
    "nesting_template_components": [
      {
        "type": "nesting_template_component",
        "id": "hard-cardboard-of-the-box",
        "name": "Hard cardboard of the box",
        "category": "hard_cardboard"
      }
    ]
  }
}

Error Response Object

message string

High level error message.
Example: "Validation failed for one or more variables"
More detailed error messages can be included in the "errors" object.

errors object