Oficjalna dokumentacja API Goodloading

API – opis danych

Łączenie się z backendem aplikacji

Aby połączyć się z backendem aplikacji, należy wprowadzić token.

URL: https://api.goodloading.com/api/external/calculation

POST

Request

Request Headers

Nazwa Wartość Wymagane Opis
Authorization Bearer {access_token} Tak Klucz do autoryzacji
Content-type application/json Tak  

Request Body

Pole Typ Wymagane Wartość
name string Nie Nazwa projektu
note string Nie Opis projektu
loads array of Loads Tak Tablica z ładunkami
loadingSpaces array of Loading Spaces Tak Tablica z przestrzeniami ładunkowymi
options json Tak Opcje algorytmu

Opcje algorytmu (options)

Pole Typ Wymagane Wartość
allowOverweight boolean Nie Ustawienie wartości na true spowoduje, że ładunki nie będą ustawiane w przestrzeni ładunkowej jeżeli waga przekroczy dopuszczalną ładowność. Domyślna wartość: false.
unit string Nie Jednostki podanych wymiarów. Można wybrać jedną z dwóch wartości:
– cm
– lb
Domyślna wartość: “cm”
keepLoadsTogether boolean Nie Ustawienie wartości na true powoduje, że ładunki z danej grupy będą ustawiane razem. Domyślna wartość: false.
newAlgorithm boolean Nie Ustawienie wartości na true powoduje, że zostanie użyty nowy algorytm. Domyślna wartość: true.
loadingOrder string Nie Wartości:
“default” :na podstawie kolejności dodawania obiektów ładunkowych
“weight” : na podstawie wagi ładunków
“volume”: na podstawie objętości ładunków
“priority” :na podstawie priorytetu ładunków
„barrier”: na podstawie identyfikatora zamówienia ładunków, oddzielonych barierami
multiStops boolean Nie Ustawienie wartości na false powoduje, że multi przestaje być brane pod uwagę. Domyślna wartość: false.
arrangeOptimally boolean Nie Włączenie funkcji „układaj optymalnie” spowoduje, że algorytm będzie szukał dla ładunków ułożenia z zachowaniem jak największej wolnej przestrzeni, bez względu na kolejność ich dodania. Domyślna wartość: false.

Dane dotyczące ładunku (loads)

Nazwa Wartość Wymagane Opis
id number Nie ID ładunku
quantity integer Tak Ilość ładunków. Musi być liczbą całkowitą większą od 0.
name string Tak Nazwa ładunku
length number Tak Długość jednego ładunku. Musi być większa od 0. Dotyczy wyłącznie sześcianów i rur.
width number Tak Szerokość jednego ładunku. Musi być większa od 0. Dotyczy wyłącznie sześcianów
height number Tak Wysokość jednego ładunku. Musi być większa od 0. Dotyczy wyłącznie sześcianów i beczek.
diameter number Tak Średnica ładunku. Musi być większa od zera. Dotyczy wyłącznie rur i beczek.
weight number Tak Waga jednego ładunku. Musi być większa lub równa 0.
priority integer Nie Priorytet ładunku. Wartość musi być liczbą całkowitą większą lub równą 0. Wartość domyślna: 0.
stacking boolean / integer Nie Piętrowanie ładunku. Wartość false oznacza, że jest nie piętrowalny, wartość true oznacza, że jest piętrowalny. Podanie liczby całkowitej większej od 0 oznacza, że ładunek jest piętrowalny z ograniczoną liczbą pięter. Wartość domyślna: true.
allowToRotate boolean Nie Przyjmuje true lub false. Ustawienie wartości na true pozwala przy obliczeniach zamieniać szerokość z długością, czyli obracać ładunek względem podstawy. Dotyczy: sześcianów i rur. Wartość domyślna true.
rotateFreely boolean Nie Przyjmuje true lub false. Ustawienie wartości umożliwia obracanie ładunkiem w dowolną stronę. Dotyczy wyłącznie sześcianów. Wartość domyślna false.
color string Nie Wczytaj kolor ładunku w formacie kodu szesnastkowego (hex code).
origin {id: number,
name: string}		 Nie Miejsce załadunku ładunku (multi stops)
destination {id: number,
name: string}		 Nie Dotyczy funkcji multistop i oznacza miejsce rozładunku.
pctSupport number Nie Procent obsługiwanej powierzchni ładunku. Umożliwia piętrowanie ładunku o większym polu podstawy, na ładunku o mniejszym polu podstawy.
alongFloor boolean Nie Ustawienie wartości true powoduje, że ładunki, zanim zostaną spiętrowane, ułożą się wzdłuż podłogi. Przyjmuje prawdę lub fałsz.
maxWeightOnTop number Nie Maksymalny ciężar, jaki można umieścić na ładunku.
boxesBelowAllowed array of numbers Nie Tablica id pudełek, które można umieścić pod dodawanym ładunkiem.
loadType number Nie 0:ładunek sześcienny, 1:beczka, 2:rura
Domyślnie “0”
order number Nie ID zamówienia ładunku (brany pod uwagę tylko wtedy, gdy options.loadingOrder = „barrier”)

