Skip to main content

Searching For, and Exporting, Cargo Data

The Search Request API will return a cargoID, barcode, and scanDate based on an inputted search parameter. The search parameter can be a barcode, a date from, a date to, a machine name, or any combination of them.

Cargo Spectre date format

Dates must be specified in ISO 8601 format (yyyy-mm-ddT00:00:00) with at least a date (but optionally a time as well), e.g. February 1, 2022 at 2PM (1400) would be 2022-02-01T14:00:00.

Cargo sort

Results are returned from newest to oldest. Older cargo will have a CargoId of type int that is smaller than newer cargo. For example, for CargoId 100 vs 99, 100 will be the newer one and will be returned first.

HTTPS required

The cloud server is separate from Spectre Dimensioner API calls and uses a different endpoint. Please note that for security, the endpoint MUST be HTTPS and not HTTP.

<Api/Cargo/Search>​

Request​

The search API returns at most 60 items per response to keep server load manageable. For that reason, the API can accept a "last ID received" parameter LastCargoID to return unique results on the next request. This parameter should be the oldest (smallest) cargoID received from the last search response. One can keep querying the server for this information until the server returns a null in the search results (or, equivalently, an error of "End of results list").

Endpoint​

POSThttps://spectre-licensing.com/api/cargo/search


Body​

{
    "email": "fake@company.com",
    "password": "FakePassword123!",
    "barcode": "12341234",
    "dateFrom": "2022-03-01",
    "dateTo": "2023-01-01T03:23:10",
    "machineName": "TestMachine"
}

Response with Results Returned​

{
  "searchResults": [
    {
        "barcode": "12341234",
        "cargoID": 11111,
        "scanDate": "yyyy-mm-ddT12:00:00",
        "machineName": "Laptop1"
    },
    {
        "barcode": "12345",
        "cargoID": 11110,
        "scanDate": "yyyy-mm-ddT00:00:00",
        "machineName": "TestComputer-1"
    }
  ],
  "error": null
}

Response with No Results​

Compare the below response example to the above, with two returned results where the oldest (smallest) cargoID was 11110, to the response shown below. If 11110 is the last ID that meets the search constraints, and a subsequent search with "lastCargoID":"11110" is performed, a result of "null" and "End of results list" will be received. If there are older cargo items than 11110, they will be returned instead, again up to a count of 60. The process can then be repeated with the new lastCargoID received.

{
  "searchResults": null,
  "error": "End of results list"
}

<Api/Cargo/Export>​

The Export Cargo API will return the entire set of data about a piece of cargo. A cargo can only be retrieved by knowing its cargoID (as returned in the search API).

Parameters​

The api/cargo/export endpoint can take optional parameters.

IncludeShareLink will include a share GUID that can be appended to https://spectre-licensing.com/Cargo/Shared/ to provide no-authentication access to that specific scan. The share GUID will be created if one does not exist, or the existing one will be sent if one already exists.

Type: Bool

Default: none

Request​

Endpoint​

POSThttps://spectre-licensing.com/api/cargo/export


Body​

{
    "email": "fake@company.com",
    "password": "FakePassword123!",
    "cargoID": 11110
}

Response​

The response will have the same format as data returned by performing a Dimension+Snapshot command via the Spectre Dimensioner API. However, it will also have Custom Fields associated with the cargo's Cloud data.

Retrieving files

Pictures, PDFs, and other files associated with the cargo record can be retrieved by sending a GET to https://cargospectre.blob.core.windows.net/scans/ as in the response comments below.

{
  "responses": {
    "dimension": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "info": {
        "cargoID": 43286, // Number - Internal Cargo Spectre ID
        "name": "", // String - Optional cargo name
        "barcode": "FAKEBARCODE123", // String
        "comments": "Comments are optional and can be left blank.", // String
        "scanDate": "2018-11-16T03:49:18", // String - UTC time in ISO format
        "machineName": "Laptop", // String - Human readable name of the Spectre machine that authored the data
        "scanGuid": "3a75b02a-9300-4ba4-a117-87869dc14e9a", // String - This may be used in future sharing scenarios
        "dimensions": {
          "length": 0.81, // Number
          "width": 0.54, // Number
          "height": 0.55, // Number
          "volume": 0.247132, // Number
          "density": 305.504750, // Number
          "weight": {
            "net": 75.5, // Number
            "gross": 76.5, // Number
            "tare": 1.5 // Number
          },
        },
        "units": {
          "length": "meters", // String - Applies to Length, Width, and Height
          "volume": "cubic meters", // String - Applies to Volume
          "weight": "lb", // String - Applies to Net, Gross, and Tare
          "density": "lb/cubic meters" // String - Applies to Net, Gross, and Tare
        },
        "customFields": { // Optional custom fields that your organization can configure will show up here
          "Is Damaged": true,
          "Piece Count": 3,
          "Destination": "LAX",
        }
      }
    },
    "snapshot": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "directory": { // All path values are relative to: https://cargospectre.blob.core.windows.net/scans/
        "clouds": {
          "path": [ // Array of strings - Point cloud 3D models of the scene
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\combined-raw.pcd",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\box.pcd"
          ]
        },
        "images":{
          "path": [ // Array of strings - Images of the cargo
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1-marked.jpg"
          ]
        },
        "thumbnails": {
          "path": [ // Array of strings - Same as the images above just smaller (for faster loading if needed)
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1-marked.jpg"
          ]
        },
        "misc": {
          "path": [ // Array of strings - Freight reports or other cargo documents
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\Freight-Report.pdf"
          ]
        }
      }
    }
  }
}

