Language
+49 40 / 39 90 34 94 contact@herberg-systems.com

About Cargo API
Data exchange made easy

Integrate the About Cargo functionalities fast and easy in your own IT

The About Cargo API

The About Cargo API is an interface with which you can request all functions and data via a REST-interface. Our API offers you the possibility to use the About Cargo API as a part of your internal IT or software solution. The About Cargo API is a collection of HTTP RPC methods which has the following form: https://app.about-cargo.com/…

The methods of the About Cargo API allows to request the estimated arrival time of ships and to process the times in your own IT. This means that you can exchange the data in machine-readable form with our service without having the need for an user interface.

The benefit: You can process the data digitally for your own purpose without the necessity of human interaction.

For example, every 10 minutes you can check whether the arrival time of a ship has changed and, if necessary, inform the responsible employee by means of your IT information.

The query of the API will be done via the Internet as About Cargo is a cloud service. To use the API, your client (the polling site) needs an internet connection via the HTTPS protocol.

In which language and with which tools your client will be implemented depends on your internal IT structure. If you use Microsoft servers or Microsoft computers, you can develop an About Cargo API for example in Microsoft DotNET. You can find an example here.

How does the API work?

About Cargo is a cloud service, which regularly updates the ship position and processes further information to predict the arrival and departure time of a container ship. The system is processing the position and provides internally in the database the current arrival time. The client sends its request to the system and receives as a response the data back. The systems do not estimate a fixed arrival time but a horizon of expectation. One example: The ship MS Anna is on the route from Santos (Brazil) to Rotterdam. The algorithm estimates the following data:

Probable arrival time

This is the average probable time of arrival resulting from the last position report. Example: The ship arrives on 12.7.2018 at 9:00.

Accuracy of arrival time

This value indicates how the arrival time is estimated. If, for example, the accuracy is four hours the horizon of expectation is on the 12th of July 2018 +/- four hours, between 5 am to 1 pm.

Timeliness of arrival times

This value indicates how old the prediction is. Example: A value of five hours indicates that the data basis of the assessment is five hours old.

Earliest probable arrival time

With the earliest probable arrival time, the algorithm estimates the earliest time the liner will manage to uphold.

Planned arrival and departure times

These are the times the shipping companies publish on their homepages. You can also type these times manually via the API in the system. Thus, you will receive an alert, if a ship is delayed.

Latest probable arrival time

This indicates the time, the algorithm predicts in the worst case as the arrival time of the liner

How to use the About Cargo API

Step 1: Authentication process to access the About-cargo API

For accessing the About Cargo-API an access key is necessary. For acquiring the key, you may contact the Herberg Systems team. We also provide free access for testing purposes. The user will be given a username and password which will be needed to get a JWT token to access the API.

After receiving the user data following steps are needed, to access the About Cargo-API:

  1. The client may first request a JWT authorization token with the credentials (username, password).
  2. If the credentials are valid and the client is authorized to access the API, a JWT token is returned.
  3. The client can then access the About Cargo-API. To do this, the JWT token must be transferred in the request header. The JWT token is valid for 3600 seconds.
  4. If the token is valid, the results for the API request will be sent back to the client.
  5. If an API request is made with an expired JWT token, the user gets a "401 - JWT token expired" response. Then the user may request a new JWT authorization token as in step 1 explained.

In the following the steps will be explained:

 

1. Request for the token:

Before calling the API, the user must first request the token.

Send a post request to URL https://staging.about-cargo.com/api/token with the content-type set to application/json and body set as {“username”:”<username>”, “password”:”<password>”}

Please replace <username> and <password> with your actual credentials.

Sample request for token using Curl:

curl -X POST " https://staging.about-cargo.com/api/token" -H "accept: application/json" -H 
"Content-Type: application/json" -d "{ \"username\": \"<username>\", \"password\":
\"<password>\"}"

