Marcura

&lt;img src="https://content.pstmn.io/9e5ad1a4-82ee-46d6-9141-5e7b7f9c84b1/ZG93bmxvYWQuc3Zn" width="150" height="100">

This service made to share different maritime datasets. **Marcura** has 15 years expertise in maritime industry and has huge network of agent and charterers. It has rich data collection on **costs**, **locations**, **polygons, vessels restrictions**, **tradeflows** and **lineups**. This service is extension to [**Portlog**](https://desktop.postman.com/?desktopVersion=10.13.0&userId=27133318&teamId=0)

The base url of the set API endpoints is [https://data.portlog.com/](https://data.portlog.com/)

Marcura API

Authentication

Bearer Token

API Key

Commodities

Get commodity mapping

Locations

Port Location

Terminal Location

Berth Location

Port Costs v1

Get Port Cost

Get Terminal Stats

Port Costs v2

Retrieve the port costs for all available vessel segments and operation types (loading/discharging) for a given location and commodity. Response includes indication whether cost includes towage and also DWT range of a returned vessel segment. For details please refer to request/response examples on the right.

Get Costs Per Segment

Restrictions

Restrictions All

Working Hours

PortLog PRO operations to predict voyage.

PortLog PRO

Retrieve laytime predictions (turnaround, paid, unpaid and demurrage/despatch days), most likely cost and voyage alerts for a single or multiple voyages. Each voyage includes multiple itineraries/portcalls and has unique <code>estimateId</code> which can be used to retrieve the results later. Itineraries require only port as input parameter, PortLog will predict terminal based on the itinerary details like commodity, vessel size, charterer, etc. Cargoes can be used across whole voyage or only by single itineraries/portcalls. They are referenced using unique <code>cargoSeq</code>. For details please refer to request/response examples on the right.

Predict voyage

Retrieve available CP templates with defined terms.

Get CP templates

Retrieve available working hour templates.

Get working hour templates

Retrieve a list of saved ProSnapshots by IMOS estimate ID. Returns summary information including the proSnapshotRequest field from the JSON, without PDF data. Each snapshot contains the original request parameters and metadata about when it was created and by whom.

Get snapshots by IMOS estimate ID

Retrieve a saved ProSnapshot by ID as JSON. Returns the complete snapshot data including the original request, selected terminal snapshot, and all alternative terminal snapshots with their respective laytime calculations, costs, restrictions, insights, and alerts.

Get snapshot by ID as JSON

Retrieve a saved ProSnapshot by ID as PDF file for download. The PDF contains a comprehensive report with laytime calculations, cost analysis, terminal comparisons, restrictions summary, insights, and alerts for the selected voyage segment. The file is automatically downloaded with the filename format 'prosnapshot-{snapshot_id}.pdf'.

Get snapshot by ID as PDF

PortLog OTA predicts the optimal time of arrival (OTA) by calculating laytime and port costs for any arrival scenario of your port calls.

PortLog OTA

Performs laytime and PnL predictions for a provided set of estimated arrival times. The Interface Unique Reference (IUR) is used to map all necessary portcall data like vessel, port, operation, commodity and other relevant commercial terms from external voyage provider.The API will return the mapped portcall details and a scenario for each provided ETA with laytime result information and PnL impact

Calculate laytime and costs for OTA scenarios

Lineups V2

Crude oil

Liquid bulk

Dry cargo

Grains

Coal

Iron ore

Terminal Predictor

Predicts terminals in port based on given parameters: port, commodity, operation, DWT. The API will return a list of terminals, together with a percentage score for each terminal, indicating the likelihood of the terminal being selected for the commodity/operation/vessel's DWT.

Predicts terminals in port based on given parameters: port, commodity, operation, DWT

PortLog Insights provides access to your own insights from PortLog for both dry and tank.

PortLog Insights

Gets all own insights from both dry and tank entitlements in json format.

Gets all own insights

Downloads an attachment file associated with an insight. The file can be of any media type.

Downloads insight attachment file

Time in Port

Return the activity breakdown as shown in Time tab + the additional field of calculated days alongside based on the activity duration summary between All Fast and Last Line Ashore. For details please refer to request/response examples on the right.

Get Time In Port

Tradeflows

Everything

Iron Ore

Tradeflows V2

Crude Oil

Liquid Bulk

Commodities at Berth

Commodity detailed level

Commodity level

Facility Operators

Get Facility Operator

Agency Locations

DA-Desk Operator APIs are a set of REST APIs delivered using JSON data format and served over HTTPS. DA-Desk exposes several APIs however this document will focus on the most popular set to keep the document as bite size as possible. While DA-Desk makes best efforts in keeping these API fully backward compatible, in some rare cases changes need to be made. In the event of such changes, the point of contact will receive a notification with ample time to be ready for the change. These APIs use mainly the DA-Desk internal IDs for retrieving and referring to information, however integration codes for agents/suppliers, ports and vessels are passed along with the responses to help the customers integrate the information with their internal systems.

The APIs are hosted behind a CDN (Amazon Cloudfront). If an IP filter is required, please check the IP Range of Cloudfront that applies to your region: [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)

The Production API is hosted on [https://api.marcura.com/dad](https://api.marcura.com/dad).

The Test API is hosted on [https://api.cuat.marcura.com/dad](https://api.cuat.marcura.com/dad).

## Authentication

DA-Desk API uses the shared Marcura API authentication.

All API calls require a valid authenticated user session. Once authentication is performed successfully, a session token is generated and returned. This token needs to be used in every subsequent API call by passing it as a query parameter _?token=_.

Authentication can be performed by calling the shared Marcura API _/auth_.

## Service ID and Version

_serviceId_ and _serviceVersion_ are query parameters used by DA-Desk APIs for tracking and debugging. These parameters are mandatory in all API calls except the authentication. The _serviceId_ should contain your integration application name and _serviceVersion_ should contain the version of the application. Both parameters are of type String.

Example:

`?serviceId=customerXXXIntegration&serviceVersion=1.0`

DA-Desk (Operators)

Searching for DAs can be done using the DA-Desk Operator search API. There are plenty of parameters that this API supports, here below we show an example based on last updated date, filtering for actionable DAs for the user vessel list only and on DA type of MAIN ordering the response by ETA in descending order. The API also support a free text search which is available under the parameter of _text_ as shown in the example. The response of this API is paginated and scrolling through the pages is allowed. However there is a limit of 10,000 entries available in the scroll. If more results are required, please consider changing the search criteria to limit the response size.

DA Search

Once a list of Das is acquired that need to get information for, the DA Details API can be called which will have all the information in one place include details such as the agent full contact details, the nomination type, the exchange rates, the cost information including vouchers, credit notes and many more. This API has integration codes for agent.

DA Details

While the DA details API might contain most of the information requires, a portcall details API is also available that contains more information about the portcall itself including the vessel, port, agent, contracts selected, the full set of agent instructions, the header and footer, the portcall contact persons, internal references and others. It also includes information such as max port costs, timebar and more. The portcall ID can be obtained from the search API or the DA Details API. This API has integration codes for agent, vessel and port.

Portcall Details

The DA goes through several different phases throughout its life such as agent appointed, PDA submitted … all the way through to DA Compete. To retrieve the history of a particular DA, the history API can be used which returns events together with timestamps and the persons involved.

DA History

The DA Download API is a multipurpose API that in summary generates a DA coversheet as a PDF file and prepares it for download. The coversheet depends on the current DA status so calling this API throughout the lifecycle of the DA will give you a different coversheet. For example calling this API after completing PDA Approval, will generate a PDA Approved Coversheet. After the DA has been submitted for FDA operator to agree, this API generates a coversheet and optionally attaches all the invoices linked to this DA. The query parameter _withDocs_ which accepts a Boolean enables or disables the addition of all invoices to the download pack. The currency in which the coversheet is generated can also be controlled by the _displayCurrency_ query parameter.

Another query parameter that controls this API: _expCatId_. This query parameter limits the download to one single expense category (the id of which can be extracted from the DA Details API). If the expCatId selected is an Owner’s Cost expense or a Charterer’s Cost expense, the coversheet generated will become an Owner’s Coversheet or a Charterer’s Coversheet respectively. The invoices attached to this coversheet will be limited to the ones that appear in the selected expense category only.

After the agent submits the FDA and before DA-Desk processes the DA and moves it to FDA for operator to agree, there is another temporary coversheet that can be downloaded to specifically help generating charterer’s expenses if the timebar is approaching and the DA is stuck somewhere in between. This document can be downloaded by supplying the query parameter: _fdaLetter_\=true and will generate a coversheet for the FDA as submitted by the agent.

DA Download

If instead of a coversheet and a whole pack, it is required to obtain individual documents (invoices, credit notes …) to be download for segregation, this API allows you to download the individual documents of a DA by ID. The document IDs can be found in the DA Details API within the cost items section. Please note that cost items have a many to many relationship with documents hence if you are scrolling through a DA, the list of document IDs might not be unique.

Individual Document Download

Payments API provides information about approval of payments, in which currency and other relevant information. If PPL services are also availed, this API will provide information on whether the PPL payment was executed or not. One DA can have multiple payments such as advance and balance. On top, calling this API on the Main DA, it will actually provide a consolidated view including all Supplementary Das and Vendor Invoices.

DA Payments

DA-Desk also offers a set of reports with some pre-computed data that might be interesting for the customer. There are 14 reports in total but some of these reports might not be applicable for the customer. Also reports require permission to be given to by the administrator. To retrieve the list of reports available to you, the following API can be used

Reports

Each report has a different search criteria available. To retrieve the search criteria list of a report use the following API.

Report Criteria

Each report also returns a different result set which can be retrieved using the following API.

Report Columns

Finally the actual search API can be triggered through the following call.

Report Data

# DA-Desk (Agents)

DA-Desk Agents APIs are a set of REST APIs delivered using JSON data format and served over HTTPS. DA-Desk exposes several APIs however this document will focus on the most popular set to keep the document as bite size as possible. While DA-Desk makes best efforts in keeping these API fully backward compatible, in some rare cases changes need to be made. In the event of such changes, the point of contact will receive a notification with ample time to be ready for the change.

The APIs are hosted behind a CDN (Amazon Cloudfront). If an IP filter is required, please check the IP Range of Cloudfront that applies to your region: [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)

The Production API is hosted on [https://api.marcura.com/dad](https://api.marcura.com/dad).

The Test API is hosted on [https://api.cuat.marcura.com/dad](https://api.cuat.marcura.com/dad).

## Authentication

DA-Desk API uses the shared Marcura API authentication.

All API calls require a valid authenticated user session. Once authentication is performed successfully, a session token is generated and returned. This token needs to be used in every subsequent API call by passing it as a standard HTTP Authorization Bearer token in the form of: _Authorization: Bearer_ .

Authentication can be performed by calling the shared Marcura API _/auth_. Please refer to the documentation under [Authentication -&gt; Bearer Token](https://developers.marcura.com/marcura/api/)_._

## Service ID and Version

_serviceId_ and _serviceVersion_ are query parameters used by DA-Desk APIs for tracking and debugging. These parameters are mandatory in all API calls except the authentication. Both parameters are of type String and both can take any (made up) value as long as it is consistent through all the calls. Basically both should be constant, where the serviceVersion should be changed on every customer integration release to identify the different versions. The _serviceId_ should contain your (made up) integration application name and _serviceVersion_ should contain the version of the application.

Example:

`?serviceId=dadesk--integration&serviceVersion=1.0`

DA-Desk (Agents)

Searching for DAs can be done using the DA search API. There are plenty of parameters that this API supports, here below we show an example based on last updated date, filtering for specific status group of "New Appointment Please Accept". The response of this API is paginated and scrolling through the pages is allowed. However there is a limit of 10,000 entries available in the scroll. If more results are required, please consider changing the search criteria to limit the response size.

DA Status Groups

Once a list of Das is acquired that need to get information for, the DA Details API can be called which will have all the information in one place include details such, the exchange rates, the cost information, including cost items, vouchers, credit notes and many more. The API also includes information on what actions can be performed on the DA in this current status.

Information about the portcall can be retireved using the portcall details API. This information includes the vessel, port, contracts selected, the full set of agent instructions, the header and footer, the portcall contact persons and others. It also includes information such as max port costs, timebar and more. The portcall ID can be obtained from the search API or the DA Details API.

Once an agent has been appointed by an operator, the confirmation of acceptance of the appointment is required. That is performed by calling the Accept and Submit API which tells DA-Desk that the agent is accepting the appointment and will be submitting the PDA.

Accept and Submit

This API can be used to push information into the proforma DA including:

- Currency
    
- Reference numbers
    
- Comments
    
- Contact Person
    
- Proforma Basis
    
- Estimated time of Departure
    
- others...

Update PDA

DA Cost Item Search/Create 

Update the value of the cost item. Supplying the query parameter advancePercent=true will automatically re-calcalculate the advance based on the percentage specified in the DA.

Update Cost Item

Add a comment to the cost item. This will be particularly useful is the agent can push relevant information such as how this value was computed and tariff explanations.

Add Comment

Removes a cost item from a DA. The cost item must not have dependencies such as comments.

Delete Cost Item

Update FDA

Get FDA Documents

Upload FDA Documents

Upload FDA SOF

Add Payment Prefunding

Update Payment Prefunding

Will be replaced by a search cost item provided a master cost item ID and an annotation ID.

List bank accounts

Master Cost Items

Annotations

This endpoint has global tradeflows coverage which for **Grains, Liquid Bulk, Dry Cargo, Iron Ore, CPP, Coal** and **Crude Oil**. These data has been developed with the help of our internal sources and multiple agents availble globally.

Lineups API (BETA)

This endpoint has all grains global tradeflows.

This endpoint has all the Liquid Bulk or Tanker vessels tradeflow globally.

This endpoint has Iron Ore cargo related vessels data.

This endpoint has Coal carrying cargo vessels data.

This endpoint has Crude Oil carrying vessels data.

Contact US

Marcura PortLog Data API Services

v3.1

Production

Access the Lineups API to get detailed information about vessels and their planned activities, Vessel arrival with operations of various cargoes across major ports. The API likely provides information on all planned vessels scheduled to call at specific ports, along with the associated activities and commodities involved in those operations. The data has been derived using different data sources, including port authorities, shipping companies, terminal operators, vessel tracking services (AIS), and port agencies
We have segregated Lineup API into multiple end points based on commodity like grains, liquid bulk ( tankers ), Dry Cargo (Bulk), Iron Ore, Cleaned Petroleum Products, Coal, Crude Oil. <div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div >Lineup API share details on future/planned activities only. We have historical data as well which can be shared on request. One can contact us for historical data.</div></div>Update and ETL schedilung process<div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div>Update Frequency : Run checks and validations on ETA date records will covering the last 75 ETA dates. For each of the last 75 ETA dates, check if the associated record is valid or needs updates based on the latest available data.
Flagging Deleted IDs: If any records are identified for deletion , based on various check, update the isDeleted flag to &apos;Y&apos; and ensure the modified_date field is updated accordingly.
Handling Record Updates:If a vessel&apos;s ETA date or port is updated due to confirmation from a trusted source the relevant fields (port, ETA date) must be updated in the database along with the modified Date<div class="slate-div"></div>Imp Note :- For Regular API calling , please use modified_start that using eta_start


Access the Lineups API to get detailed information about vessels and their planned activities, Vessel arrival with operations of various cargoes across major ports. The API likely provides information on all planned vessels scheduled to call at specific ports, along with the associated activities and commodities involved in those operations. The data has been derived using different data sources, including port authorities, shipping companies, terminal operators, vessel tracking services (AIS), and port agencies


We have segregated Lineup API into multiple end points based on commodity

grains, liquid bulk ( tankers ), Dry Cargo (Bulk), Iron Ore, Cleaned Petroleum Products, Coal, Crude Oil

Run checks and validations on ETA date records will covering the last 75 ETA dates. 

For each of the last 75 ETA dates, check if the associated record is valid or needs updates based on the latest available data.

If any records are identified for deletion , based on various check, update the isDeleted flag to 'Y' and ensure the modified_date field is updated accordingly.

If a vessel's ETA date or port is updated due to confirmation from a trusted source the relevant fields (port, ETA date) must be updated in the database along with the  modified Date

Imp Note :- For Regular API calling , please use modified_start that using 

The Crude Oil section provides comprehensive global lineup data for all Dry Cargo which are not a part of agricultuiral products , Iron ore and coals .This endpoint has all Dry Cargo related vessels data.<div class="slate-div"></div><div class="slate-div"></div>

The Crude Oil section provides comprehensive global lineup data for all Dry Cargo which are not a part of agricultuiral products , Iron ore and coals .

This endpoint has all Dry Cargo related vessels data.

name

vessel

iso2code

iso3Code

country

code

unlocode

coordinates

port

cargo

quantity

operation

cargoInfo

isDeleted

modified

The authorization token used to access the API.

Authorization

The ISO 2 code for identifying the country associated with the grain lineup.

The International Maritime Organization (IMO) number of the vessel associated with the grain lineup.

Sections

Crude oil

Header Parameters

Query Parameters

Body Parameters

Response

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

Crude oil

Header Parameters

Query Parameters

Body ParametersExpand all

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Body Parameters

Response