Dane przestrzeni ładunkowej (loadingSpace)

Nazwa Wartość Wymagane Opis
quantity integer Tak Liczba przestrzeni ładunkowych. Musi być liczbą całkowitą większą niż 0
name string Tak Nazwa przestrzeni ładunkowej
type string Nie Typ przestrzeni ładunkowej. Można ustawić jedną z następujących wartości:
– vehicle [domyślnie]
– sea
– air x
– air y
– pallet
parts array Tak Tablica przestrzeni przestrzeni ładunkowej. Np. zestaw będzie miał dwie części.
part.length number Tak Długość części przestrzeni ładunkowej. Musi być większa niż 0.
part.width number Tak Szerokość części przestrzeni ładunkowej. Musi być większa niż 0.
part.height number Tak Wysokość części przestrzeni ładunkowej. Musi być większa niż 0.
part.baseHeight number Nie Wysokość podstawy palety
part.limit number Tak Ładowność częściowa przestrzeni ładunkowej. Musi być większa niż 0
part.axis array Nie Tablica z osiami przestrzeni ładunkowej. Jeżeli jest podana musi zawierać dokładnie dwa albo trzy elementy.
part.axi.distanceFromSpaceFront number Tak Odległość osi od początku przestrzeni ładunkowej, wartość ujemna, gdy oś znajduje się pod kabiną kierowcy.
part.axi.emptySpaceLoad number Tak Obciążenie osi przy pustej przestrzeni ładunkowej. Wartość musi być liczbą większą lub równą 0.
part.axi.maxLoad number Tak Najwyższe dopuszczalne obciążenie osi. Wartość musi być liczbą większą lub równą 0.
part.loadingSide string Nie Sposób załadunku przestrzeni ładunkowej. Można ustawić jedną z czterech wartości:
„back” [domyślne]
„top”
„left”
„right”
part.barrier object Nie Bariera w przestrzeni ładunkowej między rzędami ładunków (brana pod uwagę tylko wtedy, gdy options.loadingOrder = „barrier”).
part.barrier.thickness number Tak Grubość bariery
part.barrier.height number Nie Wysokość bariery
stops array Nie Seria przystanków
stop.id number Tak ID przystanku
stop.name string Tak Nazwa przystanku
stop.address string Nie Adres przystanku
stop.city string Nie Miasto przystanku
stop.country string Nie Kraj przystanku
stop.postalCode string Nie Kod pocztowy przystanku
stop.coordinates string Nie Współrzędne lokalizacji przystanku
stop.coordinates.lat number Tak Szerokość geograficzna przystanku
stop.coordinates.lon number Tak Długość geograficzna przystanku

Minimalne zapytanie (Request)

W minimalnej wersji zapytania do APi, należy zdefiniować:

  • wszystkie rodzaje oraz liczby ładunków, które chcemy przewieźć (loads)
  • wszystkie przestrzenie ładunkowe, które chcemy załadować.(loadingspaces)

Dla każdego ładunku oraz przestrzeni ładunkowej oddzielnie definiuje się wszystkie obowiązkowe parametry, zgodnie z opisem w punktach

Dokumentacja podaje również wartości domyślne dla parametrów nieobowiązkowych.

Nieobowiązkowo można podać parametry przetwarzania algorytmu, zgodnie z opisem

Opcje algorytmu (options)

W min. wersji zapytania wymagane jest podanie wszystkich 3 sekcji/ obiektów

  • loads
  • loadingSpaces
  • options

Przykład zapytania min.