2. Sample token response:

 

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NDkxMTkzMDUsImV4cCI6MTU0OTEyMjkwNSwicm9sZXM
iOlsiUk9MRV9TVVBFUkFETUlOIiwiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoiU3VwZXJhZG1pbiJ9.pch9E7AOZPD-2hFxtgWVpdMw
l4fWWx2oknC8zDuQIMcajEXAtrKZGgCtbWxPwYDH9wrEswB66q3zC8BSDwsEloPXwfwP7f3tC7ZVNwRwb0Okdp6jTI46Fr3mTTKpOj
DGOwNKoj88FO8-ZYi_LUPIl2lKEWE5qkyTIzV3BVOOJdaOmvEknuIlJLxodwKIKLshk24npEwZhNEr_eCejFcyNoq-_gHpw9JPKILW
pMtKSrOHHcP6nrgxSFD6iYMyieWUevxohJ-j7g9rt3ITydP4t9udTtbSnXi9MbQriPYuSsygtraAcyId1Ii1QP7FigjitZgc9tXbzh
4-kCFyX28O2vT8D4zSQ12RPEO3Vm_3ZdivuOjYUKkSOMGYsjJrS9ySxyMzZqrsi_rX37VS2BqCYu5VRlNOIdxg_JwH1MJqrAoe_6SB
I9tFTltgfMnBjCBMvVmD5z5noGs0IzSmBOyiPYRJAR23A88BzONKf-ybgNWVKSzU0M4vZLjQtkCB_j8QbFsbyRk4gqpmog5FZzNgUO
9NFymPm5g3I3EuOoRJ_PzTCLxKbX5JdM6Y_8mOnrc-wsE7wOskK--DhgOiCZiI_Fwc9fCa2RscRDb0ph-N4QuVrs98yyA3mT3jC-i_
FvCzuY9SGiLHgblpa_BzcaacCTXEQnZ-PX_eqlp_1zjcSWY"
}

 

3. Token usage:

The same authentication token should be reused in every request until it expires. The token must be included in the authorization header after the keyword bearer in every API request. You can view all available API calls at https://staging.about-cargo.com/api.


Sample API request for all ships:

curl -X GET " https://staging.about-cargo.com/api/vehicles" -H "accept: application/json" -H 
"Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NDkxMTkzMDUsImV4cCI6MTU0OTEyMj
kwNSwicm9sZXMiOlsiUk9MRV9TVVBFUkFETUlOIiwiUk9MRV9VU0VSIl0sInVzZXJuYW1lIjoiU3VwZXJhZG1pbiJ9.pch9E7AOZPD
-2hFxtgWVpdMwl4fWWx2oknC8zDuQIMcajEXAtrKZGgCtbWxPwYDH9wrEswB66q3zC8BSDwsEloPXwfwP7f3tC7ZVNwRwb0Okdp6jT
I46Fr3mTTKpOjDGOwNKoj88FO8-ZYi_LUPIl2lKEWE5qkyTIzV3BVOOJdaOmvEknuIlJLxodwKIKLshk24npEwZhNEr_eCejFcyNoq
-_gHpw9JPKILWpMtKSrOHHcP6nrgxSFD6iYMyieWUevxohJ-j7g9rt3ITydP4t9udTtbSnXi9MbQriPYuSsygtraAcyId1Ii1QP7Fi
gjitZgc9tXbzh4-kCFyX28O2vT8D4zSQ12RPEO3Vm_3ZdivuOjYUKkSOMGYsjJrS9ySxyMzZqrsi_rX37VS2BqCYu5VRlNOIdxg_Jw
H1MJqrAoe_6SBI9tFTltgfMnBjCBMvVmD5z5noGs0IzSmBOyiPYRJAR23A88BzONKf-ybgNWVKSzU0M4vZLjQtkCB_j8QbFsbyRk4g
qpmog5FZzNgUO9NFymPm5g3I3EuOoRJ_PzTCLxKbX5JdM6Y_8mOnrc-wsE7wOskK--DhgOiCZiI_Fwc9fCa2RscRDb0ph-N4QuVrs9
8yyA3mT3jC-i_FvCzuY9SGiLHgblpa_BzcaacCTXEQnZ-PX_eqlp_1zjcSWY"


4. Sample API response with the list of ships:

 

[
{
"id": 1,
"name": "ship 1",
"alias": "",
"identifier": "9683867",
"isActive": true,
"updatedDate": "2018-10-25T10:54:00+00:00",
"createdDate": "2018-09-28T12:19:17+00:00",
"type": "/api/vehicle_types/1",
"carrier": "/api/carriers/6"
},
{
"id": 2,
"name": "Ship 2",
"alias": "",
"identifier": "9717228",
"isActive": true,
"updatedDate": "2018-10-25T10:53:58+00:00",
"createdDate": "2018-09-28T12:19:17+00:00",
"type": "/api/vehicle_types/1",
"carrier": "/api/carriers/6"
},
]
Step 2: Activating the ship

