APSO | Quantum-South

FREEMIUM

Door Quantum-South | Bijgewerkt il y a 2 ans | Cargo

Spotlights

Introducing APSO for the air cargo industry

Here's a video on APSO's capabilities.

APSO Product Brochure

Read more on APSO's functionalities in this two-pages doc.

Volgers: 0

Bronnen:

Productwebsite

API maker:

Quantum-South

quantum-south

Beoordeel API:

Beoordeling: 5 - Stemmen: 1

README

Introduction

There are three things that you must include in every API call.

BASE-URLIt is the root URL of the QS API that needs to be used to access the API endpoints. This URL is https://api.quantum-south.com/
TOKEN ****A 40-character alpha-numeric string that gives you access to use the API. It must be included in the Header as follows: Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
RESOURCE This parameter specifies the problem to be addressed. In other words, it refers to the QS product that will be consumed. BPP or WB are two possible values for this parameter, which stand for Bin-Packing Problem and Weight and Balance respectively.

With that in mind, the next step is to send a POST or GET request to api.quantum-south.com with the appropriate values set, as follows:

https://api.quantum-south.com/{RESOURCE}/
**Header:** Authorization: Token {YOUR-API-TOKEN}

APSO - A Bin Packing Problem solution

The API has three endpoints:

1. POST {BASE-URL}/BPP/

This endpoint is used to initiate a new job process. The client sends a JSON payload containing the following fields:

{
    "flight_weight_capacity": 80000,
    "containers": [
        {
            "type": "PMP",
            "config": 2
        },
        {
            "type": "RKN",
            "config": 5
        },
				{
            "type": "BULK",
            "config": 1
        }
    ],
		"awbs": [
				{
            "type": ["BULK"],
						"priority": 517000,
						"awb_number": 61555255,
						"shc": ["OFD"],
						"weight": 77.8,
						"dimensions": ["120x80x108x1 Cms"]
        },
				{
            "type": [],
						"priority": 658000,
						"awb_number": 31254958,
						"weight": 47.4,
						"dimensions": ["80x62x84x1 Cms", "118x78x63x1 Cms", "48x48x60x5 Cms"]
        },
				{
            "type": ["PMP-1"],
						"priority": 517000,
						"awb_number": 415767211,
						"shc": ["EAP","ECP", "MAC", "BIG", "XPS"],
						"weight": 104.2
        },
				{
            "type": ["SSPD"],
            "uld_identifiers": ["PMC87669IB", "PMC76227IB"],
						"priority": 5400,
						"awb_number": 98117222,
						"weight": 98.0
        }
		]
}

Parameter Name	Compulsory	Type	Description	Example
flight_weight_capacity	Yes	Integer	The weight capacity of the flight in kg.	5099
containers	Yes	List of Containers	All available containers that can be loaded.	[ Container, Container, Container ]
awbs	Yes	List of AWBs	All available AWBs to load.	[AWB, AWB, AWB]

Container: A Container will be submitted through a List of Containers. Each container consists of the following schema:

Compulsory	Type	Description	Example
type	Yes	String	ULD type code or BULK. These parameter must be one of the following values: PMP, PAG, PAJ, AKE, RKN, AKH, PKC, RAP or BULK.

config	Yes	Integer	Quantity of ULDs of the type that can be put into the flight.

AWB: An AWB will be submitted through a List of AWBs. Each AWB consists of the following scheme:

Parameter Name	Compulsory	Type	Description	Example
	type	Yes	List of strings	This parameter is always a list of strings. Said list can have different length.

If it does not contain any elements, it means that the AWB is loose cargo.

In case you have 1 long, then there are 3 valid options:
A. The list only has the "BULK" element.
B. The list only has the "SSPD" element.
C. The list contains an element with format "&lt;ULD type&gt;-&lt;quantity&gt;". 

In case the list has length n, all elements of the list must have the format “&lt;ULD type&gt;-&lt;quantity&gt;”. | Examples:
- [”PAG-2”, “AKE-3”]
- [”BULK”]
- [”PAG-2”]
- []
- [“SSPD”] |
| uld_identifiers | If the parameter type is equal to [”SSPD”], this parameter must be sent. Otherwise it should NOT be passed. | List of strings | If the AWB is part of an already built ULD, this field is the ULD Identifier of the ULD.
A single AWB can be divided among many already built ULDs. In this case, this field must be a list with all the identifiers of the aforementioned ULDs. | [”AKE07103IB”, “PMC22100IB”, “PMC22633IB”]

 |