Request with ShareGuid​

Endpoint​

POSThttps://spectre-licensing.com/api/cargo/export


Body​

{
    "email": "fake@company.com",
    "password": "FakePassword123!",
    "cargoID": 11110,
    "includeShareGuid": true
}

Response with ShareGuid​

The response will have the same format as data returned by performing a Dimension+Snapshot command via the Spectre Dimensioner API. However, it will also have Custom Fields associated with the cargo's Cloud data.

Retrieving files

Pictures, PDFs, and other files associated with the cargo record can be retrieved by sending a GET to https://cargospectre.blob.core.windows.net/scans/ as in the response comments below.

{
  "responses": {
    "dimension": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "info": {
        "cargoID": 43286, // Number - Internal Cargo Spectre ID
        "name": "", // String - Optional cargo name
        "barcode": "FAKEBARCODE123", // String
        "comments": "Comments are optional and can be left blank.", // String
        "scanDate": "2018-11-16T03:49:18", // String - UTC time in ISO format
        "machineName": "Laptop", // String - Human readable name of the Spectre machine that authored the data
        "scanGuid": "3a75b02a-9300-4ba4-a117-87869dc14e9a", // String
        "shareGuid": "20060ff1-427b-419d-be81-72a18d4e98b5", // String
        "dimensions": {
          "length": 0.81, // Number
          "width": 0.54, // Number
          "height": 0.55, // Number
          "volume": 0.247132, // Number
          "density": 305.504750, // Number
          "weight": {
            "net": 75.5, // Number
            "gross": 76.5, // Number
            "tare": 1.5 // Number
          },
        },
        "units": {
          "length": "meters", // String - Applies to Length, Width, and Height
          "volume": "cubic meters", // String - Applies to Volume
          "weight": "lb", // String - Applies to Net, Gross, and Tare
          "density": "lb/cubic meters" // String - Applies to Net, Gross, and Tare
        },
        "customFields": { // Optional custom fields that your organization can configure will show up here
          "Is Damaged": true,
          "Piece Count": 3,
          "Destination": "LAX",
        }
      }
    },
    "snapshot": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "directory": { // All path values are relative to: https://cargospectre.blob.core.windows.net/scans/
        "clouds": {
          "path": [ // Array of strings - Point cloud 3D models of the scene
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\combined-raw.pcd",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\box.pcd"
          ]
        },
        "images":{
          "path": [ // Array of strings - Images of the cargo
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1-marked.jpg"
          ]
        },
        "thumbnails": {
          "path": [ // Array of strings - Same as the images above just smaller (for faster loading if needed)
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1-marked.jpg"
          ]
        },
        "misc": {
          "path": [ // Array of strings - Freight reports or other cargo documents
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\Freight-Report.pdf"
          ]
        }
      }
    }
  }
}

Receiving Exports from the Web GUI​

Single Export​

Cargo Spectre users can export cargo data from the cloud using the Cloud API or the Export feature on the website itself. There are three ways to export cargo data:

  • As cargo is scanned (from the remote control page)
  • From the cargo details page
  • From the cargo export API in the previous section

In order to export from the cloud website via the user interface, you will need to provide a URL endpoint that accepts HTTP POST requests. Cargo Spectre users have the ability to set a different URL for each Cargo Spectre device, so you may want to have a few different URL paths. For example:

EXPORTED FROMURL
Customer 1, Machine Ahttps://my-company-name.com/customer-1/machine-A
Customer 1, Machine Bhttps://my-company-name.com/customer-1/machine-B
Customer 2, Machine Ahttps://my-company-name.com/customer-2/machine-A

