API Key Validation

To ensure the security of requests, the API checks for a valid secret key in the headers. So basically, you need to add headers including the 'x-rapidapi-key'.

"x-rapidapi-key": "COMPLETE YOUR API KEY"

Configs Object

The “Configs” object contains several configuration parameters that affect the cutting process. All this fields are optional but highly recommended to be filled, when not filled the default value is used.

• "bar_length": : Represents the length of the stock bars to be cut in mm.
  • Type: Integer
  • Range: 1 to 20000
  • Default: 6000
• "saw_width": : Represents the width of the saw blade in mm, that is lost during the cutting process.
  • Type: Integer
  • Range: 0 to 50
  • Default: 2
• "end_cut": : It can be applied in case of having some kind of imperfection on the extreme of the raw material bars. This allows you to specify a number of mm to be discarded. The introduced value will be cut in each extreme of the bar, in case it is needed only in one extreme, the value should be divided by 2.
  • Type: Integer
  • Range: 0 to 500
  • Default: 0
• "variability": : This parameter is useful in case a fix value should be subtracted from the stock bars to compensate length variability issues. Usually, the difference from the longest and shortest bar of a set is the more conservative choice.
  • Type: Integer
  • Range: 0 to 500
  • Default: 0
• "losses": : This field is used in case some repetitive kind of loss is applied in each cut such as process variability, inexperience of the operator or perpendicularity issues.It will be applied to every cut.
  • Type: Integer
  • Range: 0 to 20
  • Default: 0
• "iterations": : Represents how many iterations the simulation should run; processing time increases exponentially with the number of iterations. For most problems a quantity of iteration of 5000 should be more than enough.
  • Type: Integer
  • Range: 0 to 50000
  • Default: 5000