{
    "loads": [
        {
            "quantity": 6,
            "name": "load 1",
            "length": 120,
            "width": 80,
            "height": 100,
            "weight": 100
        }
],
       "loadingSpaces": [
        {
            "quantity": 1,
            "name": "truck 1",
            "parts": [
                {
                    "length": 1300,
                    "width": 200,
                    "height": 200,
                    "limit": 24000
                }
            ]
        }
    ],
  "options": {
            }
}

Rezultat

1. Odpowiedź JSON – Response do zapytania min

2. Reprezentacja graficzna dla podanego przykładu

Domyślnie 6 takich samych ładunków zostało załadowanych do domyślnej przestrzeni ładunkowej “vehicle” i umieszczonych tuż przy kabinie kierowcy, począwszy od lewej strony.

Rozbudowane zapytanie o wartości opcjonalne (Request)

Wszystkie dane opcjonalne, domyślnie są ustawiane zgodnie z opisem w:

o ile użytkownik nie poda wprost żądanych wartości.

{
    "loads": [
        {
            "quantity": 6,
            "name": "load 1",
            "length": 120,
            "width": 80,
            "height": 100,
            "weight": 100,
            "priority": 0,
            "stacking": true,
            "allowToRotate": true,
            "rotateFreely": false,
            "alongFlooor": false,
            "loadType": 0
        }
],
       "loadingSpaces": [
        {
            "quantity": 1,
            "name": "truck 1",
            "type": "vehicle",
            "parts": [
                {
                    "length": 1300,
                    "width": 200,
                    "height": 200,
                    "limit": 24000,
                    "loadingSide": "back"
                 }
                ]
            }
       ],
        "options": {
            "allowOverweight": false,
            "unit": "cm",
            "keepLoadsTogether": false,
            "newAlgorithm": true,
            "loadingOrder": "default",
            "multiStops": false,
            "arrangeOptimally": false
     }
}

.

Rezultat

To samo ułożenie co w pkt Minimalne zapytanie (Request)

.

Response

Status HTTP Opis
200 Wynik obliczeń jest zwracany
400 Błąd walidacji danych wejściowych
401 Błąd autoryzacji
429 Przekroczono dopuszczalną liczbę zapytań

Response Body

