API - Reference

API-REFERENCE

Cargo Spectre can seamlessly integrate into your existing warehouse
management software.  Our API is simple to use and available at NO COST
to any Cargo Spectre customer.

OVERVIEW

Our API uses HTTP REST/SOAP. It is not encrypted, and should only be used in local networks if message privacy is important.
The default port used is 7100, although it is configurable in the config.xml. Requests are made as either a POST or GET request to the
server’s IP address on the specified port. The server responds with either XML or binary data in the case of a file request.

URL Endpoints

Cargo Spectre uses localhost for all API calls, but does need access to certain external addresses for the following services:

URL Service
https://spectre-licensing.com Licensing and optional cloud storage of cargo data
https://spectre-support.centralus.cloudapp.azure.com Client version updates and support

 

POST Requests

Input Format

A POST request should contain a body with XML containing the list of requested actions.

<Requests>
  <ApiName>
    <ApiInputTree>
  </ApiName>
  <AnotherApiName/>
<Requests>

We can request multiple API calls at a time, duplicates included. They will be executed in order, but keep in mind that a blocking SOAP call will take longer with more API calls. Note: In the below example, Snapshot does not happen until Dimension is completed. After both Dimension and Snapshot are completed, the server returns the results of both in the output format.

<Requests>
  <Dimension>
  <Snapshot>
</Requests>

Output Format

<Responses>
  <ApiName code="0">
    <ApiOutputTree>
  </ApiName>
  <ApiName code="5" description="some error"/>
</Responses>

For each API request, there will be a corresponding response tree. Each response is accompanied by an error code attribute. An error code of 0 means the call was successful.

Example output:

<Responses>
    <Dimension code="0">
        <Info>
            <Dimensions>
                <Length>60.5</Length>
                <Width>60.5</Width>
                <Height>61.0</Height>
                <Volume>223275.000</Volume>
                <Weight>
                    <Net>0</Net>
                    <Gross>0</Gross>
                    <Tare>0</Tare>
                </Weight>
                <Barcode/>
            </Dimensions>
            <Units>
                <Length>Inches</Length>
                <Volume>Cubic Feet</Volume>
                <Weight>lb</Weight>
            </Units>
        </Info>
    </Dimension>
    <Snapshot code="0">
        <Directory>
            <Clouds>
                <Path>Jun-13_09-24-36_2016/073340441047-raw.pcd</Path>
            </Clouds>
            <Images>
                <Path>Jun-13_09-24-36_2016/color-image0.png</Path>
            </Images>
            <Xmls>
                <Path>Jun-13_09-24-36_2016/info.xml</Path>
            </Xmls>
        </Directory>
    </Snapshot>
</Responses>

That is the expected response for a requests that calls for a Dimension action followed by a Snapshot action.

Additional Example Request:

POST http://192.168.1.169:7100 with the following body:

<Requests>
  <Ping/>
<Requests>

Example Response:

<Responses>
  <Ping code="0"/>
</Responses>

GET Requests

Input Format

Every API call that can be specified with POST can also be sent through GET. The GET call does the same thing as POST but converts it to a single request without any inputs. Some API calls will return errors if used in this way if they require inputs to do something.

Note: API actions (/file, /dimension, /settings, etc) should all be lowercase.

Example:

http://ip_address:7100/dimension

Clients can retrieve specific files from the machine through GET calls. The Snapshot API, for instance, returns paths to various different data files for a particular piece of freight. You can use GET with a prepended “/file” to grab such files. Files can only be retrieved from within the “~/Cargo-Spectre” directory and no files outside of that will be accessible through this method.

Example:

http://ip_address:7100/file/Jun-13_09-24-36_2016/color-image0.png

Output Format

Output for GET requests is the same as for POST requests. See Output format above.


Current API List

<Dimension>

Reports the dimensions, and volume of the object. May also include the weight and barcode of the object if applicable.

<Snapshot>

Saves reported dimensions along with images, clouds, and other metadata. Returns the resulting directory structure

<Ping>

Simple API that always returns success

<CalibrateBackground>

This makes the Cargo Spectre server capture data from the depth-sensing cameras and use it to determine what the background looks like without the presence of an object

<CalibrateCentroidObject>

Once an object has been placed in the center of the scene, this API call can be used to tell the Cargo Spectre server where to expect cargo to be placed for dimensioning.

<ReportError>

If a piece has a questionable scan, it’s possible to report an error to us. This will upload the previous scan’s data to our cloud (including your calibration) where we can investigate what may have happened. Such cases can also be added to our regressions to better ensure accuracy in future versions. When using this reporting tool, we ask you to measure the cargo by an alternative method and then provide us with the measured: Length, Width, and Height (using the unit of measurement that your Cargo Spectre is set to).

<ReportError>
  <Length>30.0</Length>
  <Width>20.0</Width>
  <Height>40</Height>