• "include_zero_cuts": : Specifies whether in the answer the length with zero cuts should be represented or not.
  • Type: Boolean
  • Default: False
  1. Example of output with "include_zero_cuts":true

     
     bars": [{
     	"Bar Number": 1,
     	"Total Length Used": 6000,
     	"Bar Left Over": 1000,
     	"Cuts": [{
     		"Nominal Length": 2000,
     		"Name": "Cut B",
     		"Quantity": 0 //<-----HERE IS THE EFFECT
     	}, {
     		"Nominal Length": 5000,
     		"Name": "Cut A",
     		"Quantity": 1
     }]
     							

  2. Example of output with "include_zero_cuts":false

     
     "bars": [{
             "Bar Number": 1,
             "Total Length Used": 5000,
             "Bar Left Over": 1000,
             "Cuts": [{
                 "Nominal Length": 5000,
                 "Name": "Cut A",
                 "Quantity": 1
     }]
     							

• "data_type": : ": Specifies whether the response should be in `json` or `csv` format.
  • Allowed Values: "json", "csv"
  • Default: json

Cuts Array

The "Cuts" array contains multiple cutting instructions. Each cut entry is an array containing three elements.

Structure:

"Cuts":[
[Description, Quantity, Length]
[Description, Quantity, Length],
…
[Description, Quantity, Length]
]


1. Description: Optional string that names the cut. Up to 20 characters. It is optional but recommended)
2. Quantity: Mandatory integer that specifies the number of cuts required.
3. Length: Mandatory integer that specifies the nominal length of each cut.(Losses and other inefficiencies are added by the system to the nominal length based on what is specified on "Configs" )

Working Examples:

• Example 1 (preferred):

  
  "Cuts": [
      ["Cut A", 100, 100],
      ["Cut B", 200, 200],
      ["Cut C", 90, 300]
  ]
  							

• Example 2:

  
  "Cuts": [
      [100, 100],
      [150, 200],
      [90, 300]
  ]
  							

• Example 3:

  
  "Cuts": [
      ["Cut A", 100, 100],
      [150, 200],
      [90, 300]
  ]
  							

If a description is not provided, the API generates one based on the length adding the AUT tag. For example, if a [90,250] cut is added the system will generate the equivalent to [“Cut 250mm AUT”,90,250]

In case 2 cuts of the same nominal length are added the system will totalize in a single cut all the inputs adding the TOTALIZED tag. For example, for a ["Cut A", 100, 100], ["Cut B", 200, 100], ["Cut C", 90, 300] the system will process the equivalent to ["Cut A TOTALIZED", 300, 100], [“Cut C”, 90, 300].

More info on section of Merging and Sorting.

Configs Validation

Each field in the `Configs` object is validated according to the rules specified in "Input Format". If any field fails validation, the API returns an appropriate error message with the http response code 400.

Example Validation Error:

Request: {"bar_length": "invalid"}
Response: {"error": "Invalid type for bar_length: expected integer"}

Cuts Validation

Each entry in the "Cuts" array must contain at least two elements (quantity and length) and at most three elements (optional description, quantity, and length).

Valid Cuts:

• Two elements with quantity and length it will auto-generate the description.
• Three elements with a description, quantity, and length will be accepted as is.

Invalid Cuts:

• If the array has less than two or more than three elements, it will be rejected.

Example Validation Error:

Request:[["Cut A", 100], ["Cut B"]]
Response:{"error": "Each cut must include a mandatory length and quantity"}

Merging and Sorting

After validation, the cutting instructions are processed as follows:

• Merging: Cuts of the same length are combined. If two cuts have the same length but different descriptions, the descriptions are merged, and a "TOTALIZED" label is added.
• Sorting: Cuts are sorted by their nominal length from shortest to longest for processing and output.

Optimization Algorithms

Several optimization algorithms run to determine the best way to cut the bars based on the input configurations and cutting instructions. This algorithm used Montecarlo simulations and proprietary selective postprocessing. The quality of the answer is not 100% perfect as with any statistic method but is relatively very accurate. A very important aspect of this algorithms is that 2 runs can have slightly different results, an effect that should be reduced (up to a point) by increasing slightly the iterations. Beware that increasing iterations can reduce drastically the performance of the algorithms.

JSON Response

The API returns results in JSON format by default. It contains details of the optimized cuts, bar usage, and leftover material.

1. Status: 200 – Indicating that there is a successful response.
2. Configs: : The configuration parameters used by the algorithms.
3. Results: Macro results including global performance number of the optimization process.
4. Bars: Detailed results of each bar and how it should be cut.

Examples

1. Example of output with JSON Response ("include_zero_cuts": false):

   
   {
       "status": "success",
       "configs": {
           "Bar Length": 6000,
           "Calculated Bar Length": 6000,
           "Iterations": 5000,
           "Cut Losses": 0,
           "Bar Variability": 0,
           "Saw Blade Width": 0,
           "End Cuts for Each Side": 0,
           "include_zero_cuts": false,
           "Data Type": "json"
       },
       "results": {
           "Qty of Requested Cuts": 3,
           "Qty of Optimized Cuts": 3,
           "Qty of Bars Needed": 2,
           "Total (Nominal) Length to be Cut": 9000,
           "Total (Real) Length to be Cut": 9000,
           "Total Cutting Losses": 0,
           "Total Leftover": 3000
       },
       "bars": [{
           "Bar Number": 1,
           "Total Length Used": 5000,
           "Bar Left Over": 1000,
           "Cuts": [{
               "Nominal Length": 5000,
               "Name": "Cut A",
               "Quantity": 1
           }]
       }, {
           "Bar Number": 2,
           "Total Length Used": 4000,
           "Bar Left Over": 2000,
           "Cuts": [{
               "Nominal Length": 2000,
               "Name": "Cut B",
               "Quantity": 2
           }]
       }]
   }
   							

2. Example of output with JSON Response ("include_zero_cuts": true):

   
   {
       "status": "success",
       "configs": {
           "Bar Length": 6000,
           "Calculated Bar Length": 6000,
           "Iterations": 5000,
           "Cut Losses": 0,
           "Bar Variability": 0,
           "Saw Blade Width": 0,
           "End Cuts for Each Side": 0,
           "Include Zero Cuts": true,
           "Data Type": "json"
       },
       "results": {
           "Qty of Requested Cuts": 3,
           "Qty of Optimized Cuts": 3,
           "Qty of Bars Needed": 2,
           "Total (Nominal) Length to be Cut": 9000,
           "Total (Real) Length to be Cut": 9000,
           "Total Cutting Losses": 0,
           "Total Leftover": 3000
       },
       "bars": [{
           "Bar Number": 1,
           "Total Length Used": 5000,
           "Bar Left Over": 1000,
           "Cuts": [{
               "Nominal Length": 2000,
               "Name": "Cut B",
               "Quantity": 0
           }, {
               "Nominal Length": 5000,
               "Name": "Cut A",
               "Quantity": 1
           }]
       }, {
           "Bar Number": 2,
           "Total Length Used": 4000,
           "Bar Left Over": 2000,
           "Cuts": [{
               "Nominal Length": 2000,
               "Name": "Cut B",
               "Quantity": 2
           }, {
               "Nominal Length": 5000,
               "Name": "Cut A",
               "Quantity": 0
           }]
       }]
   }
   
   							

CSV Response

If "data_type" is set to "csv", the response will be a CSV string that can be saved as a .csv file containing the output information in tabular form divided in 3 macro sections: configurations, results and bars.
Each section has specific and relevant information about the optimization process.

1. Configurations
   Table that shows the selected configurations for the optimization process.
   

   #CONFIGURATIONS
   Configuration Parameter	Value
   Bar Length	6000
   Calculated Bar Length	6000
   Iterations	5000
   Cut Losses	0
   Bar Variability	0
   Saw Blade Width	0
   End Cuts for Each Side	0
   Include Zero Cuts	0
   Data Type	csv

2. Results
   Results of the optimization process that shows the global results. It is important to check always that the qty of requested cuts is equal to the qty of optimized cuts.
   

   #RESULTS
   Result Parameter	Value
   Qty of Requested Cuts	90
   Qty of Optimized Cuts	90
   Qty of Bars Needed	3
   Total (Nominal) Length to be Cut	18000
   Total (Real) Length to be Cut	18000
   Total Cutting Losses	0
   Total Leftover	0

3. 3. Bars:
   This section displays each single bar and the quantity of cuts that can be obtained in each bar.
   For example: in Bar 1 it is expected to have 10 Cuts A of 100mm, 16 Cuts B of 200mm and 6 Cuts C of 300mm.
   The row number is a progressive identification that can be used as a primary key. The total length and bar left over are the ones of the bar and will be repeated on each row associated to that bar.
   

   #BARS
   Row Number	Bar Number	Total Length Used	Bar Left Over	Nominal Length	Name	Quantity
   0	1	6000	0	100	Cut A	10
   1	1	6000	0	200	Cut B	16
   2	1	6000	0	300	Cut C	6
   3	2	6000	0	100	Cut A	13
   4	2	6000	0	200	Cut B	10
   5	2	6000	0	300	Cut C	9
   6	3	6000	0	100	Cut A	7
   7	3	6000	0	200	Cut B	4
   8	3	6000	0	300	Cut C	15

Common HTTP Error Codes

• 403 Forbidden: Missing or invalid credentials.
• 405 Method Not Allowed: Only POST requests are accepted.
• 400 Bad Request: Invalid input format, missing fields, or validation failure.

Custom Validation Errors

• Invalid JSON Format:
  

  Response: {"error": "Invalid JSON format"}

• Invalid Config Field:
  

  Response:{"error": "Invalid value for bar_length: expected integer"}

• Invalid Cuts Field::
  

  Response: {"error": "Each cut must include a mandatory length and quantity"}

Example 1: 3 Cuts - JSON - no zeros

Optimize 10 Cuts of 1000mm, 10 Cuts of 2000mm and 10 Cuts of 3000mm using bars of 6000mm.

Request:

{
    "Configs": {
        "bar_length": 6000,
        "saw_width": 0,
        "end_cut": 0,
        "variability": 0,
        "losses": 0,
        "iterations": 5000,
        "include_zero_cuts": false,
        "data_type": "json"
    },
    "Cuts": [
      	["Cut A", 10, 1000],
    	["Cut B", 10, 2000],
    	["Cut C", 10, 3000]
    ]
}
							

Response:

{
    "status": "success",
    "configs": {
        "Bar Length": 6000,
        "Calculated Bar Length": 6000,
        "Iterations": 5000,
        "Cut Losses": 0,
        "Bar Variability": 0,
        "Saw Blade Width": 0,
        "End Cuts for Each Side": 0,
        "Include Zero Cuts": false,
        "Data Type": "json"
    },
    "results": {
        "Qty of Requested Cuts": 30,
        "Qty of Optimized Cuts": 30,
        "Qty of Bars Needed": 10,
        "Total (Nominal) Length to be Cut": 60000,
        "Total (Real) Length to be Cut": 60000,
        "Total Cutting Losses": 0,
        "Total Leftover": 0
    },
    "bars": [{
        "Bar Number": 1,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 1000,
            "Name": "Cut A",
            "Quantity": 3
        }, {
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 1
        }]
    }, {
        "Bar Number": 2,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 1000,
            "Name": "Cut A",
            "Quantity": 3
        }, {
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 1
        }]
    }, {
        "Bar Number": 3,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 1000,
            "Name": "Cut A",
            "Quantity": 3
        }, {
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 1
        }]
    }, {
        "Bar Number": 4,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 2
        }]
    }, {
        "Bar Number": 5,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 2
        }]
    }, {
        "Bar Number": 6,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 2
        }]
    }, {
        "Bar Number": 7,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 1000,
            "Name": "Cut A",
            "Quantity": 1
        }, {
            "Nominal Length": 2000,
            "Name": "Cut B",
            "Quantity": 1
        }, {
            "Nominal Length": 3000,
            "Name": "Cut C",
            "Quantity": 1
        }]
    }, {
        "Bar Number": 8,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 2000,
            "Name": "Cut B",
            "Quantity": 3
        }]
    }, {
        "Bar Number": 9,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 2000,
            "Name": "Cut B",
            "Quantity": 3
        }]
    }, {
        "Bar Number": 10,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 2000,
            "Name": "Cut B",
            "Quantity": 3
        }]
    }]
}

							