| priority | Yes | Integer | AWB priority number. | 517000 |
| awb_number | Yes | Integer | Unique identifier for the AWB. | 61555255 |
| shc | No | List of String | An IATA or company-specific code can be used as a SHC for an AWB. Multiple SHCs can be assigned to an AWB, but it is also possible for an AWB to have no SHC. | [”EAP”, ”ECP”, ”MAC”, ”BIG”, ”XPS”] |
| weight | Yes | Float | The weight of the entire AWB in kilograms. | 77.8 |
| dimensions | If the parameter type is equal to [”BULK”] or [], this parameter must be sent. Otherwise it should NOT be passed.
 | List of Strings | This refers to the measurements of each individual piece included in the AWB, which are specified in centimeters. A "piece type" refers to a group of pieces that have identical dimensions. A single AWB can contain numerous piece types, each with its unique set of dimensions. If there are multiple piece types, they should be passed in a list of strings with a specific format.

The format must follow the following string scheme:
 
1. Three integers separated by "x" that represent the dimensions of the piece type in length, width, and height.

2. An integer preceeded by “x” that indicates the number of pieces of that type.

3. The word "Cms", which indicates that the dimensions are given in centimeters.

The first and second parts of the code must be concatenated without sp. The second and third parts of the code must be separated by a single space. | [”1-80x62x84 C”, “1-118x78x63 C”, “5-48x48x60 C”] |
|  |  |  | 
 |  |

The server responds with a JSON payload containing a unique job_id that the client can use to identify the job, as well as other useful information.

{
    "job_id": "123456",
		"created_at": "*2023-02-22T15:30:00.000Z*",
		"status": "created",
		"data": {
		    "flight_weight_capacity": 80000,
		    "containers": [
		        {
		            "type": "PMP",
		            "config": 2
		        },
		        {
		            "type": "RKN",
		            "config": 5
		        },
						{
		            "type": "BULK",
		            "config": 1
		        }
		    ],
				"awbs": [
						{
		            "type": ["BULK"],
								"priority": 517000,
								"awb_number": 61555255,
								"shc": ["OFD"],
								"weight": 77.8,
								"dimensions": ["120x80x108x1 Cms"]
		        },
						{
		            "type": [],
								"priority": 658000,
								"awb_number": 31254958,
								"weight": 47.4,
								"dimensions": ["80x62x84x1 Cms", "118x78x63x1 Cms", "48x48x60x5 Cms"]
		        },
						{
		            "type": ["PMP-1"],
		            "priority": 517000,
								"awb_number": 415767211,
								"shc": ["EAP","ECP", "MAC", "BIG", "XPS"],
								"weight": 104.2
		        },
						{
		            "type": ["SSPD"],
		            "uld_identifiers": ["PMC87669IB", "PMC76227IB"],
								"priority": 5400,
								"awb_number": 98117222,
								"weight": 98.0
		        }				
				]
		}
}

Response Schema	Type	Description	Example
job_id	String	This is a unique identifier assigned by the server to the job triggered by the POST request. This identifier can be used to track the status of the job and retrieve the generated job later.	123456
created_at	String	This parameter indicates the date and time when the job was initiated by the server. The date and time format is ISO 8601. Which means, the format is YYYY-MM-DDTHH:mm:ss.sssZ

Query example

**curl** -X POST \
  https://api.quantum-south.com/BPP/ \
  -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' \
  -H 'Content-Type: application/json' \
  -d '{
    "flight_weight_capacity": 80000,
    "containers": [
        {
            "type": "PMP",
            "config": 2
        },
        {
            "type": "RKN",
            "config": 5
        },
				{
            "type": "BULK",
            "config": 1
        }
    ],
		"awbs": [
				{
            "type": ["BULK"],
						"priority": 517000,
						"awb_number": 61555255,
						"shc": ["OFD"],
						"weight": 77.8,
						"dimensions": ["120x80x108x1 Cms"]
        },
				{
            "type": [],
						"priority": 658000,
						"awb_number": 31254958,
						"weight": 47.4,
						"dimensions": ["80x62x84x1 Cms", "118x78x63x1 Cms", "48x48x60x5 Cms"]
        },
				{
            "type": ["PMP-1"],
            "priority": 517000,
						"awb_number": 415767211,
						"shc": ["EAP","ECP", "MAC", "BIG", "XPS"],
						"weight": 104.2
        },
				{
            "type": ["SSPD"],
            "uld_identifiers": ["PMC87669IB", "PMC76227IB"],
						"priority": 5400,
						"awb_number": 98117222,
						"weight": 98.0
        }
		]
}'