Worldwide, there are approximately 5000 container vessels. We are only tracking those ships, that are relevant to our customers. Thus, we are be able to offer our services cost-effective. Therefore, ships need to be registered and activated. Once activated the positions of the ships are requested regularly.

First of all, the client needs to register a ship, when it is not yet registered in the system. As soon as there is a position, the algorithm calculates on request a horizon of expectation. The client can request this horizon of expectation.

In the following the steps for activation are described:

First, we request, if the ship is already registered.

GET http://195.201.103.57:3081/api/vehicles?imoNumber=91234567

If we do not get a set of data back, we are registering the ship. For registering we need the ID of the carrier the ship belongs to.

GET http://195.201.103.57:3081/api/carriers

for example replies with the following:

{
        "type_id": 1,
        "vehicle_ids": [
            591,
            1253
        ],
        "connection_ids": [
            2
        ],
        "id": 2,
        "name": "NYK",
        "is_active": true,
        "updated_date": null,
        "created_date": "2018-09-28T12:19:14+00:00"
    },

In this case, we are taking the carrier “NYK”, the ID is “2”. We are activating the ship as follows:

HTTP POST http://195.201.103.57:3081/api/vehicles
{
"type_id": 1,
"carrier_id": 2,
"name": "MS Anna",
"identifier": "91234567"
}

Here, type_id = 1 means that it is a seagoing vessel. The “identifier” is the IMO number of the ship.

 

Maybe a ship is already registered in the system, but not yet activated. In this case, the following steps need to be taken.

Use the IMO number to request a particular ship already registered in the About Cargo API:

GET https://staging.about-cargo.com/api/vehicles?imoNumber=91234567

The answer might look like as follows

[
{
"id": 1432,
"name": "MS Anna",
"alias": "Test 1",
"identifier": "99112233",
"isActive": false,
"activeUntil": "2019-01-31T00:00:00+00:00",
"updatedDate": "2019-01-12T10:11:13+00:00",
"createdDate": "2019-01-01T10:05:56+00:00",
"type": "/api/vehicle_types/1",
"carrier": "/api/carriers/3"
}
]

The attribute „isActive“ provides information about the activation status of the ship. Currently, the ship is inactive.

To activate the ship, execute the request:

PUT https://staging.about-cargo.com/api/vehicles/1432

In the body of the request set the attribute „isActive“ to „true“:

{
"isActive": true
}

The result is the activation of the ship in the system:

{
"id": 1432,
"name": "MS Anna",
"alias": "Test 1",
"identifier": "99112233",
"isActive": true,
"activeUntil": "2019-03-31T00:00:00+00:00",
"updatedDate": "2019-03-12T10:11:13+00:00",
"createdDate": "2019-01-01T10:05:56+00:00",
"type": "/api/vehicle_types/1",
"carrier": "/api/carriers/3"
}

Now the ship is active.

Step 3: Requesting the algorithm of the calculation

The system regularly requests the positions and calculates the ETA for the next port for all activated ships.

In this scenario, the client provides the information about the ship and the next destination port to directly request the calculation algorithm. Here, only the next arrival time is calculated.

GET http://195.201.103.57:3081/api/etas/calculate?imoNumber=91234567&unLoCode=BRIBB

responses with the horizon of expectation for the ship the IMO number 91234567 and the port Imbituba in Brasil:

{
    "id": 14,
    "eta_planned": null,
    "average": 1633,
    "minimum": 1410,
    "maximum": 1712,
    "median": 1598,
    "standard_deviation": 123,
    "accuracy": 246,
    "is_active": true,
    "updated_date": null,
    "created_date": "2018-10-26T15:51:07+00:00"
}

All times are in minutes. Which means the following:

Variable

Value

Equates to

Meaning

average

1633 minutes

27 hours 13 minutes

Average time to arrival

minimum

1410 minutes

23 hours 30 minutes

Minimum time to arrival

maximum

1712 minutes

28 hours 32 minutes

Maximum time to arrival

median

1598 minutes

26 hours 38 minutes

Median of the different values until the arrival

standard_deviation

123 minutes

2 hours 3 minutes

Standard deviation to arrival

In this case, if you take the average the is ETA is 27 hours +/- 2 hours. If you take the median it is 26 hours and 38 minutes +/- 2 hours.
If the ship is not activated, if there is no position or if it cannot be assigned to a service leg, a corresponding error message is returned.

 