Example 2: 5 Cuts - JSON - with zeros

Optimize 2 Cuts of 1000mm, 3 Cuts of 2000mm, 4 Cuts of 100mm, 6 Cuts of 50mm and 4 Cuts of 350mm using bars of 6000mm.

Request:

{
    "Configs": {
        "bar_length": 6000,
        "saw_width": 0,
        "end_cut": 0,
        "variability": 0,
        "losses": 0,
        "iterations": 5000,
        "include_zero_cuts": true,
        "data_type": "json"
    },
    "Cuts": [
      	["Frame 1", 2, 1000],
    	["Beam 2", 3, 2000],
    	["Cross Beam", 4, 100],
      	["Column", 6, 50],
      	["Support", 4, 350]
    ]
}
							

Response:

{
    "status": "success",
    "configs": {
        "Bar Length": 6000,
        "Calculated Bar Length": 6000,
        "Iterations": 5000,
        "Cut Losses": 0,
        "Bar Variability": 0,
        "Saw Blade Width": 0,
        "End Cuts for Each Side": 0,
        "Include Zero Cuts": true,
        "Data Type": "json"
    },
    "results": {
        "Qty of Requested Cuts": 19,
        "Qty of Optimized Cuts": 19,
        "Qty of Bars Needed": 2,
        "Total (Nominal) Length to be Cut": 10100,
        "Total (Real) Length to be Cut": 10100,
        "Total Cutting Losses": 0,
        "Total Leftover": 1900
    },
    "bars": [{
        "Bar Number": 1,
        "Total Length Used": 6000,
        "Bar Left Over": 0,
        "Cuts": [{
            "Nominal Length": 50,
            "Name": "Column",
            "Quantity": 4
        }, {
            "Nominal Length": 100,
            "Name": "Cross Beam",
            "Quantity": 1
        }, {
            "Nominal Length": 350,
            "Name": "Support",
            "Quantity": 2
        }, {
            "Nominal Length": 1000,
            "Name": "Frame 1",
            "Quantity": 1
        }, {
            "Nominal Length": 2000,
            "Name": "Beam 2",
            "Quantity": 2
        }]
    }, {
        "Bar Number": 2,
        "Total Length Used": 4100,
        "Bar Left Over": 1900,
        "Cuts": [{
            "Nominal Length": 50,
            "Name": "Column",
            "Quantity": 2
        }, {
            "Nominal Length": 100,
            "Name": "Cross Beam",
            "Quantity": 3
        }, {
            "Nominal Length": 350,
            "Name": "Support",
            "Quantity": 2
        }, {
            "Nominal Length": 1000,
            "Name": "Frame 1",
            "Quantity": 1
        }, {
            "Nominal Length": 2000,
            "Name": "Beam 2",
            "Quantity": 1
        }]
    }]
}
							