2. GET {BASE-URL}/BPP/{JOB-ID}/status/

This endpoint is used to check the status of the job. The job_id is obtained from the response of the previous /BPP/ endpoint.

The server responds with a JSON payload containing the status of the job:

{
    "job_id": "123456",
		"status": "in_progress",
		"created_at": "2023-02-22T15:30:00.000Z"
}

Response Schema	Type	Description	Example
job_id	String	This is a unique identifier assigned by the server to the job triggered by the POST request. This identifier can be used to track the status of the job and retrieve the generated job later.	123456
created_at	String	This parameter indicates the date and time when the job was initiated by the server. The date and time format is ISO 8601. Which means, the format is YYYY-MM-DDTHH:mm:ss.sssZ

If the requested job_id is invalid or has expired, the server responds with a 404 Not Found status code.

Query example

**curl** -X GET \
  https://api.quantum-south.com/BPP/123456/status/ \
  -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'

3. GET {BASE-URL}/WB/{JOB-ID}/download/

This endpoint is used to download the completed job. The job_id is obtained from the response of the previous /BPP/ endpoint, and the result can only be downloaded if its status is “finished”.

The server responds with a JSON payload containing the status of the job:

{
    "job_id": "123456",
		"status": "in_progress",
		"created_at": "2023-02-22T15:30:00.000Z",
		"data": {
		    "flight_weight_capacity": 80000,
		    "containers": [
		        {
		            "type": "PMP",
		            "config": 2
		        },
		        {
		            "type": "RKN",
		            "config": 5
		        },
						{
		            "type": "BULK",
		            "config": 1
		        }
		    ],
				"awbs": [
						{
		            "type": ["BULK"],
								"priority": 517000,
								"awb_number": 61555255,
								"shc": ["OFD"],
								"weight": 77.8,
								"dimensions": ["120x80x108x1 Cms"]
		        },
						{
		            "type": [],
								"priority": 658000,
								"awb_number": 31254958,
								"weight": 47.4,
								"dimensions": ["80x62x84x1 Cms", "118x78x63x1 Cms", "48x48x60x5 Cms"]
		        },
						{
		            "type": ["PMP-1"],
		            "priority": 517000,
								"awb_number": 415767211,
								"shc": ["EAP","ECP", "MAC", "BIG", "XPS"],
								"weight": 104.2
		        },
						{
		            "type": ["SSPD"],
		            "uld_identifiers": ["PMC87669IB", "PMC76227IB"],
								"priority": 5400,
								"awb_number": 98117222,
								"weight": 98.0
		        }
				]
		},
		"results": {
				"items": [
						{
				       "pallet_id": null,
				       "pallet_type": "BULK",
				       "item_id": 61555255-0,
				       "position": [0.0, 0.0, 0.0],
				       "dimensions": [120.0, 80.0, 108.0]
				    },
				    {
				       "pallet_id": 1,
				       "pallet_type": "RKN",
				       "item_id": 31254958-0,
				       "position": [80.0, 0.0, 0.0],
				       "dimensions": [80.0, 62.0, 84.0]
				    }
					],
				"intacts": [
						{
							 "awb_number": 517000	
						},
						{
							 "uld_identifiers": ["PMC87669IB", "PMC76227IB"]
						}
				]
		}
}

Response Schema	Type	Description	Example
job_id	String	This is a unique identifier assigned by the server to the job triggered by the POST request. This identifier can be used to track the status of the job and retrieve the generated job later.	123456
created_at	String	This parameter indicates the date and time when the job was initiated by the server. The date and time format is ISO 8601. Which means, the format is YYYY-MM-DDTHH:mm:ss.sssZ

where YYYY
is the year, MM
is the month, DD
is the day, THH:mm:ss.sss
is the time in hours, minutes, seconds, and milliseconds, and Z
is the time zone offset from UTC. | 2023-02-22T15:30:00.000Z |
| status | String | This parameter indicates the current status of the job. Possible values for this parameter could be started, enqueued processing, failed or finished. This parameter can be used to check the progress of the job and determine if the job is ready to be downloaded. | created |
| data | Object | The JSON object that was originally sent to trigger the request. | Observe the example that is situated above. |
| results | Object | This parameter contains the results of the processed job. It represents the list of selected containers that should be loaded onto the aircraft alongside the how the AWBs were allocated among the containers and where to place each piece of an AWB inside each container to optimize the flight. If the status parameter is not finished, then this parameter may not be present. | Observe the example that is situated above. |

