Skip to main content

FT SOAP API - How to retrieve reports using WSAPIFormData

  • Updated

This article describes how to retrieve one or more arrival, departure or noon reports.

Step 1: Get the list of available reports

As a first step, you need to get a list of all reports. The list contains the identifier (formGuid) which you need to request a particular report.

Call the GetFormDataInfoList function:

 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetFormDataInfoList>
<body>
<apiIdentifier>
<companyGuid>{{companyGuid}}</companyGuid>
<clientGuid>{{clientGuid}}</clientGuid>
</apiIdentifier>
<timeFrameRequestFilter>
<startDate>2023-02-01T00:00:00</startDate>
<endDate>2023-02-28T00:00:00</endDate>
</timeFrameRequestFilter>
<ffFolderTemplateTypeTag>ARRIVALREPORT</ffFolderTemplateTypeTag>
</body>
</GetFormDataInfoList>
</s:Body>
</s:Envelope>

Set the following parameters:

  • companyGuid: This is your company credential
  • clientGuid: This is your client credential
  • startDate: The begin of the time period you are looking data for
  • endDate: The end date and time of the time period you are looking data for
  • ffFolderTemplateTypeTag: This can be
    • ARRIVALREPORT = Arrival Report
    • DEPARTUREREPORT = Departure Report
    • PERFORMANCEREPORT = Noon Report

The result may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.fleettracker.de/api/1.0">
    <SOAP-ENV:Body>
        <ns1:GetFormDataInfoListResponse>
            <body>
                <request>
                    <apiIdentifier>
                        <ns1:companyGuid>...</ns1:companyGuid>
                        <ns1:clientGuid>...</ns1:clientGuid>
                    </apiIdentifier>
                    <timeFrameRequestFilter>
                        <startDate>2023-02-01T00:00:00</startDate>
                        <endDate>2023-02-28T00:00:00</endDate>
                    </timeFrameRequestFilter>
                    <ffFolderTemplateTypeTag>ARRIVALREPORT</ffFolderTemplateTypeTag>
                </request>
                <formDataInfoDatasets>
                    <folderTemplateGuid>1e4a3931-df86-424e-b4ac-650dade7613f</folderTemplateGuid>
                    <formTemplateGuid>47d720e4-4049-4490-afed-866b8d81a1f5</formTemplateGuid>
                    <folderGuid>ae8539fa-b2f4-4008-96a3-62aa496bf858</folderGuid>
                    <formGuid>9a80ce4e-2f25-4ee7-ab5f-464d8c959ea3</formGuid>
                    <imoNumber>91234567</imoNumber>
                    <lastRevisionDate>2023-02-01T13:05:36</lastRevisionDate>
                </formDataInfoDatasets>
                <formDataInfoDatasets>
...
 

The ship is identified by its IMO number (imoNumber).

Pick the formGuid to identify a particular report. In this example, the ship with the IMO number 91234567 has an arrival report with the form GUID "9a80ce4e-2f25-4ee7-ab5f-464d8c959ea3".

Note: Each report may have different revisions. The lastRevisionDate is the timestamp when the latest revision of the report has been created.

Step 2: Retrieve the report

Now, you can use the GetFormData function to lownload the report:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetFormData>
<body>
<apiIdentifier>
<companyGuid>{{companyGuid}}</companyGuid>
<clientGuid>{{clientGuid}}</clientGuid>
</apiIdentifier> 
<formGuid>6ca3da7e-a0e2-41a6-a0e3-6be856b0df3b</formGuid>
</body>
</GetFormData>
</s:Body>
</s:Envelope>

The result:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.fleettracker.de/api/1.0">
    <SOAP-ENV:Body>
        <ns1:GetFormDataResponse>
            <body>
                <request>
                    <apiIdentifier>
                        <ns1:companyGuid>...</ns1:companyGuid>
                        <ns1:clientGuid>...</ns1:clientGuid>
                    </apiIdentifier>
                    <formGuid>6ca3da7e-a0e2-41a6-a0e3-6be856b0df3b</formGuid>
                </request>
                <imoNumber>91234567</imoNumber>
                <name>AVEIRO</name>
                <UNLocationCode>AVE</UNLocationCode>
                <countryCode>PT</countryCode>
                <destinationType>HARBOUR</destinationType>
                <entryId>344344</entryId>
                <eta>2023-02-07 17:50:00</eta>
                <etd>2023-02-08 17:32:00</etd>
                <formDatasets>
                    <revisionDate>2023-02-08T06:58:59</revisionDate>
                    <endPeriod>2023-02-07T18:50:21</endPeriod>
                    <formData>
                        <value>2291.5</value>
                        <unit>nm</unit>
                        <name>DISTANCE_BOSP_EOSP</name>
                        <widget_id>100</widget_id>
                    </formData>
                    <formData>
                        <value>4.1</value>
                        <unit>nm</unit>
                        <name>DISTANCE_EOSP_FWE</name>
                        <widget_id>201</widget_id>
                    </formData>
                   ...

The variables are:

  • Destination (provided for arrival and departure reports):
    • name: port name
    • UNLocationCode: UN Location code of the port/anchorage
    • countryCode: Country code
    • destinationType:
      • HARBOUR = port call
      • ANCHORAGE = Anchorage
      • DRIFTING = Drifting
      • CANAL = Canal passage
      • RANGE = Range
  • revisionDate = The date when the report was created
  • endPeriod = The timestamp of the report
  • Form data:
    • value: The value
    • unit: The unit
    • name: The identifier of the input variable (widget)