Example for a REST-Client in C#

In this section, we'll show you how to implement a REST client in C #, which can be used to request the About Cargo API.

The About Cargo interface provides the data in JSON format. The class Rest client calls the interface and returns the data as a dynamic data object.

Following steps are necessary for a request via a REST client:

  1. You need to create a new instance
  2. Afterwards, you need to request a token for the About Cargo API
  3. Now, the REST client can request About Cargo

 

How to create an instance?

In the first step you create a new instance:

RestClient client = new RestClient();

 

How to receive a token?

To receive a sign-in token call the method

client.requestToken(<username>, <password>);

Replace the credentials <username> and <password>; with the log-in data. After a successful call, the token will be saved within the client-object.

 

How can I request specific data?

Afterwards, you can call the interface as follows:

 

var objects = client.get("vehicles");

or

var objects = client.get("etas/calculate?imoNumber=91234567&unLoCode=DEHAM");


Example code for the REST client in C#

using System;
using System.Net;
using System.IO;
using System.Text;
using System.Web.Helpers;
using System;
using System.Net;
using System.IO;
using System.Text;
using System.Web.Helpers;

namespace AboutCargoTrial
{
    /// <summary>
    /// This is a sample implementation for a REST client that is able to access 
    /// the AboutCargo API described at www.about-cargo.com.
    /// </summary>
    public class RestClient
    {
        /// <summary>
        /// The URL
        /// </summary>
        public string Url { get; set; }
        
        /// <summary>
        /// The JWT Token
        /// </summary>
        public string AccessToken { get;set; }
        
        /// <summary>
        /// Constructor
        /// Contains the fixed URL to the test instance base URL.
        /// </summary>
        public RestClient()
        {
            Url = "https://staging.about-cargo.com/api/";
        }
        
        /// <summary>
        /// Get data from the API.
        /// </summary>
        /// <param name="methodStr">The API method to be called</param>
        /// <returns>A dynamic object or null.</returns>
        public dynamic get (string methodStr)
        {
        	// define URI by adding the method to be called to the base URL
            var myUri = new Uri(new Uri(Url), methodStr);
            
            // configure request object to use the JWT access token
            var myWebRequest = WebRequest.Create(myUri);
			var myHttpWebRequest = (HttpWebRequest)myWebRequest;
			myHttpWebRequest.PreAuthenticate = true;
			myHttpWebRequest.Headers.Add("Authorization", "Bearer " + AccessToken);
			myHttpWebRequest.Accept = "application/json";
            
            // prepare sink for responses
            var myWebResponse = myWebRequest.GetResponse();
            var responseStream = myWebResponse.GetResponseStream();
            if (responseStream == null) {
                return null;
            }
            
            // read the complete JSON response
            var myStreamReader = new StreamReader(responseStream, Encoding.Default);
            var json = myStreamReader.ReadToEnd();
            
            // clean up
            responseStream.Close();
            myWebResponse.Close();
            
            // decode JSON response and return the result
            dynamic data = Json.Decode(json);
            return data;
            
        }
        
        /// <summary>
        /// Retrieve a JWT Token for login.
        /// </summary>
        /// <param name="username">The user name</param>
        /// <param name="password">The password</param>
        public void requestToken (string username, string password)
        {
        	// define URI for getting the JWT token
            var myUri = new Uri(new Uri(Url) , "token");
            
            // configure request object to get the JWT access token
            var myWebRequest = (HttpWebRequest) WebRequest.Create(myUri);
            myWebRequest.ContentType = "application/json";
            myWebRequest.Accept      = "application/json";
            myWebRequest.Method      = "POST";

            // create a request stream containing user name and password
            using (var streamWriter = new StreamWriter(myWebRequest.GetRequestStream()))
            {
                string json = "{\"username\": \""+username+"\"," + "\"password\": \""+password+"\"}";

                streamWriter.Write(json);
                streamWriter.Flush();
                streamWriter.Close();
            }

            // prepare sink for the response
            var httpResponse = (HttpWebResponse) myWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
            	// read complete response
                string jsonResult = streamReader.ReadToEnd();
                
                // decode JSON response and grab the token
                dynamic data = Json.Decode(jsonResult);
                AccessToken = data.token;
            }
            
        }
    }
}

 

© All rights reserved