The exported data will take the JSON form by default, although there are other export formats available to users as well.

The following formats are standard, however some custom formats also exist for specific WMS, TMS, or ERP systems.

{
  "responses": {
    "dimension": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "info": {
        "cargoID": 43286, // Number - Internal Cargo Spectre ID
        "name": "", // String - Optional cargo name
        "barcode": "FAKEBARCODE123", // String
        "comments": "Comments are optional and can be left blank.", // String
        "scanDate": "2018-11-16T03:49:18", // String - UTC time in ISO format
        "machineName": "Laptop", // String - Human readable name of the Spectre machine that authored the data
        "scanGuid": "3a75b02a-9300-4ba4-a117-87869dc14e9a", // String - This may be used in future sharing scenarios
        "dimensions": {
          "length": 0.81, // Number
          "width": 0.54, // Number
          "height": 0.55, // Number
          "volume": 0.247132, // Number
          "density": 305.504750, // Number
          "weight": {
            "net": 75.5, // Number
            "gross": 76.5, // Number
            "tare": 1.5 // Number
          },
        },
        "units": {
          "length": "meters", // String - Applies to Length, Width, and Height
          "volume": "cubic meters", // String - Applies to Volume
          "weight": "lb", // String - Applies to Net, Gross, and Tare
          "density": "lb/cubic meters" // String - Applies to Net, Gross, and Tare
        },
        "customFields": { // Optional custom fields that your organization can configure will show up here
          "Is Damaged": true,
          "Piece Count": 3,
          "Destination": "LAX",
        }
      }
    },
    "snapshot": {
      "code": 0, // Number - Anything besides 0 indicates an error has occurred
      "directory": { // All path values are relative to: https://cargospectre.blob.core.windows.net/scans/
        "clouds": {
          "path": [ // Array of strings - Point cloud 3D models of the scene
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\combined-raw.pcd",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\box.pcd"
          ]
        },
        "images":{
          "path": [ // Array of strings - Images of the cargo
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1-marked.jpg"
          ]
        },
        "thumbnails": {
          "path": [ // Array of strings - Same as the images above just smaller (for faster loading if needed)
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0-marked.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1.jpg",
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1-marked.jpg"
          ]
        },
        "misc": {
          "path": [ // Array of strings - Freight reports or other cargo documents
            "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\Freight-Report.pdf"
          ]
        }
      }
    }
  }
}

Batch Export​

Cargo Spectre users can batch-export cargo data from the cloud using the Batch Export functionality.

In order to export from the cloud website via the user interface, you will need to provide a URL endpoint that accepts HTTP POST requests. Cargo Spectre users have the ability to set a different URL for each Cargo Spectre device, so you may want to have a few different URL paths. For example:

EXPORTED FROMURL
Customer 1, Machine Ahttps://my-company-name.com/customer-1/machine-A
Customer 1, Machine Bhttps://my-company-name.com/customer-1/machine-B
Customer 2, Machine Ahttps://my-company-name.com/customer-2/machine-A

The exported data will take the JSON form by default, although there are other export formats available to users as well.

The following formats are standard, however some custom formats also exist for specific WMS, TMS, or ERP systems.