Nazwa Typ Wartość
loadingSpaces array Tablica przestrzeni ładunkowych
loadingSpace.id integer Identyfikator przestrzeni ładunkowej
loadingSpace.name string Nazwa przestrzeni ładunkowej.
loadingSpace.type string Typ przestrzeni ładunkowej:
“vehicle”
“sea”
“air x”
“air y”
“pallet
loadingSpace.parts array Tablica części przestrzeni ładunkowej. Np. zestaw będzie składał się z dwóch części.
loadingSpace.part.length number Długość części przestrzeni ładunkowej.
loadingSpace.part.width number Szerokość części przestrzeni ładunkowej.
loadingSpace.part.height number Wysokość części przestrzeni ładunkowej.
loadingSpace.part.limit number Ładowność części przestrzeni ładunkowej.
loadinSpace.part.axis array Tablica osi dla danej części przestrzeni ładunkowej.
loadingSpace.part. axi.distanceFromSpaceFront number Odległość osi od początku danej części przestrzeni ładunkowej.
loadingSpace.part.
axi.emptySpaceLoad		 number Nacisk na oś przy pustej przestrzeni ładunkowej.
loadingSpace.part.
axi.maxLoad		 number Maksymalne dopuszczalne obciążenie osi.
loadingSpace.part.
axi.addedLoad		 number Nacisk na oś ułożonych ładunków.
loadingSpace.part.loads array Tablica ładunków ułożonych w danej części przestrzeni ładunkowej (single stop)
loadingSpace.part.stops array Tablica przystanków
loadinfSpace.part.stop.stopId number Identyfikator przystanku
loadingSpace.part.stop.name string Nazwa przystanku
loadingSpace.part.stop.summary json Podsumowanie danych dotyczących danego przystanku
loadingSpace.part.stop.summary.occupiedLdm number Liczba wykorzystanych metrów ładownych
loadingSpace.part.stop.summary.freeLdm number Liczba wolnych metrów ładownych
loadingSpace.part.stop.summary.occupiedSurface number Zajęta powierzchnia (w mm kw)
loadingSpace.part.stop.summary.freeSurface number Wolna powierzchnia (w mm kw)
loadingSpace.part.stop.summary.occupiedVolume number Zajęta objętość (w mm sześciennych)
loadingSpace.part.stop.summary.freeVolume number Wolna objętość (w mm sześciennych)
loadingSpace.part.stop.summary.percentLdmUsd number Zajęte metry ładowne – procentowo
loadingSpace.part.stop.summary.percentVolumeUsd number Zajęta objętość – procentowo
loadingSpace.part.stop.loads array Tablica ładunków dla danego przystanku.
loadingSpace.part.load.id number Identyfikator ładunku
loadingSpace.part.load.allowToRotate boolean Pozwolenie na obracanie ładunku po jego podstawie
loadingSpace.part.load.quantity integer Liczba ładunków
loadingSpace.part.load.name string Nazwa ładunku
loadingSpace.part.load.priority integer Priorytet ładunku
loadingSpace.part.load.weight number Waga ładunku.
loadingSpace.part.load.length number Długość ładunku.
loadingSpace.part.load.width number Szerokość ładunku.
loadingSpace.part.load.height number Wysokość ładunku.
loadingSpace.part.load.stacking boolean / integer Pozwolenie na piętrowanie ładunku/ liczba pięter
loadingSpace.part.load.placement array Tablica z rozłożeniem ładunków w danej części przestrzeni ładunkowej.
loadingSpace.part.load.placement.length number Długość ustawionego ładunku. Wartości długości i szerokości mogą być zamienione miejscami w stosunku do pierwotnych wartości,, jeśli opcja „allowToRotate” jest ustawiona na „true”.
loadingSpace.part.load.placement.width number Szerokość ustawionego ładunku. Wartości długości i szerokości mogą być zamienione miejscami w stosunku do pierwotnych wartości,, jeśli opcja „allowToRotate” jest ustawiona na „true”.
loadingSpace.part.load.placement.height number Wysokość ustawionego ładunku.
loadingSpace.part.load.placement.position json Pozycja ładunku w przestrzeni ładunkowej, względem osi x, y, z. Patrząc od początku przestrzeni, pozycje x: 0, y: 0, z: 0 to prawy dolny róg przestrzeni.
Przyjęte wskazanie osi:
x: wzdłuż szerokości przestrzeni
y: wzdłuż wysokości przestrzeni
z: wzdłuż długości przestrzeni
loadingSpace.part.load.placement.loadsPerAxis json Liczba ładunków ułożonych wzdłuż poszczególnych osi
loadingSpace.part.load.placement.loadsPerAxis.x integer Liczba ładunków wzdłuż osi x.
loadingSpace.part.load.placement.loadsPerAxis.y integer Liczba ładunków wzdłuż osi Y.
loadingSpace.part.load.placement.loadsPerAxis.z integer Liczba obciążeń wzdłuż osi Z.
loadingSpace.part.load.placement.position.x numer Pozycja ładunku na osi X
loadingSpace.part.load.placement.position.y numer Pozycja ładunku na osi Y
loadingSpace.part.load.placement.position.z numer Pozycja ładunku na osi Z
loadingSpace.part.summary json Podsumowanie dla danej części przestrzeni ładunkowej.
loadingSpace.part.summary.occupiedLdm number Liczba wykorzystanych metrów ładownych
loadingSpace.part.summary.freeLdm number Liczba wolnych metrów ładownych
loadingSpace.part.summary.occupiedSurface number Zajęta powierzchnia (w mm kw)
loadingSpace.part.summary.freeSurface number Wolna powierzchnia (w mm kw)
loadingSpace.part.summary.occupiedVolume number Zajęta objętość (w mm sześciennych)
loadingSpace.part.summary.freeVolume number Wolna objętość (w mm sześciennych)
notFittedLoads array Ładunki, które nie zmieściły się w żadnej przestrzeni ładunkowej
notFittedLoad.id number Identyfikator ładunku, który się nie zmieścił w przestrzeni ładunkowej
notFittedLoad.length number Długość ładunku, który się nie zmieścił w przestrzeni ładunkowej
notFittedLoad.width number Szerokość ładunku
notFittedLoad.height number Wysokość ładunku
notFittedLoad.weight number Waga ładunku
notFittedLoad.quantity integer Liczba ładunków
notFittedLoad.priorytet integer Priorytet ładunku
notFittedLoad.name string Nazwa ładunku
notFittedLoad.stacking boolean/ integer Pozwolenie na piętrowanie ładunku/ liczba pięter
notFittedLoad.allowToRotate boolean Pozwolenie na obracanie ładunku względem podstawy
options json Opcje algorytmu
options.allowToOverwieght boolean Wartość mówiąca, czy można przekroczyć dopuszczalną ładowność
options.unit string Jednostka podawanych wymiarów
options.keepLoadsTogether boolean Wartość mówiąca, czy ładunki z danej grupy są ustawiane razem.
_links array Tablica dalszych możliwych działań
link.rel string Relacja
link.href string Link do wizualizacji projektu w aplikacji Goodloading