</ReportError>

<SetSetting>

Sets custom settings for the server to use. You can use this to modify settings such as a machine name or the measurement units.

Example Request

<SetSetting>
  <Path>/Settings/Device/Name</Path>
  <Value>Loading Dock</Value>
</SetSetting>
Paths (case sensitive) Accepted values (case sensitive) Description
/Settings/Device/Name <any string> Human-readable name for a particular machine
/Settings/Device/Scale/Format Totalcomp Continuous Format | FB1100 Continuous Format | Rice Lake Continuous Format | CI200 Continuous Format Scale data format
/Settings/Device/Scale/Baud 9600 | 14400 | 19200 | 28800 | 38400 | 56000 | 57600 | 115200 Baud rate for an attached scale
/Settings/Device/Scale/Parity 8 data bits, no parity bit, 1 stop bit | 7 data bits, even parity bit, 1 stop bit | 7 data bits, odd parity bit, 1 stop bit Communication information for an attached scale
/Settings/Device/Scale/Ntep <any string> The NTEP certification number for the attached scale
/Settings/Printing/Pdf true | false Generates a freight report PDF when enabled
/Settings/Printing/Logo <a string that is a valid file path to an image> A file path for a company logo to be displayed on freight reports
/Settings/RemoteApi/Port <any integer in range 1024-49151> Port number
/Settings/Scanner/Mode Cargo | Parcel Scanning mode. Select “cargo” for two camera operation, and “parcel” for one camera.
/Settings/Scanner/Upload Never | When saving [Under development] Uploads scans to cloud storage
/Settings/Snapshot/Images/Format jpg | png The file format to save images in
/Settings/Units/Length millimeters | centimeters | meters | inches | feet Length measurement unit for dimensions
/Settings/Units/Volume cubic millimeters | cubic centimeters | cubic meters | cubic inches | cubic feet Volume measurement unit
/Settings/Units/Weight kilograms | lb Weight measurement unit

<GetSetting>

This retrieves the value of any setting set either through the Cargo Spectre settings menu or the <SetSetting> command detailed above.

Example request

<GetSetting>
  <Path>/Settings/Units/Length</Path>
</GetSetting>

<GetErrorStatus>

This returns the last status code set by the Cargo Spectre server, whether error or success.


Matchmaking Server

The matchmaking server is separate from the other Cargo Spectre API calls and will return a list of all Cargo Spectre devices that have successfully checked out a license using your credentials. You can manually view these records at http://spectre-licensing.com.

JSON (default)

Request example (included in the POST body):
{
    "email": "fake@company.com",
    "password": "FakePassword123!"
}
Response example:
{
  "matches": [
    {
      "publicIP": "100.150.162.60",
      "localIP": "192.168.1.100:321",
      "macAddress": "bbb156d2651f",
      "machineName": "Dock 5",
      "lastUpdated": "2016-12-18T13:57:14.777059"
    },
    {
      "publicIP": "",
      "localIP": "127.0.0.1:7100",
      "macAddress": "f46d04698d",
      "machineName": "Receiving Bay",
      "lastUpdated": "2016-11-20T16:21:07.8148707"
    },
    {
      "publicIP": "48.78.4.91",
      "localIP": "192.168.1.197:7100",
      "macAddress": "742f681c2d",
      "machineName": "Departure Scanner",
      "lastUpdated": "2016-11-20T15:16:27.4377527"
    }
  ],
  "error": null
}

 

XML

Note: to receive XML back, the request must specify the “Accept” header with the value set to “application/xml” otherwise the response will be returned in JSON.
Request example:
<MatchmakingRequest>
 <Email>fake@company.com</Email>
 <Password>FakePassword123!</Password>
</MatchmakingRequest>

Response example:

<MatchmakingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Matches>
        <Match>
            <PublicIP>100.150.162.60</PublicIP>
            <LocalIP>192.168.1.100:321</LocalIP>
            <MACAddress>bbb156d2651f</MACAddress>
            <MachineName>Dock 5</MachineName>
            <LastUpdated>2016-12-18T13:57:14.777059</LastUpdated>
        </Match>
        <Match>
            <PublicIP>8.211.81.5</PublicIP>
            <LocalIP>127.0.0.1:7100</LocalIP>
            <MACAddress>f46d04698d</MACAddress>
            <MachineName>Receiving Bay</MachineName>
            <LastUpdated>2016-11-20T16:21:07.8148707</LastUpdated>
        </Match>
        <Match>
            <PublicIP>48.78.4.91</PublicIP>
            <LocalIP>192.168.1.197:7100</LocalIP>
            <MACAddress>742f681c2d</MACAddress>
            <MachineName>Departure Scanner</MachineName>
            <LastUpdated>2016-11-20T15:16:27.4377527</LastUpdated>
        </Match>
    </Matches>
</MatchmakingResponse>
Scroll to top