Marcura API ## Sections • [Marcura API](https://developers.marcura.com/home.md): Marcura Group offers multiple comprehensive software solutions to help streamline maritime processes. Marcura's data solutions provide structured and reliable access to maritime and shipping data, spanning vessel movements, port operations, trade flows, disbursement account costs and many other Port Intelligence solution . Our data is available through a range of access methods, including APIs, CSV, Excel, and S3 buckets, enabling seamless integration into customer systems for operational reporting, cost analysis, and trade intelligence. Among these, our Port Log Data APIs provide a dedicated interface for accessing detailed port call information, giving end users structured access to the underlying datasets. Contact US • [Authentication](https://developers.marcura.com/authentication.md): The API uses two methods to authenticate requests: Bearer Token API Key All API requests must be made over HTTPS . Calls made over plain HTTP will fail. API requests without authentication will also fail. • [Bearer Token](https://developers.marcura.com/authentication/bearer-token.md): This endpoint authenticates users and provides a bearer token that can be used for secure access to protected resources in subsequent API calls. Users are required to submit their clientId and clientSecret as a JSON payload. For backwards compatibility, the API also accepts the username and password Please contact our user management team on email address usermanagement@marcura.com to get onboarded. Authorization for Subsequent Requests After obtaining the token, include it in the Authorization header as a Bearer token in future API requests to authorized endpoints: Authorization: Bearer <token> Request • [API Key](https://developers.marcura.com/authentication/api-key.md): Key will be provided to over a secure channel and need to be set as X-Marcura-Api-Key HTTP header. X-Marcura-Api-Key: <apiKey> • [PortLog Data](https://developers.marcura.com/portlog-data-1.md): Data Collection & Scale Marcura processes more than 200,000 port calls annually, supported by millions of real-time data points captured from live voyages to power accurate, real-time estimates. This is further enriched by over 38.2 million digitised Statement of Facts (SoF) events, contributed through our extensive global network of agents and charterers — many of whom are directly involved in maintaining and updating the data. Drawing on decades of maritime industry expertise, Marcura has built this extensive network of agents, charterers, and mariners to deliver enriched, high-quality data that supports better decision-making, improved operational efficiency, and deeper insight into market trends and dynamics. Here’s a list of our available APIs. If you're interested in any of them or have a specific request that’s not covered, feel free to reach out. We're happy to help! • [Agency Locations](https://developers.marcura.com/portlog-data-1/agency-locations.md): Provides the list of all shipping agency details, including agency name, website, phone number, and email address. This is used for identifying and contacting the preferred agency for a given port for any services or operations or enquiries. • [Agency Locations](https://developers.marcura.com/portlog-data-1/agency-locations/agency-locations.md): Provides the list of all shipping agency details, including agency name, website, phone number, and email address. This is used for identifying and contacting the preferred agency for a given port for any services or operations or enquiries. Key Fields Title Description Field Description Agency Name Port Agency name Website Agency's official website URL Phone Number Primary contact phone number Email Address Primary contact email address • [Get Facility Operator](https://developers.marcura.com/portlog-data-1/facility-operator/get-facility-operator.md) • [Commodities at Berth](https://developers.marcura.com/portlog-data-1/commodity-berth.md): Commodities at Berth API provides comprehensive information about the commodities being handled at specific berths during loading, discharging, or both operations. API also monitors berth locations on all calls and tracks vessels that are calling with their respective operations. This tracking functionality could be valuable for various stakeholders involved in maritime operations, including port authorities, shipping companies, and logistics providers. • [Commodity detailed level](https://developers.marcura.com/portlog-data-1/commodity-berth/commodity-detailed-level.md) • [Commodity level](https://developers.marcura.com/portlog-data-1/commodity-berth/commodity-level.md) • [Tradeflows](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1.md): Access our Tradeflows API to determine the actual movement of cargoes across the major ports and countries. This API provides the flows of multiple cargo from the port of Loading to Port of Discharge. The data have been derived using multiple data sources like: Port Authorities Shipping Companies Terminal Operators Vessel Tracking Services (AIS) Port Agencies Tradeflow records has been cleaned and refined, providing users with accurate and reliable data. By mapping the data to masterdata entities and utilizing AIS for further validation and enrichment, we ensure that the information presented through the API is of high quality and integrity. Key Fetures Ports with Activities : The API provides a comprehensive list of ports and countries where commodities are being Exported (Loading) and Imported (Discharging) . This enables users to identify key port locations for Cargo movements and activities worldwide. Quantity and Dates : The API includes details on the quantity of Cargo loaded or discharged at each port, along with the corresponding dates of these activities. This data allows users to analyze shipment volumes, monitor market trends, and plan logistics operations effectively over time. Data Collection and Updates : Information in the API is collected and updated from multiple sources, ensuring accuracy and reliability. Regular updates ensure that users have access to the latest information on grain activities at various ports. Decision Support : By leveraging the insights provided by the Tradeflows API, stakeholders can make informed decisions related to commodity trade, including supply chain planning, market analysis, and risk management. Tradeflow 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. Users can only hit to get maximum 60 days historical data and 15 days future data from AP There are flows where the Quantity data will be either 1 or NULL, as those are unidentifiable cargo or UOM other than MT. The Tradeflow API consist of multiple cargoes, the API can be segregated into multiple End points based on commodity as below. LIQUID BULK CRUDE CPP DPP DRY CARGO COAL IRON ORE GRAINS Querry Parameters Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Parameters Data type Description export_startDate date Start date of export date. Using alone this filter helps to update the tradeflows records each day, e.g. 2023-05-01 export_endDate date End date of export date. This filter helps to restrict the result dataset to be return till this date, e.g. 2023-05-20 exportCountry string Export country iso2code in comma separated for multiple countries, e.g. IN, AE imo string This filter is used to check for specific IMO or vessel's record,e.g. 9364239, 9791872 modified_start date start date of modified date range 'yyyy-mm-dd' modified_end date end date of modified date range 'yyyy-mm-dd' Note:- As we are integrating all our APIs into a single platform, we are currently using two base URLs. We request you to migrate to the new URL. Old- https://data.portlog.com New- https://api.marcura.com • [Coal](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/coal.md): With our real-time data management solution, combined with multiple data source and internal research, we provide a full spectrum of activities and movements of Coal cargo trade from the point of Origin to destinations. • [Iron Ore](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/iron-ore.md): The Iron Ore API is a valuable tool that offers insights into the loading and discharging activities of dry commodities at different ports. This data includes crucial details such as quantities and dates of these activities, providing essential information for stakeholders in the Iron Ore trade Key features of the Iron Ore API include: Comprehensive Data: The API offers comprehensive data on the loading and discharging of wet commodities, covering a wide range of products such as Fueloil, chemicals,Baseoil, and other liquid bulk commodities. Quantities and Dates: Users can access detailed information about the quantities of wet commodities loaded or Discharged at each port, as well as the dates of these activities. This allows for accurate tracking and analysis of cargo movements over time. Port-Specific Insights: The API provides port-specific insights, allowing users to understand the flow of wet commodities at different ports around the world. This information can help inform decision-making related to trade routes, vessel scheduling, and port infrastructure investment. Real-time Updates: The API is regularly updated with real-time data, ensuring that users have access to the latest information on wet cargo activities at various ports. This enables timely decision-making and enhances operational efficiency. Customizable Queries: Users can customize their queries to filter data based on specific criteria, such as commodity type, port location, date range, and quantity thresholds. This flexibility enables users to focus on the information most relevant to their needs • [Grains](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/grains.md): The Grain Ports API offers valuable insights into the loading and discharging of grain commodities at various ports, including details such as quantities and dates of these activities. This information is essential for stakeholders involved in the grain trade, including producers, traders, shipping companies, and port operators. Key features of the Grain Ports API include: Port List : The API provides a comprehensive list of ports and countries where grain commodities are Export (Loading) and Import (Discharging) . This enables users to identify key port locations for grain trade activities worldwide. Loading and Discharging Activities : For each port, the API offers information on the loading and discharging of grain commodities. Users can track the volume of grain being handled at each port and monitor changes in activity over time. Quantity and Dates : The API includes details on the quantity of grain loaded or discharged at each port, along with the corresponding dates of these activities. This data allows users to analyze shipment volumes, monitor market trends, and plan logistics operations effectively. Data Collection and Updates : Information in the API is collected and updated from multiple sources, ensuring accuracy and reliability. Regular updates ensure that users have access to the latest information on grain activities at various ports. Decision Support : By leveraging the insights provided by the Grain Ports API, stakeholders can make informed decisions related to grain trade, including supply chain planning, market analysis, and risk management. Overall, the Grain Ports API serves as a valuable tool for tracking grain trade activities and optimizing logistical operations in the global grain market. If you have any specific questions about the API or its functionalities, feel free to ask! Grain Product category is a generic placeholder for products like wheat, corn, soyabean, rice etc • [Crude Oil](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/crude-oil.md): Marcura's Crude Oil API provides valuable insights into the global crude oil market. By leveraging a vast network of on-the-ground sources and a team of experienced Marine analysts, Marcura ensures that the data received is comprehensive, accurate, and timely. The reports cover export data across over xx major lifting countries, offering detailed analysis on a daily, weekly, and monthly basis. With a focus on transparency and reliability, Marcura's Crude API data include information on Vessel details carrying crude grade, port of origin, Port of destination and Quantity This level of granularity enables stakeholders to make informed decisions based on real-time market intelligence. Whether it's tracking supply trends, understanding export dynamics, or identifying emerging opportunities, Marcura's Crude Package serves as an indispensable resource for anyone operating in the crude oil market. The API includes all type of Crude commodities lifted like Arab Heavy Crude, Al Shaheen Crude, Arab Light Crude, Arab Extra Light Crude, Basrah Heavy Crude, Bonny Light Crude • [CPP](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/cpp.md): Marcura offers a comprehensive suite of reports focusing on Clean petroleum products exports and imports Ports, countries including details such as quantities and dates of these activities. With data gathered from a wide network of on-the-ground sources on a daily, weekly, and monthly basis . Our team of experienced analysts' processes validates the data, enabling them to deliver updates on daily basis. This rapid turnaround time provides clients with timely market intelligence crucial for making informed decisions. The reports offering historical data alongside the latest information. This allows clients to contextualize current trends and patterns, with data presented both in tabular and graphical formats for easy interpretation The API includes all type of CPP commodities lifted like Jet Fuel, Gas Oil, Diesel Fuel, Base Oil, Lube Oil etc. • [DPP](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/dpp.md): Marcura offers a comprehensive suite of reports focusing on Dirty petroleum products exports and imports Ports ,countries including details such as quantities and dates of these activities.. With data gathered from a wide network of on-the-ground sources on a daily, weekly, and monthly basis . Our team of experienced analysts' processes validates the data, enabling them to deliver updates on daily basis. This rapid turnaround time provides clients with timely market intelligence crucial for making informed decisions. The reports offering historical data alongside the latest information. This allows clients to contextualize current trends and patterns, with data presented both in tabular and graphical formats for easy interpretation The API includes all type of DPP commodities lifted like Fuel Oil, High Sulphur Fuel Oil, Carbon Black Feedstock Oil etc • [Liquid Bulk](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/grains-copy-2.md): The Liquid Bulks API provides valuable insights into the loading and discharging of wet commodities at various ports. This includes details such as quantities and dates of these activities, which are essential for stakeholders involved in the wet cargo trade. These stakeholders include producers, traders, shipping companies, and port operators. Key features of the Liquid Bulks API include: Comprehensive Data: The API offers comprehensive data on the loading and discharging of wet commodities, covering a wide range of products such as Fueloil, chemicals,Baseoil, and other liquid bulk commodities. Quantities and Dates: Users can access detailed information about the quantities of wet commodities loaded or Discharged at each port, as well as the dates of these activities. This allows for accurate tracking and analysis of cargo movements over time. Port-Specific Insights: The API provides port-specific insights, allowing users to understand the flow of wet commodities at different ports around the world. This information can help inform decision-making related to trade routes, vessel scheduling, and port infrastructure investment. Real-time Updates: The API is regularly updated with real-time data, ensuring that users have access to the latest information on wet cargo activities at various ports. This enables timely decision-making and enhances operational efficiency. Customizable Queries: Users can customize their queries to filter data based on specific criteria, such as commodity type, port location, date range, and quantity thresholds. This flexibility enables users to focus on the information most relevant to their needs The Liquid Bulks API serves as a valuable tool for stakeholders in the wet cargo trade, providing essential insights into cargo movements, market trends, and port activities. If you have any further questions or need assistance with utilizing the API, feel free to ask! Since the data has been sourced from Multiple sources and after all the necessary check and updates there are some records where the Quantity will be left blank or unknown. • [Dry cargo](https://developers.marcura.com/portlog-data-1/tradeflows-copy-1/dry-cargo.md): The Dry Bulks API is a valuable tool that offers insights into the loading and discharging activities of dry commodities at different ports. This data includes crucial details such as quantities and dates of these activities, providing essential information for stakeholders in the Dry cargo trade Key features of the Dry Bulks API include: Comprehensive Data: The API offers comprehensive data on the loading and discharging of wet commodities, covering a wide range of products such as Fueloil, chemicals,Baseoil, and other liquid bulk commodities. Quantities and Dates: Users can access detailed information about the quantities of wet commodities loaded or Discharged at each port, as well as the dates of these activities. This allows for accurate tracking and analysis of cargo movements over time. Port-Specific Insights: The API provides port-specific insights, allowing users to understand the flow of wet commodities at different ports around the world. This information can help inform decision-making related to trade routes, vessel scheduling, and port infrastructure investment. Real-time Updates: The API is regularly updated with real-time data, ensuring that users have access to the latest information on wet cargo activities at various ports. This enables timely decision-making and enhances operational efficiency. Customizable Queries: Users can customize their queries to filter data based on specific criteria, such as commodity type, port location, date range, and quantity thresholds. This flexibility enables users to focus on the information most relevant to their needs • [Lineups](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1.md): 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 . 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. Update and ETL schedilung process 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 'Y' and ensure the modified_date field is updated accordingly. Handling Record Updates: 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 eta_start • [Crude oil](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/liquid-bulk-copy-1.md): 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. • [Liquid bulk](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/dry-cargo-copy-2.md): The Liquid Bulk 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. • [Dpp](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/cpp-copy-2.md): DPP API Data set provides a collection of data and schedules specifically related to vessels that are transporting Iron and Iron Ore Products . It details the planned arrivals, and operations of vessels carrying coal at a particular port . This endpoint has Iron Ore cargo related vessels data. Dpp • [Cpp](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/iron-ore-copy-3.md): CPP API Data set provides a collection of data and schedules specifically related to vessels that are transporting Iron and Iron Ore Products . It details the planned arrivals, and operations of vessels carrying coal at a particular port . This endpoint has Iron Ore cargo related vessels data. • [Dry cargo](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/grains-copy-4.md): The DryCargo 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. • [Grains](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/grains.md): The Grains section provides comprehensive global lineup data for all grains which includes agricultuiral products, allowing users to access vital information related to grain shipments efficiently. With this API endpoint, users can obtain detailed insights into grain lineups worldwide, aiding in better decision-making and operational planning within the maritime industry. This endpoint has all grains global lineups data. • [Coal](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/coal.md): Coal API Data set provides a collection of data and schedules specifically related to vessels that are transporting coal and Coal Products . It details the planned arrivals, and operations of vessels carrying coal at a particular port . This endpoint has Coal carrying cargo vessels data. • [Iron ore](https://developers.marcura.com/portlog-data-1/lineups-api-beta-copy-1/iron-ore.md): Iron Ore API Data set provides a collection of data and schedules specifically related to vessels that are transporting Iron and Iron Ore Products . It details the planned arrivals, and operations of vessels carrying coal at a particular port . This endpoint has Iron Ore cargo related vessels data. • [Restrictions](https://developers.marcura.com/portlog-data-1/restrictions.md): Restriction API will provide information regarding the limitations on the size or type of vessels that can used at a particular berth. The Berth restrictions information is a primary information used for Marine assurance to check the Vessel acceptance criteria. Each Berth restrictions are being maintained and updated through various sources and are being verified and published after the due diligence. The Restriction API enhances operational efficiency and safety in maritime activities by providing essential information about berth limitations. By leveraging this data, stakeholders can optimize vessel scheduling, minimize downtime, and uphold high standards of marine assurance. Agents can confirm, edit and update data. Dedicated Mariners to verify the Data collected from [port Agents , Port Authority and Port Handbooks • [Restrictions All](https://developers.marcura.com/portlog-data-1/restrictions/restrictions-all.md) • [Working Hours](https://developers.marcura.com/portlog-data-1/restrictions/working-hours.md) • [Cost](https://developers.marcura.com/portlog-data-1/port-costs-api.md): The port costs are developed based on Marcura’s extensive experience in handling Disbursement Accounts (DA) and analysing historical port cost data. The cost estimates are derived by analysing historical port calls, applicable charges, vessel characteristics, cargo/commodity groups, DWT ranges, and vessel segments. This enables us to provide the most likely cost for a given port and vessel profile while accounting for variations observed across different port calls and data sources • [Get Cost per Commodity Group](https://developers.marcura.com/portlog-data-1/port-costs-api/port-cost-2.md): This API provides the most likely port costs for Dry Bulk and Liquid Bulk, covering different commodity groups, DWT ranges, and vessel segments forboth Loading and Discharging actvities. Below are the Vessel Segment and DWT ranges • [Get Grain Cost](https://developers.marcura.com/portlog-data-1/port-costs-api/get-grain-cost.md): This API provides the most likely Voyage costs for Grains covering specific Location, DWT ranges and vessel segments for both Loading and Discharging actvities. Below are the Vessel Segment and DWT ranges • [Polygon](https://developers.marcura.com/portlog-data-1/locations-copy-2.md): Access to our location API , which will provide you with the Coordinates (latitude/longitude) of Ports, Terminals and Berths. Provides the geographical boundary of a port, terminal, or berth, geofenced based on various sources of information. Together with the Location API, the Polygon API offers a powerful toolset for accessing spatial boundaries of ports, terminals, and berths. Polygon Types Provided Port Polygon – Geofenced outer boundary of the port area Port Approaches Polygon – Boundary covering the approach area leading into the port Port Anchorage Polygon – Boundary of the designated anchorage area Terminal Polygon – Boundary of an individual terminal within the port Berth Polygon – Boundary of an individual berth within a terminal This polygon can be used to identify The list of Vessels within the Port, Terminal and Berths. Track the Vessel arrived and departed at Port, terminal and Berth Calculate the Avg waiting time, Turnaround time etc The API has to be called separately as per hierarchy of Port , Terminal and Berths The Locations API has no restrictions whatsoever with regards to the history. The API may be called once without providing any parameters to facilitate the initial load. Thereafter, the [start_dt] may be used to GET data modified on or after that date. Please replace/update this data by using the [berthCode] identifier. At all times, you may refresh the entire dataset by following (b) as and when required. Marcura Recommendation: Records may be retrieved Weekly • [Port Polygon](https://developers.marcura.com/portlog-data-1/locations-copy-2/port-location-copy.md): This endpoint will return geographical boundary of the port. This boundary is derived from thousands of port calls made by vessels, and it has been verified using actual Statement of Facts (SOF). This ensures that the port boundary accurately represents the physical extent of the port area based on real-world maritime activities. • [Terminal polygon](https://developers.marcura.com/portlog-data-1/locations-copy-2/terminal-location-copy.md) • [Berth Polygon](https://developers.marcura.com/portlog-data-1/locations-copy-2/berth-location-copy.md) • [Locations](https://developers.marcura.com/portlog-data-1/location-api.md): Access to our location API , which will provide you with the Coordinates (latitude/longitude) of Ports, Terminals and Berths. Provides Port, Terminal, and Berth (PTB) location details, forming the core geographic reference hierarchy used across other Marcura APIs. Port Location API Port name, country, ISO2 code, UN/LOCODE, coordinates, and related reference details. Terminal Location API Terminal name, terminal location, and the parent port name belong to. Berth Location API Berth name, berth location, and the parent terminal and port names associated with it. This polygon can be used to identify The list of Vessels within the Port, Terminal and Berths. Track the Vessel arrived and departed at Port, terminal and Berth Calculate the Avg waiting time, Turnaround time etc The API has to be called separately as per hierarchy of Port , Terminal and Berths The Locations API has no restrictions whatsoever with regards to the history. The API may be called once without providing any parameters to facilitate the initial load. Thereafter, the [start_dt] may be used to GET data modified on or after that date. Please replace/update this data by using the [berthCode] identifier. At all times, you may refresh the entire dataset by following (b) as and when required. Marcura Recommendation: Records may be retrieved Weekly • [Berth Location](https://developers.marcura.com/portlog-data-1/location-api/berth-location.md) • [Congestion](https://developers.marcura.com/portlog-data-1/commodities-copy.md): Provides information on port congestion levels and vessel delays, helping to anticipate waiting times and plan port calls more effectively. Delay – Current delay at the port Vessels in Port – Vessels currently in port Vessel ETA 14 Days – Vessels expected within the next 14 days • [Port Congestion](https://developers.marcura.com/portlog-data-1/commodities-copy/get-commodity-mapping-copy.md): The Port Congestion Report provides key indicators to assess congestion levels at a port by analyzing vessel traffic and delays. Vessels are categorized into segments based on their Deadweight Tonnage (DWT), enabling more granular analysis of congestion by vessel size. This report includes: Vessels in the Port : Number of vessels currently at the port awaiting berthing or operational clearance. Vessels (ETA ≤ 14 Days) : Number of vessels expected to arrive at the port within the next 14 days. Average Berthing Delay : The average number of days vessels take to secure a berth after arriving at the port. • [Commodities](https://developers.marcura.com/portlog-data-1/mapping.md): Helps identify the type of cargo/commodities handled by a given port, terminal, and berth. Commodities Handled – Identifies the type of cargo/commodities handled by the port, terminal, and berth By Operation – Identifies the cargo handled at the berth by operation — what cargo is being loaded and what is being discharged • [Commodity Mapping](https://developers.marcura.com/portlog-data-1/mapping/get-commodity-mapping.md) • [PortLog Masterdata](https://developers.marcura.com/portlog-masterdata.md): Reference data known to PortLog - locations and commodity groups - including the codes to pass to the other endpoints. • [Port Location](https://developers.marcura.com/portlog-masterdata/port-location.md): Returns port specific details regarding the port and its coordinates (latitude and longitude), grouped by country. The unique identifier of the port is code - although UN/LOCODE is the standard unique identifier for ports, there are locations in our database where it is not available and is being gradually updated. Results can be narrowed down by country or by port. When no filter is given, all ports are returned. Port groups are not included. • [Commodity Groups](https://developers.marcura.com/portlog-masterdata/commodity-groups.md): Returns the commodity groups of the requested cargo type. The code of a group is the value to pass as commodityGroupId to the port costs and time in port endpoints, for the same cargo type. Groups form a hierarchy through parentCode ; the top level groups of a cargo type point at the root group ‘All Cargos’, which spans both cargo types and is therefore never returned. • [Terminal Location](https://developers.marcura.com/portlog-masterdata/terminal-location.md): Returns the terminals of the requested ports and their coordinates (latitude and longitude), grouped by port and country. The unique identifier of the terminal is code . Berths are not included, they are master data of their own. A requested port with no terminals is returned with an empty terminal list. • [PortLog CORE](https://developers.marcura.com/portlog-core.md): PortLog CORE operations including Port costs, Time-in-port, Terminal-Predictor and Insights. • [Get Time In Port](https://developers.marcura.com/portlog-core/get-time-in-port.md): 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 Costs Per Segment](https://developers.marcura.com/portlog-core/get-costs-per-segment.md): 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. • [Predicts terminals in port based on given parameters: port, commodity, operation, DWT](https://developers.marcura.com/portlog-core/predicts-terminals-in-port-based-on-given-parameters-port-commodity-operation-dwt.md): 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. • [Gets all own insights](https://developers.marcura.com/portlog-core/gets-all-own-insights.md): Gets all own insights from both dry and tank entitlements in json format. • [Downloads insight attachment file](https://developers.marcura.com/portlog-core/downloads-insight-attachment-file.md): Downloads an attachment file associated with an insight. The file can be of any media type. • [PortLog PRO](https://developers.marcura.com/portlog-pro.md): PortLog PRO operations to predict voyage. • [Predict voyage](https://developers.marcura.com/portlog-pro/predict-voyage.md): 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 estimateId 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 cargoSeq . For details please refer to request/response examples on the right. • [Get CP templates](https://developers.marcura.com/portlog-pro/get-cp-templates.md): Retrieve available CP templates with defined terms. • [Get working hour templates](https://developers.marcura.com/portlog-pro/get-working-hour-templates.md): Retrieve available working hour templates. • [Get snapshots by IMOS estimate ID](https://developers.marcura.com/portlog-pro/get-snapshots-by-imos-estimate-id.md): 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 snapshot by ID as JSON](https://developers.marcura.com/portlog-pro/get-snapshot-by-id-as-json.md): 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 PDF](https://developers.marcura.com/portlog-pro/get-snapshot-by-id-as-pdf.md): 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’. • [PortLog OTA](https://developers.marcura.com/portlog-ota.md): PortLog OTA predicts the optimal time of arrival (OTA) by calculating laytime and port costs for any arrival scenario of your port calls. • [Calculate laytime and costs for OTA scenarios](https://developers.marcura.com/portlog-ota/calculate-laytime-and-costs-for-ota-scenarios.md): 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 • [DA-Desk (Operators)](https://developers.marcura.com/da-desk-operators.md): 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 The Production API is hosted on https://api.marcura.com/dad . The Test API is hosted on 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 <token> . Authentication can be performed by calling the shared Marcura API /auth . Please refer to the documentation under Authentication -> Bearer Token . 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-<tla>-integration&serviceVersion=1.0 • [DA Search](https://developers.marcura.com/da-desk-operators/da-search.md): 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 Details](https://developers.marcura.com/da-desk-operators/da-details.md): 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. • [Portcall Details](https://developers.marcura.com/da-desk-operators/portcall-details.md): 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. • [DA History](https://developers.marcura.com/da-desk-operators/da-history.md): 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 Download](https://developers.marcura.com/da-desk-operators/da-download.md): 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. • [Individual Document Download](https://developers.marcura.com/da-desk-operators/individual-document-download.md): 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. • [DA Payments](https://developers.marcura.com/da-desk-operators/da-payments.md): 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. • [Reports](https://developers.marcura.com/da-desk-operators/reports.md): 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 • [Report Criteria](https://developers.marcura.com/da-desk-operators/report-criteria.md): Each report has a different search criteria available. To retrieve the search criteria list of a report use the following API. • [Report Columns](https://developers.marcura.com/da-desk-operators/report-columns.md): Each report also returns a different result set which can be retrieved using the following API. • [Report Data](https://developers.marcura.com/da-desk-operators/report-data.md): Finally the actual search API can be triggered through the following call. • [Contract Search](https://developers.marcura.com/da-desk-operators/da-search-copy.md): Searching for contracts can be done using the DA-Desk Contract search API. There are plenty of parameters that this API supports, here below we show an example based on country, port, title, filtering ordering the response by title in descending order. Attachment are avaiailable in the document section of the response and the applicabilities section give detail configuration of where the contract applies by local agents/suppliers, port, country, activities and other criteria. In the contract module, the configuration works in a way that the parent contract contains some default configuration. The applicability level may overwrite or keep it as is. Empty configuration on the applicability level means it will inherit from the parent contract. 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-Desk (Agents)](https://developers.marcura.com/da-desk-agents.md): 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 The Production API is hosted on https://api.marcura.com/dad . The Test API is hosted on 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 -> Bearer Token . 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-agent-integration&serviceVersion=1.0 • [DA Search](https://developers.marcura.com/da-desk-agents/da-search.md): 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](https://developers.marcura.com/da-desk-agents/list-bank-accounts-copy-1.md): List all available DA Status groups which can be used as a search criteria and returned in the response for each DA to determine its current status. • [DA Details](https://developers.marcura.com/da-desk-agents/da-details.md): 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. • [Portcall Details](https://developers.marcura.com/da-desk-agents/portcall-details.md): 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. • [Accept and Submit](https://developers.marcura.com/da-desk-agents/accept-and-submit.md): 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. • [Update PDA](https://developers.marcura.com/da-desk-agents/update-pda.md): 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... • [DA Cost Item Search/Create](https://developers.marcura.com/da-desk-agents/copy-2.md): Given a DA ID, Master cost item ID and Annotation ID (optional), this API will return back a cost item from the given DA respecting the master cost item and annotation parameters. It will automatically find a cost item if present within the DA, create it if is does not exist and allocate it automatically to a category whenever it is necessary. • [Update Cost Item](https://developers.marcura.com/da-desk-agents/update-cost-item.md): 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. • [Add Comment](https://developers.marcura.com/da-desk-agents/add-comment.md): 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. • [Delete Cost Item](https://developers.marcura.com/da-desk-agents/delete-cost-item.md): Removes a cost item from a DA. The cost item must not have dependencies such as comments. • [Update FDA](https://developers.marcura.com/da-desk-agents/update-fda.md): This API can be used to push information into the proforma DA including: Reference numbers Invoice Number Comments Invoice Date Actual time of Arrival & Departure others... • [Get FDA Documents](https://developers.marcura.com/da-desk-agents/get-fda-documents.md): Get list of documents available for this DA. Each document will be marked with a flag if it is also downloadable. • [Upload FDA Documents](https://developers.marcura.com/da-desk-agents/upload-fda-documents.md): Upload a document for this final DA. The most important document is the invoice pack which should include an Agency coverletter, followed by all the invoices for this disbursement account. If there are any supporting documentation for invoices, please include them after the invoice itself. Here is an example of how the document pack should be structured: Agency Coverletter Invoice 1 Supporting Documents for invoice 1 Invoice 2 Supporting Documents for invoice 2 Invoice 3 Supporting Documents for invoice 3 … Please note that SOF (Statement of Facts) has it's own upload space. Use this API for any other document other than the SOF. • [Upload FDA SOF](https://developers.marcura.com/da-desk-agents/upload-fda-sof.md): Upload the Statement of Facts in a PDF format. • [Add Payment Prefunding](https://developers.marcura.com/da-desk-agents/add-payment-prefunding.md): Add an entry of how much of the prefunding was received by the agency. The amount should be in the same currency as the DA currency. Balance amount will be calculated based on this value. There can be multiple entries if multiple payments were affected. • [Update Payment Prefunding](https://developers.marcura.com/da-desk-agents/update-payment-prefunding.md): Update an existing prefunding entry to make corrections. • [List bank accounts](https://developers.marcura.com/da-desk-agents/list-bank-accounts.md): List all available bank accounts. Bank accounts will be filtered depending on operator settings, payment currencies and other factors. • [Master Cost Items](https://developers.marcura.com/da-desk-agents/list-bank-accounts-copy-2.md): Listing all master cost items for DA-Desk. A filter by name is supported where the name can be passed as a query parameter. The master cost items are non-customer specific and there is 1 single standard set for all DA-Desk customers. The master cost items are organised in a hierarchical structure where cost items are grouped and costs are allowed at any level in the hierarchy. Such examples would be Towage (parent) with Towage Escort, Towage Fire Tug Standby, Towage Overtime as children. The lower level defines more fine grained allocation of the cost. • [Annotations](https://developers.marcura.com/da-desk-agents/copy-1.md): Annotations are sub-divisions of master cost items. Using towage as an example, towage will be the master cost item, where INWARD and OUTWARD are annotations. In many cases annotations are optional but they can give more fine granularity to the cost. Annotations are also built using a hierarchical structure however the parent is not allowed to be in a DA. For example Inward and Outward are children of annotation Movement, however Movement on it's own does not mean anything and cannot be associated with a cost item. These specific annotations are marked in the API with isAbstract=true . • [Contact US](https://developers.marcura.com/contact-us.md): For any enquiry please contact us at: Piers Yea - p.yea@marcura.com Jeff Clark - j.clark@marcura.com For technical support please contact us at: support@portlog.com