The API provides a mechanism for customers to access the schedule and tracking data. Customers can use the API to make use of the schedule data within their own software applications. The API provides access via a standard REST web service that can be used with any programming language and on any platform.
Data is accessed by making a Request to the API that specifies the type of data that is being searched for and any criteria to narrow the search. The API then replies with a Response that includes a list of any items that satisfy the request. So, for example, a request for vessels could specify a particular carrier and the API would send back a response which includes a list containing information on each of the vessels operated by the specified carrier.
The table below summarizes the different types of data available from the API and gives an example of a request that could be made to retrieve data of that type.
Each request to the API is made by specifying a particular Endpoint to call. These endpoints are simply URLs that the code that calls the API uses to indicate which type of data it is interested in. There is one endpoint for each of the items in the table above. So, for example, there is an endpoint named /carriers which is used to return information on carriers and an endpoint named /vessels to return vessel information.
Each endpoint also supports a number of different parameters that specify criteria to use to filter the results. So, for example, the /carriers endpoint can be called with a SCAC parameter. This would indicate that only details for the carrier with a SCAC code that matches that specified by the parameter should be returned.
| API Call | Description | Example Request |
|---|---|---|
| /carriers | The company operating a vessel | Get details on a carrier with a specific SCAC code |
| /locations | A region or country in which ports are located | Get details of all regions or countries whose name begins with a specific word |
| /ports | A shipping port | Get details of all the ports in a specified country |
| /portcalls | All available port calls and dates by a particular vessel | Get the names of all vessels scheduled to call at a port within a specified date range |
| /portpairs | All available origin/destination port-pairs for a specified carrier | Get a list of port-pairs for which the /sailings end-point would return voyages |
| /routes | All available routes (Services) for a carrier | Get all route (Service) names calling at any port |
| /sailings | A journey between an origin and destination port. This can be a direct voyage or a multi-legged journey involving one or two transhipments | Get a list of possible schedules between a specified origin port and destination port that starts after a specified date |
| /tracking | Actual port call dates/times from AIS | Get actual port calls for a vessel |
| /vessels | A shipping vessel | Get vessel register details on all vessels operated by a specified carrier |
| /voyages | Information on a particular vessel-voyage from its start-port on a particular date to its end-port at a later date | Get information on voyages scheduled to be made by a specified vessel after a specified date |
| /usage | The number of API requests made per calendar month | Get the number of remaining quota of API calls available |
These parameters vary according to the endpoint and the exact details can be found in the API reference guide, which will be sent to you along with an API test key.
The response data returned by the API also varies according to each endpoint. Generally the responses consist of a list of items in ‘json‘ that match the request and some aggregate information. The aggregate information contains data such as the total number of results or the number of results that relate to a particular carrier for example.
If there are a lot of results available for a particular API call, the response will just include a subset of them and an indication of how many are available. Further API calls can be made to retrieve the rest of the results in batches of 200. In these cases, special limit and offset parameters are used to specify which subset of the results should be returned on each call.
Sometimes requests to a number of different API endpoints will be required to get all the information needed. For example, if a request had been made to the /voyages endpoint to find information about the voyages of a particular vessel, the response will include the origin and destination ports but not any intermediate ports. To obtain these, a further call to the /portcalls endpoint could be made specifying the schedule ID that was included in the /voyages response.
Click API Documentation to view the API References, Changes and Postman Instructions.