Support
Getting started API
Before beginning, it is necessary to create a Developer Portal Account. If you are registered with Maersk, Maersk Line Limited, Safmarine, or any Sealand – A Maersk Company region, a separate username and password will be required.
Register now to create your App and connect to our APIs by using our registration page.
- After creating an account, log in and create your app to consume one or more API products. From the navigation bar, select Apps and then click the Create app button.
-
Select the API Products that you will call using your App credentials.
Our Customer APIs are exclusively available to Maersk’s current business partners.
To use these APIs, you need to provide at least one Maersk customer code.
If you are logged in using a free email account, you will not be able to use our Customer APIs.
Please register using your official company email address and provide at least one Maersk customer code.
If you cannot locate your Customer Code, please contact your local Maersk office.
When you create an app, a Consumer Key is automatically generated. You can copy the consumer key to your clipboard, as well as view and copy the consumer key's secret. Additionally, you can revoke and add consumer keys from the "Update app" screen.
Now that you have your Consumer-Key, it's time to explore and test our APIs to see how they can enhance your application. In this step, we'll guide you through the process of trying our APIs using the built-in API Docs in our API Catalogue, Postman and Swagger Editor. These tools, or any API client, can help you understand the functionality of our APIs and ensure that everything is working correctly before you start building your integration. Follow the instructions below to get started with each tool and make your first API calls.
The examples provided are for API calls to the Point-to-Point Schedules API, which does not require OAuth 2.0 for authentication. For API Products that require OAuth 2.0, approval for access will be granted within 10 business days. Once you receive an email notification that your access is enabled, you can follow our Authorisation Guide for additional instructions.
- To use the built-in testing functionalty directly from the Developer Portal, select the View button on an API Product in our API Catalogue.
- Navigate through the endpoints listed in the left panel. Click on any endpoint to expand its details, including parameters, request bodies and responses.
- From the left panel, select the endpoint you would like to test. In this example, select the GET endpoint to retrieve Point-to-Point Schesules for Maersk available Ocean Products. Select the Test Request button in the bottom right corner of the console window to execute your API call using cURL in shell script. To execute the API call using another client library, select the dropdown arrow in the upper right corner of the console window.
- From the Test Request window, paste the value of your Consumer-Key into the Authorization APIKeyHeader field.
- Select the query parameters provided in the example or enter your own. For the Point-to-Point Schedules API, the value for vesselOperatorCarrierCode is required. Select the Send Request button from the upper right corner of the Test Request window.
- View the API response in the Response Panel on the right. A successful response returns Status: 200 OK. If you received an error response, please refer to the Common Errors & Troubleshooting section below.
- To download and install Postman or try the web version, visit the Postman download page and choose the version suitable for your operating system (Windows, macOS, Linux or Web). Follow the installation instructions. .
- Launch the Postman application.
- To create a new request, select Send an API request from My Workspace.
- Select the appropriate HTTP method (GET, POST, PUT, DELETE, etc.) from the dropdown next to the request URL bar and type the URL of the API endpoint you want to test. In this example, to retrieve Point-to-Point Schesules for Maersk available Ocean Products, select GET and type the URL: https://api.maersk.com/products/ocean-products.
- Click on the Headers tab to add the required headers. For this example, type the following:
- Add query parameters by clicking the Params tab and entering key-value pairs. In this example, to retrieve schedules from Houston, TX to Rotterdam, enter the origin and destination query parameters. The value for vesselOperatorCarrierCode is required.
Alternatively for Step 3, you can paste the following cURL command in the request URL bar:
- To execute the request, click the Send button. Postman will process the request and display the response in the lower panel. A successful response returns Status: 200 OK. If you received an error response, please refer to the Common Errors & Troubleshooting section below.
- Download the OpenAPI Spec file to your local machine by selecting the View button from the center panel for an API Product in our API Catalogue and click on the Download OpenAPI Spec link.
- To access Swagger Editor, open your web browser and navigate to Swagger Editor.
- Click on File in the top menu and select Import File and upload the OpenAPI spec file from your local machine.
- Verify the Loaded API by ensuring that the API endpoints and details are correctly displayed in the right panel.
- Navigate through the endpoints listed in the right panel. Click on any endpoint to expand its details, including parameters, request bodies and responses.
- Choose an endpoint you want to test. In this example, to retrieve Point-to-Point Schesules for Maersk available Ocean Products, select the GET /ocean-products endpoint.
- Navigate through the endpoints listed in the right panel. Click on any endpoint to expand its details, including parameters, request bodies and responses.
- Click the Try It Out button and enter the required parameters in the provided fields. For this example, to retrieve schedules from Houston, TX to Rotterdam, enter the origin and destination query parameters. The value for vesselOperatorCarrierCode is required. Be sure to remove any parameters you do not want to include in your request.
- To send the request, scroll to the end of the request parameters and click the Execute button. The response details will be displayed below the request section including the status code, response headers and response body. A successful response returns Status: 200 OK. If you received an error response, please refer to the Common Errors & Troubleshooting section below.
In this section, you will find detailed explanations of common errors that may occur while testing our APIs, along with practical troubleshooting steps to resolve them. By understanding these errors and following the suggested solutions, you can ensure smoother and more efficient integration with our APIs.
- This error is returned if the Consumer-Key is missing from the header of the API request or if the Consumer-Key is invalid. Be sure to include --header 'Consumer-Key: the value of your Consumer-Key' in the header of your request. Also, verify that the Consumer-Key is associated to the API that you are calling.
HTTP/1.1 401 Unauthorized
{
"code" : "ERR_GW_001",
"message" : "API Key Validation Failed, please check the API key",
"reason" : "Invalid or expired Key",
"status" : "401"
}
- This error is returned by the Maersk API Gateway if your request fails the OpenAPI Specification (OAS) validation step. This step verifies that your request includes the mandatory query parameters, enum values and the operation method (GET, POST, PUT, PATCH, DELETE) for the endpoint defined in the OAS. The response message contains a detailed description of the cause for the validation failure. Refer to the API specification to ensure that your request conforms to the contract.
HTTP/1.1 400 Bad Request
{
"faultstring" : "OASValidation MAM-SpecValidation with resource \"oas://openapi.yaml\": failed with reason: \"[ERROR - Query parameter 'vesselOperatorCarrierCode' is required on path '/ocean-products' but not found in request.: []]\"",
"detail" : {
"errorcode" : "steps.oasvalidation.Failed"
}
}
- This error indicates that the server cannot find the requested resource. For the Point-to-Point Schedules API, Maersk is unable to find a valid route based on the parameters provided in your request. The response includes a debugMessage that details the reason for the error. In this example, the server was unable to identify the location based on the parameters provided. Refine your location parameters and retry your request. Refer to the FAQs and the API specification for helpful hints related to some parameters.
HTTP/1.1 404 Not Found
{
"method" : "GET",
"requestUri" : "/products/ocean-products",
"status" : "404",
"timestamp" : "05-06-2024 21:26:23",
"message" : "Data not found",
"debugMessage" : "Exception from underlying service[Locations not found!]",
"id" : "5ba9a6414d055adeb3d11cea34ab80fb"
}
- This error indicates that Maersk has identified more than one collectionOrigin and/or deliveryDestination location based on the request parameters provided. The response message includes a list of possible locations. Refine your location parameters and retry your request. Refer to the FAQs and the API specification for helpful hints related to some parameters.
HTTP/1.1 409 Conflict
{
"message" : "more than one collectionOrigin or deliveryDestination location has been found for the input query parameters, please check the available locations list and resend the API request with the corresponding carrierCityGeoID",
"collectionOriginLocations" : [
{
"carrierCityGeoID" : "2297GMT10DROT",
"cityName" : "Houston",
"countryCode" : "US",
"UNLocationCode" : "USH5S",
"UNRegionCode" : "AL"
}
]
}
If you experience any of these or other errors while testing our APIs and are unable to resolve them, please contact us for assistance. Be sure to include:
- The name of the registered developer
- The name of the API you are testing
- Your API request and response payloads
- Your Consumer-Key for the API you are testing
- Any other relevant details that help us to assist you more effectively
For security reasons, please do not include the secret for your Consumer-Key.
With your successful API tests, you're ready to take the next step: building your own powerful integration. This phase is where you harness the power of our APIs to enhance your application, adding new features and improving functionality. Our comprehensive documentation and examples will guide you through the process, making it easy to integrate our APIs seamlessly into your project. Start building your integration today and unlock the full potential of our platform.