Response do zapytania min

Response dla zapytania – Minimalne zapytanie (Request)

Opis parametrów dla Response, zgodnie z Response Body

Ładunki w przestrzeni ładunkowej układane są wzdłuż osi x,y,z – w pojeździe, począwszy od lewej strony kabiny kierowcy

Od powyższej zasady jest tylko 1 wyjątek- układanie z wykorzystaniem barier 8. Bariery

Response

{
    "loadingSpaces": [
        {
            "id": 1,
            "name": "truck 1",
            "parts": [
                {
                    "height": 200,
                    "length": 1300,
                    "width": 200,
                    "limit": 24000,
                    "loads": [
                        {
                            "id": 1,
                            "allowToRotate": true,
                            "stacking": true,
                            "name": "load 1",
                            "loadType": 0,
                            "priority": 0,
                            "quantity": 6,
                            "width": 120,
                            "length": 80,
                            "height": 100,
                            "weight": 100,
                            "diameter": 0,
                            "origin": null,
                            "destination": null,
                            "pctSupport": 100,
                            "alongFloor": false,
                            "boxesBelowAllowed": [],
                            "color": 6989903,
                            "placement": [
                                {
                                    "height": 100,
                                    "length": 80,
                                    "width": 120,
                                    "diameter": 0,
                                    "loadsPerAxis": {
                                        "x": 1,
                                        "y": 2,
                                        "z": 1
                                    },
                                    "position": {
                                        "x": 0,
                                        "y": 0,
                                        "z": 0
                                    },
                                    "cubeId": 0
                                },
                                {
                                    "height": 100,
                                    "length": 120,
                                    "width": 80,
                                    "diameter": 0,
                                    "loadsPerAxis": {
                                        "x": 1,
                                        "y": 2,
                                        "z": 1
                                    },
                                    "position": {
                                        "x": 120,
                                        "y": 0,
                                        "z": 0
                                    },
                                    "cubeId": 0
                                },
                                {
                                    "height": 100,
                                    "length": 80,
                                    "width": 120,
                                    "diameter": 0,
                                    "loadsPerAxis": {
                                        "x": 1,
                                        "y": 2,
                                        "z": 1
                                    },
                                    "position": {
                                        "x": 0,
                                        "y": 0,
                                        "z": 80
                                    },
                                    "cubeId": 0
                                }
                            ]
                        }
                    ],
                    "loadingSide": "back",
                    "summary": {
                        "freeLdm": 1140,
                        "occupiedLdm": 160,
                        "freeSurface": 23120000,
                        "occupiedSurface": 2880000,
                        "freeVolume": 462400000000,
                        "occupiedVolume": 57600000000,
                        "percentLdmUsd": 12.307692307692308,
                        "percentVolumeUsd": 11.076923076923077,
                        "totalLoadsWeight": 600
                    },
                    "axis": []
                }
            ],
            "type": "vehicle"
        }
    ],
    "notFittedLoads": [],
    "options": {
        "allowOverweight": false,
        "unit": "cm",
        "keepLoadsTogether": false,
        "newAlgorithm": true,
        "arrangeOptimally": false,
        "loadingOrder": "default",
        "keepGroupsInGivenSpaces": false,
        "isMagnetOn": false,
        "multiStops": false,
        "includeSavedLoadingSpaces": false,
        "additionOrder": true,
        "userOrder": false,
        "volumeOrder": false,
        "weightOrder": false
    },
    "_links": [
        {
            "rel": "preview",   ref":https://app.goodloading.com/session?id=e9197db7-acad-4fc7-b58a-f5b26edfdabc&pref=opt-names-opened"
        }
    ]
}

Wizualizacja