Example 3: 2 Cuts - CSV - no zeros

Optimize 65 Cuts of 100mm and 20 Cuts of 35mm using bars of 4000mm.

Request:

{
    "Configs": {
        "bar_length": 4000,
        "saw_width": 0,
        "end_cut": 0,
        "variability": 0,
        "losses": 0,
        "iterations": 5000,
        "include_zero_cuts": false,
        "data_type": "csv"
    },
    "Cuts": [
      	["Part 1", 65, 100],
    	["Part 2", 20, 35]
    ]
}

							

Response:

"# CONFIGURATIONS"
"Configuration Parameter",Value
"Bar Length",4000
"Calculated Bar Length",4000
Iterations,5000
"Cut Losses",0
"Bar Variability",0
"Saw Blade Width",0
"End Cuts for Each Side",0
"Include Zero Cuts",
"Data Type",csv

"# RESULTS"
"Result Parameter",Value
"Qty of Requested Cuts",85
"Qty of Optimized Cuts",85
"Qty of Bars Needed",2
"Total (Nominal) Length to be Cut",7200
"Total (Real) Length to be Cut",7200
"Total Cutting Losses",0
"Total Leftover",800

"# BARS"
"Row Number","Bar Number","Total Length Used","Bar Left Over","Nominal Length",Name,Quantity
0,1,4000,0,35,"Part 2",20
1,1,4000,0,100,"Part 1",33
2,2,3200,800,100,"Part 1",32

							

