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 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 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.
| Call | Description | Example Request |
|---|---|---|
| Carriers | The company operating a vessel | Get details on a carrier with a specific SCAC code |
| Contacts | Contact details for a carrier | Get the contact details for all offices of a carrier in a specified country |
| Vessels | A shipping vessel | Get details on all vessels operated by a specified carrier |
| Ports | A shipping port | Get details of all the ports in a specified country |
| Locations | A region or country in which ports are located | Get details of all regions or countries whose name begins with a specific word |
| Schedules | Information on a particular 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 |
| Calls | A call at a port by a particular vessel | Get the names of all vessels that call at a port within a specified date range |
| Trips | 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 trips between a specified origin anddestination that starts after a specified date |
| Usage | The number of API requests made per calendar month | Get the number of remaining quota of API calls available |
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, 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 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. 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 /schedules 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 /calls endpoint could be made specifying the schedule ID that was included in the /schedules response.
To view our API Documentation, CLICK HERE