Skip to main content

Optimizer

Updated

The Optimizer optimizes loads by sending them to the BlackBox Optimizer. It supports both synchronous and asynchronous processing, allowing requests to be processed or queued for later retrieval. 

Endpoints

GET     /opt/v1/status

POST   /opt/v1/sync

POST   /opt/v1/async

GET     /opt/v1/progress/{jobid}

GET     /opt/v1/result/{jobid}

GET     /opt/v1/images/{jobid}

 

Asynchronous vs. Synchronous Optimization

The BlackBox Optimizer supports two optimization methods: asynchronous and synchronous. Choosing the right method depends on the use case, optimization complexity, and system requirements. 

Asynchronous Optimization

Asynchronous optimization is designed for larger and more complex optimization tasks that require extended processing times. It allows the client to submit an optimization request and retrieve the results later via a webhook. 

Synchronous Optimization

Synchronous optimization is designed for real-time processing where immediate results are required. The request remains open until the optimization process completes, returning the results directly. 

Feature Asynchronous Optimization Synchronous Optimization
Response Handling Returns a jobid, results retrieved later. Returns results immediately.
Performance Slightly slower response due to webhook. Faster for small optimizations.
Best For Large jobs (palletization, truck/railcar loading) Small, real-time jobs (cartonization)
Scalability Allows parallel processing of multiple jobs.  Limited to one request per process.
Risk of Timeout No risk of client-side timeout. High risk for long-running jobs.
Webhook Support Yes, results can be pushed via webhook. No, results must be retrieved manually.
Progress Updates Can poll for job status updates. No updates until request completes.

 

Choosing the Right Method

Use asynchronous optimization when:

  • The optimization process is expected to take more than a few seconds.
  • Parallel execution of multiple jobs is required.
  • The client application cannot afford long blocking requests. 
  • Webhooks can be used for automatic result delivery.

Use synchronous when:

  • The optimization process is short and efficient. 
  • The client needs immediate results. 
  • The risk of request timeouts is low. 

Both methods have their use cases, and selecting the right one depends on the optimization workload, system architecture, and latency requirements. 

Retrieve BlackBox Status

Checks the status of the BlackBox optimizer to ensure it is operational. 

Request

curl -X GET "https://api.magiclogic.com/opt/v1/status" \
  -H "Authorization: Basic YOUR_API_KEY"

Response

{
  "status": "OK",
  "usage": "0",
  "uptime": "12:14:12:,
  "localtime": "2025-02-21T12:00:00Z",
  "loadfactor": "0"
  "license": "xxxxxx"
}

 

Optimize Synchronously

Processes an optimization request immediately and returns the result in the response. 

Request

curl -X GET "https://api.magiclogic.com/opt/v1/sync" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "load_id": "load_001",
        "priority": "high"
      }'

Response

{
  "jobid": "00001348-00000001-127.0.0.1-10101",
  "status": "Completed",
  "result": {
    "containers_loaded": 3,
    "efficiency": "92.4%",
    "total_weight": "2500kg"
  }
}

 

Optimize Asynchronously

Submits an optimization request without waiting for completion. A jobid is returned for tracking. 

Request

curl -X GET "https://api.magiclogic.com/opt/v1/sync" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "load_id": "load_001",
        "priority": "high"
      }'

Response

{
  "jobid": "00001349-00000002-127.0.0.1-10101",
  "status": "Queued"
}

 

Retrieve Optimization Progress

Fetches the progress of an asynchronous optimization job. 

Request

curl -X GET "https://api.magiclogic.com/opt/v1/progress/{jobid}" \
  -H "Authorization: Basic YOUR_API_KEY" \

Response

{
  "jobid": "00001348-00000001-127.0.0.1-10101",
  "age": "44",
  "status": "Completed",
  "position": "0",
  "averagetime": "00:00:00",
  "containercnt": "1",
  "containerix": "1",
  "curiter": "30",
  "maxiter": "30",
  "realsec": "1",
  "maxsec": "1",
  "numloaded": "42",
  "bestvolumeperc": "87.2424",
  "bestweightperc": "74.8746"
}

 

Retrieve Optimization Results

Fetches the final optimization results after the job is completed.  Be aware that the optimization results can only be retrieved once.

Request

curl -X GET "https://api.magiclogic.com/opt/v1/result/{jobid}" \
  -H "Authorization: Basic YOUR_API_KEY" \

Response

{
  "jobid": "00001349-00000002-127.0.0.1-10101",
  "status": "Completed",
  "result": {
    "containers_loaded": 2,
    "efficiency": "95.6%",
    "total_weight": "3200kg"
  }
}

 

Retrieve Load Diagrams

Fetches visualization diagrams for the optimized load.

Request

curl -X GET "https://api.magiclogic.com/opt/v1/images/{jobid}" \
  -H "Authorization: Basic YOUR_API_KEY" \

Response

This request will return a ZIP file containing the load diagram images. The file may include JPG, PNG, or PDF formats. 

On this page

    Related to

    Related articles