Example 4: 2 Cuts - CSV - with zeros

Optimize 65 Cuts of 100mm and 20 Cuts of 35mm using bars of 4000mm.

Request:

{
    "Configs": {
        "bar_length": 4000,
        "saw_width": 0,
        "end_cut": 0,
        "variability": 0,
        "losses": 0,
        "iterations": 5000,
        "include_zero_cuts": true,
        "data_type": "csv"
    },
    "Cuts": [
      	["Part 1", 65, 100],
    	["Part 2", 20, 35]
    ]
}

							

Response:

"# CONFIGURATIONS"
"Configuration Parameter",Value
"Bar Length",4000
"Calculated Bar Length",4000
Iterations,5000
"Cut Losses",0
"Bar Variability",0
"Saw Blade Width",0
"End Cuts for Each Side",0
"Include Zero Cuts",1
"Data Type",csv

"# RESULTS"
"Result Parameter",Value
"Qty of Requested Cuts",85
"Qty of Optimized Cuts",85
"Qty of Bars Needed",2
"Total (Nominal) Length to be Cut",7200
"Total (Real) Length to be Cut",7200
"Total Cutting Losses",0
"Total Leftover",800

"# BARS"
"Row Number","Bar Number","Total Length Used","Bar Left Over","Nominal Length",Name,Quantity
0,1,4000,0,35,"Part 2",20
1,1,4000,0,100,"Part 1",33
2,2,3200,800,35,"Part 2",0
3,2,3200,800,100,"Part 1",32