The API provides a mechanism for Linescape customers to access the Linescape schedule 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 use 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 summarises 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.
| Data type | Description | Example request |
|---|---|---|
| Carrier | The company operating a vessel | Get details on a carrier with a specific SCAC code |
| Contact | Contact details for a carrier | Get the contact details for all offices of a carrier in a specified country |
| Vessel | A shipping vessel | Get details on all vessels operated by a specified carrier |
| Port | A shipping port | Get details of all the ports in a specified country |
| Port Pairs | A pair of ports that are used as an origin and destination for a voyage | Get a list of all the port pairs available for a specified carrier |
| Location | A region or country in which ports are located | Get details of all regions or countries whose name begins with a specific word |
| Voyage | Information on a particular a vessel voyage from an origin port on a particular date to a destination port at a later date | Get information on all voyages made by a specified vessel after a specified date |
| Route | A shipping route | Get a list of the ports currently visited on a specified route |
| Port Calls | A call at a port by a particular vessel | Get the names of all vessels that call at a port within a particular date range |
| Sailing | A journey between an origin and destination port. This can be a direct voyage or a multi-legged journey involving a number of transhipments. | Get a list of possible sailings between a specified origin and destination that starts after a specified date |
| Actual Call | An actual recorded port call | Find the arrival and departure date when a vessel called at a paricular port |
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.
These parameters vary according to the endpoint and the exact details can be found in the API reference guide.
The response data returned by the API also varies according to each endpoint. However generally the responses consist of a list of items that match the request and some aggregate information. The aggregate information contains things like 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. 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 out 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.