{
  "cargoResponses": [
    {
      "responses": {
        "dimension": {
          "code": 0, // Number - Anything besides 0 indicates an error has occurred
          "info": {
            "cargoID": 43286, // Number - Internal Cargo Spectre ID
            "name": "", // String - Optional cargo name
            "barcode": "FAKEBARCODE123", // String
            "comments": "Comments are optional and can be left blank.", // String
            "scanDate": "2018-11-16T03:49:18", // String - UTC time in ISO format
            "machineName": "Laptop", // String - Human readable name of the Spectre machine that authored the data
            "scanGuid": "3a75b02a-9300-4ba4-a117-87869dc14e9a", // String - This may be used in future sharing scenarios
            "dimensions": {
              "length": 0.81, // Number
              "width": 0.54, // Number
              "height": 0.55, // Number
              "volume": 0.247132, // Number
              "density": 305.504750, // Number
              "weight": {
                "net": 75.5, // Number
                "gross": 76.5, // Number
                "tare": 1.5 // Number
              },
            },
            "units": {
              "length": "meters", // String - Applies to Length, Width, and Height
              "volume": "cubic meters", // String - Applies to Volume
              "weight": "lb", // String - Applies to Net, Gross, and Tare
              "density": "lb/cubic meters" // String - Applies to Net, Gross, and Tare
            },
            "customFields": { // Optional custom fields that your organization can configure will show up here
              "Is Damaged": true,
              "Piece Count": 3,
              "Destination": "LAX",
            }
          }
        },
        "snapshot": {
          "code": 0, // Number - Anything besides 0 indicates an error has occurred
          "directory": { // All path values are relative to: https://cargospectre.blob.core.windows.net/scans/
            "clouds": {
              "path": [ // Array of strings - Point cloud 3D models of the scene
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\combined-raw.pcd",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\box.pcd"
              ]
            },
            "images":{
              "path": [ // Array of strings - Images of the cargo
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\cameraName-0.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\cameraName-0-marked.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\cameraName-1.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\cameraName-1-marked.jpg"
              ]
            },
            "thumbnails": {
              "path": [ // Array of strings - Same as the images above just smaller (for faster loading if needed)
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\thumbnail\\cameraName-0.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\thumbnail\\cameraName-0-marked.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\thumbnail\\cameraName-1.jpg",
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\thumbnail\\cameraName-1-marked.jpg"
              ]
            },
            "misc": {
              "path": [ // Array of strings - Freight reports or other cargo documents
                "fake@shipper.com\\3a75b02a-9300-4ba4-a117-87869dc14e9a\\Freight-Report.pdf"
              ]
            }
          }
        }
      }
    },
    {
      "responses": {
        "dimension": {
          "code": 0, // Number - Anything besides 0 indicates an error has occurred
          "info": {
            "cargoID": 713286, // Number - Internal Cargo Spectre ID
            "name": "", // String - Optional cargo name
            "barcode": "FAKEBARCODE456", // String
            "comments": "Comments are optional and can be left blank.", // String
            "scanDate": "2024-11-16T03:49:18", // String - UTC time in ISO format
            "machineName": "Laptop3", // String - Human readable name of the Spectre machine that authored the data
            "scanGuid": "f2222139-ca9a-4c4a-8f44-e144455f0721", // String - This may be used in future sharing scenarios
            "dimensions": {
              "length": 6.81, // Number
              "width": 2.54, // Number
              "height": 6.55, // Number
              "volume": 0.247132, // Number
              "density": 1.5490127, // Number
              "weight": {
                "net": 175.5, // Number
                "gross": 176.5, // Number
                "tare": 1.5 // Number
              },
            },
            "units": {
              "length": "meters", // String - Applies to Length, Width, and Height
              "volume": "cubic meters", // String - Applies to Volume
              "weight": "lb", // String - Applies to Net, Gross, and Tare
              "density": "lb/cubic meters" // String - Applies to Net, Gross, and Tare
            },
            "customFields": { // Optional custom fields that your organization can configure will show up here
              "Is Damaged": false,
              "Piece Count": 1,
              "Destination": "LAX",
            }
          }
        },
        "snapshot": {
          "code": 0, // Number - Anything besides 0 indicates an error has occurred
          "directory": { // All path values are relative to: https://cargospectre.blob.core.windows.net/scans/
            "clouds": {
              "path": [ // Array of strings - Point cloud 3D models of the scene
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\combined-raw.pcd",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\box.pcd"
              ]
            },
            "images":{
              "path": [ // Array of strings - Images of the cargo
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-0-marked.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\cameraName-1-marked.jpg"
              ]
            },
            "thumbnails": {
              "path": [ // Array of strings - Same as the images above just smaller (for faster loading if needed)
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-0-marked.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1.jpg",
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\thumbnail\\cameraName-1-marked.jpg"
              ]
            },
            "misc": {
              "path": [ // Array of strings - Freight reports or other cargo documents
                "fake@shipper.com\\f2222139-ca9a-4c4a-8f44-e144455f0721\\Freight-Report.pdf"
              ]
            }
          }
        }
      }
    }
  ]
}

Optional Security Header​

To ensure that webhook export content is coming from Cargo Spectre and not an external source, you can optionally set a custom HTTP header to be a secret key that only Cargo Spectre would know about.

The secret key can be any text string and will be included as a basic authorization header. The following example shows what the HTTP request would look like when using Pass123! as the secret key:

POST 
host: https://example.com/export/bay-4
authorization: Basic Pass123!
content-type: application/json
content-length: 1024

{
  "responses": {
    "dimension": {
      "code": 0,
      "info": {
        "dimensions": {
          "length": 49.5,
          "width": 49,
          "height": 36.5,
          "volume": 51.23310089111328,
          "density": 7.8074524680855815,
          "weight": {
            "net": 400,
            "gross": 400,
            "tare": 0
          }
// ...JSON body truncated for this example