Result: The result of the processed job will be accessed through this object. More specifically, it has the following scheme:

Type	Description	Example
items	List of Items	List of dictionaries that represents the disggregated oieces of all the selected AWB that were passed as loose cargo or for BULK (”type”: [] or [”BULK”]).
intacts	List of Intacts	List of dictionaries that represents all the selected AWBs that were passed as not loose cargo
viz-url	String	Url to the visual representations of the loaded ULDs.

- *Item:* Is an individual piece of an AWB. Its scheme is as follows:
    
    
    | Response Schema | Type | Description | Example |
    | --- | --- | --- | --- |
    | pallet_type | String | ULD type code or BULK. These parameter must be one of the following values: PMP, PAG, PAJ, AKE, RKN, AKH, PKC, RAP or BULK. | “PMP” |
    | pallet_id | Integer | Number that identifies a specific ULD where the piece was placed into.
    
    This field is null if the pallet_type is “BULK”. | 1 |
    | item_id  | String | Identifier of a piece of an AWB that follows the format &lt;awb_number&gt;-&lt;id&gt; | 31254958-0 |
    | position | List | List of three elements that indicates the relative position of a piece within a ULD.
    
    The format of this field is [x,y,z] where:
    - x: position on the x axis.
    - y: position on the y axis.
    - z: position on the z axis. | [10,0,0] |
    | dimensions | List | Three element list that indicates the dimensions of the piece. It follows the format [x_dim, y_dim, z_dim] where:
    - x_dim: dimension along the x axis. 
    - y_dim: dimension along the y axis.
    - z_dim: dimension along the z axis.
    
    This field is useful to determine the rotation of the piece. | [80.0, 62.0, 84.0] |
- *Intact:* Intact is an object that represents AWBs that were not passed as loose cargo. This object consists of a single key-value tuple. The key must be either awb_number or uld_dientifiers, but not both:
    
    
    | Response Schema Options | Type | Description | Example |
    | --- | --- | --- | --- |
    | awb_number | Integer | Number that identifies the intact ULDs group. If the type of the intact ULDs is SSPD , this field won’t be present. | 517000 |
    | uld_dientifiers | List | If the AWB is part of an already built ULD, this field is the ULD Identifier of the ULD.
    A single AWB can be divided among many already built ULDs. In this case, this field must be a list with all the identifiers of the aforementioned ULDs.
    
    This field will be present only if the type of the AWB is SSPD . | ["PMC87669IB", "PMC76227IB"]	 |

If the requested job_id is invalid, has expired, or the job process has not yet completed, the server responds with a 404 Not Found or 409 Conflict status code, respectively.

Query example

**curl** -X GET \
  https://api.quantum-south.com/BPP/123456/download/ \
  -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'

Summarizing

The following is a description of the typical lifecycle for generating and downloading a job:

The client sends a POST {BASE-URL}/BPP request to initiate a new job process.
The server responds with a job_id.
The client periodically sends a GET {BASE-URL}/BPP/{job_id}/status request to check the status of the job.
If the status is **started**, **enqueued** or processing the client repeats step 3 at the specified interval until the status changes to **finished** or failed.
If the status is **finished**, the client sends a GET {BASE-URL}/BPP/{job_id}/download request to download the completed job.

Costs and API Quotas

As described in the section titled “Obtaining an API Token” you can obtain an API token by contacting our customer success team at info@quantum-south.com. This token will allow you to authenticate your requests and gain access to any of Quantum-South’s products.

All of our products are available through a job polling lifecycle. So, each time you create a job with the provided token for any of our products, this job will be logged in our system. After all, our sales team will contact you with a receipt specifying every call that you push. Finally you will be charged for each of the API jobs you trigger. In other words, it is a pay-par use API. You trigger what you need, and we will charge you later.

Contact our sales team to provide you detailed information about how much it will cost each API job at info@quantum-south.com.

Customized Solutions and Support

We understand that our products may not fully meet your needs, or there may be additional restrictions that we haven’t considered. If this is the case, we encourage you to reach out to our customer success team so that we can work together to find a solution.

Our team is dedicated to ensuring that our customers have the best experience possible with our products, and we are always open to feedback and suggestions for improvement. So, if you have any concerns or questions about our products, please don’t hesitate to contact us at info@quantum-south.com. We are here to help and look forward to hearing from you.