The API is available at the following URL:
https://api.linescape.com/api/v1To call it specify your API key in an x-api-key HTTP header.
An example call to the service using the curl command-line tool would be:
curl -H 'x-api-key: APIKEY' 'https://api.linescape.com/api/v1/portcalls?limit=10&offset=5&vessel_id=4629&etd.gte=2016-06-16&sort=schedule,schedule_index' All end-points support the following two query parameters which are used to specify which “page” of results to return when there are more results than can be returned in one call:
limit=N: Return no more than N items. If this is omitted then a predefined maximum limit will be used. If N is greater than this value, it will be treated as if it was set to the maximum limit. limit=0 can be used to request just the summary and an empty items list.offset=N: Return items starting at this offset. If omitted, this defaults to zero.Most end-points also support a number of “exact match” query parameters. These will return items if the specified item attribute exactly matches the specified value (e.g. id=9 will return the item with the specified id). These are not documented further below other than to specify which exact match parameters are available.
Many end-points support a search query parameter. This performs a text search matching against a number of attributes. Which attributes are matched is described in the end-point descriptions below.
Date parameters expect dates to be formatted as YYYY-MM-DD.
Results are returned in JSON format and have the following general form:
{
"summary": {
"count": 4177,
...
}
"items": [ ... ]
}The items list returns a list of items that matched all the filters specified by query paramaters.
The summary object contains various aggregate data which varies depending upon the end-point called. This will always include at least a count value which indicates the number of results that are available (irrespective of any limit set).
Return a list of carriers that satisfy the specified criteria.
id, scac, name: Exact match parameterssearch: Matches any carrier scac, name or description which begins with the specified value.has_schedules: If set to 1, only return carriers which have schedules.{
"summary": {
"count": 1
},
"items": [
{
"address": "Level 11, 30 Convention Centre Place",
"bic": "ANNU",
"carrier_group": "CMA-CGM Group",
"city": "South Wharf Vic.",
"company": "ANL Container Line Pty. Ltd.",
"country": {
"id": "AU",
"name": "Australia"
},
"description": "Australian National Lines",
"email": "export@anl.com.au",
"established": "Acq.",
"fax": "+61 3 8842-5619",
"id": 81,
"kind": "deepsea",
"max_ships": 7,
"max_teu": 18698,
"name": "ANL",
"notice": "Acquired 1998 by CMA-CGM",
"phone": "+61 3 8842-5555",
"postcode": "3006",
"regions": "Global",
"scac": "ANLC",
"smdg": "ANL",
"website": "www.anl.com.au",
"year_est": 1999
},
...
],
}Return a list of contacts for a specified carrier.
carrier_id/carrier_scac (REQUIRED), country_id: Exact match parameters{
"summary": {
"count": 13,
"available_countries": [
{
"count": 6,
"country": {
"id": "AU",
"name": "AU"
}
},
...
],
},
"items": [
{
"id": 2296,
"is_agent": false,
"name": "ANL Container Line Pty Limited (Adelaide)",
"address": "306 St Vincent Street",
"city": "Adelaide",
"postcode": "5015",
"country": {
"id": "AU",
"name": "Australia"
},
"region": null,
"comments": [
"M-F 8:30 - 17:30",
...
],
"contacts": [
{
"desc": "Main Phone",
"type": "phone",
"value": "(61)-(08)- 8347 5400"
},
{
"desc": "Main Fax",
"type": "fax",
"value": "(61)-(08) 8447 1870"
},
{
"desc": "Export",
"type": "email",
"value": "export@anl.com.au"
},
...
],
"urls": [
"http://www.anl.com.au/view_agent.php?pname=offices&ccode=AU&cType=1&country=Australia,%20Adelaide&companyId=4",
...
]
},
...
]
}Returns a list of countries and/or regions that satisfy the specified criteria.
search: Matches any region name, country ISO code or country name which begins with the specified value.{
"summary": {
"count": 90
},
"items": [
{
"type": "country",
"id": "CA",
"value": {
"name": "Canada"
}
},
{
"type": "region",
"id": "916",
"value": {
"name": "California"
"country": {
"id": "US",
"name": "United States"
},
}
},
...
]
}Returns a list of vessel port calls that satisfy the specified criteria.
schedule_id, port_id/port_code, vessel_id/vessel_imo, voyage: Exact match parameterscarriers_id/carriers_scac: Comma-separated list of carrier IDs or SCACs to match againstcarriers_id.ne/carriers_scac.ne : Comma-separated list of carrier IDs or SCACs to excludecarrier_kinds: Comma-separated list of carrier kinds to filter by. Recognised values are deepsea, shortsea,feeder, roro and nvocc. If not specified, this defaults to deepsea,shortsea,feeder.routes_id/routes_code: Comma-separated list of route IDs or codes to match against.eta.gte/eta.lte/eta.lt: Only include vessels with an ETA (estimated time of arrival) at the port which is greater-than-or-equal, less-than-or-equal or less-than the specified date.etd.gte/etd.lte/etd.lt: Only include vessels with an ETD (estimated time of departure) at the port which is greater-than-or-equal, less-than-or-equal or less-than the specified date.sort: Comma-separated list of fields to order the returned items by. Supported field names are eta, carrier, schedule, schedule_index, port. The default, if no ordering is specified, is eta.with_terms: If set to 1, terminals will be included for each port in the response.carriers: Deprecated alias for carriers_idcarriers.ne: Deprecated alias for carriers_id.ne{
"summary": {
"count": 2,
"available_carriers": [
{
"count": 2,
"carrier": {
"id": 76,
"name": "CNC Line",
"scac": "CNCU"
},
}
...
],
"selected_carriers": [
51,
76
],
"excluded_carriers": []
},
"items": [
{
"carrier": {
"id": 76,
"name": "CNC Line",
"scac": "CNCU"
},
"eta": "2016-04-27",
"eta_time": "09:21",
"etd": "2016-04-27",
"etd_time": "22:06",
"port": {
"code": "CNNGB",
"country": {
"id": "CN",
"name": "China"
},
"id": 9980,
"latlong": [
-33.85,
151.2
],
"name": "Ningbo",
"region": {
"country_id": "CN",
"id": 144,
"name": "Zhejiang"
},
"terminals": [
{ "name": "Ningbo Beilun International Container Terminal" }
]
},
"route": {
"code": "HHXCNC",
"id": 14991,
"name": "HHX SERVICE"
},
"schedule_id": 18517708,
"schedule_index": 1,
"vessel": {
"id": 3418,
"imo": "9498690",
"name": "RBD JUTLANDIA"
},
"voyage": "1619JWCNC"
},
...
}Note that etd can be null in cases where the port is the last port of call for a vessel. Also eta_time and etd_time can be null if this information is not currently available.
schedule_index gives the position that the port call appears in the schedule that the port call is taken from.
terminals will only be included if the with_terms parameter was set.
Returns a list of all available origin/destination port-pairs for a specified carrier for which the /sailings end-point would return voyages.
carrier_id/carrier_scac: ID or SCAC of carrier to search for. This must be specified.end_date.gte/end_date.lte/end_date.lt: Only include voyages that arrive at the destination greater-than-or-equal, less-than-or-equal or less-than the specified date.{
"summary": {
"count": 3015
},
"items": [
[
"BDCGP",
"CNDLC"
],
[
"BDCGP",
"CNNSA"
],
[
"BDCGP",
"CNNGB"
],
...
}Each item returned in items gives an origin and destination LOCODE for which voyages are available for the specified carrier and date range.
Note that this end-point has an increased limit on the number of items that can be returned in a single call.
Returns a list of ports that satisfy the specified criteria.
id, code, name, region_id, country_id: Exact match parameterssearch: Matches any port name, port code or region name which begins with the specified value.with_terms: If set to 1, terminals will be included for each port in the response.in_schedules: If set to 1, only return ports for which scheduled port-calls exist.{
"summary": {
"count": 4177
},
"items": [
{
"code": "AEAUH",
"country": {
"id": "AE",
"name": "United Arab Emirates"
},
"id": 12,
"latlong": [
-33.85,
151.2
],
"name": "Abu Dhabi",
"region": {
"country_id": "AE",
"id": 5043,
"name": "Abu Z¸aby [Abu Dhabi]"
},
"terminals": [
{ "name": "Abu Dhabi Port" },
{ "name": "Khalifa Port Container Terminal", "code": "ADT" }
]
},
{
"code": "AEAJM",
"country": {
"id": "AE",
"name": "United Arab Emirates"
},
"id": 14,
"latlong": [
-33.85,
151.2
],
"name": "Ajman",
"region": null,
"terminals": []
}
]
}Note that region may be null if this is not available (as shown in the second item above).
terminals will only be included if the with_terms parameter was set.
Return a list of routes that satisfy the specified criteria.
id, code, name, vessel_id/vessel_imo, carrier_id/carrier_scac: Exact match parameterssearch: Matches any route code or name which begins with the specified value.ports_id/ports_code: Comma-separated list of port IDs or codes. No more than two can be specified. Match only routes which call at all the specified ports.start_date.gte/start_date.lte/start_date.lt: Only consider schedules with a start date greater-than-or-equal, less-than-or-equal or less-than the specified date.end_date.gte/end_date.lte/end_date.lt: Only consider schedules with an end date greater-than-or-equal, less-than-or-equal or less-than the specified date.with_terms: If set to 1, terminals will be included for each port in the response.{
"summary": {
"count": 52
},
"items": [
{
"id": 200,
"code": "ADS",
"name": "Adriatic Service",
"carrier": {
"id": 71,
"name": "Borchard",
"scac": "BORU"
},
"ports": [
{
"code": "CYLMS",
"country": {
"id": "CY",
"name": "Cyprus"
},
"id": 10526,
"latlong": [
34.68333333333333,
33.05
],
"name": "Limassol",
"region": {
"country_id": "CY",
"id": 1976,
"name": "Lemesos"
},
"terminals": [
{
"name": "Limassol West Container Terminal",
"code": "EGL"
}
]
},
...
]
"port_lists": [
[ [10116, 0], [10001, 1], [10043, 5], [51711, 19] ],
[ [51711, 0], [7687, 5], [10116, 25], [10001, 28], [10043, 32] ]
]
},
...
],
}The ports list contains all the ports currently visited by the route in port code order.
Each item in port_lists contains a list of pairs of port IDs (that can be looked up in ports) and transit times (in days from departure). These are identified “sub-routes” and list the ports in the order they are visited.
Return a list of voyages between specified origin and destinations that may involve transhipments.
origins_id/origins_code: Comma-separated list of origin port IDs or codes. At least one port must be specified.destinations_id/destinations_code: Comma-separated list of destination port IDs or codes. At least one port must be specified.duration.lte/duration.gte: Only include sailings with a duration less-than-or-equal or greater-than-or-equal to the specified number of days.carriers_id/carriers_scac: Comma-separated list of carrier IDs or SCACs to match againstcarriers_id.ne/carriers_scac.ne : Comma-separated list of carrier IDs or SCACs to excludecarrier_kinds: Comma-separated list of carrier kinds to filter by. Recognised values are deepsea, shortsea,feeder, roro and nvocc. If not specified, this defaults to deepsea,shortsea,feeder.transhipment_counts: Comma-separated list of transhipment counts (0,1 or 2) to match against.start_date.gte/start_date.lte/start_date.lt: Only include schedules with a start date greater-than-or-equal, less-than-or-equal or less-than the specified date.end_date.gte/end_date.lte/end_date.lt: Only include schedules with an end date greater-than-or-equal, less-than-or-equal or less-than the specified date.sort parameter: Comma-separated list of fields to order the returned items by. Supported field names are duration, carrier, start_date and end_date. The default, if no ordering is specified, is duration.with_terms: If set to 1, terminals will be included for each port in the response.with_distances: If set to 1, distance will be included for each leg in the response (if available).with_nearby_origins: If set to 1, ports that are nearby to the specified origin ports will also be included.with_nearby_destinations: If set to 1, ports that are nearby to the specified destination ports will also be included.with_alias_ports: If set to 1, common alternative LOCODEs for the specified ports will also be searched for. For example, a search for CNSHG, might also search for CNSHA and CNSGH.origin_ids: Deprecated alias for origins_iddestination_ids: Deprecated alias for destinations_idcarriers: Deprecated alias for carriers_idcarriers.ne: Deprecated alias for carriers_id.ne{
"summary": {
"available_carriers": [
{
"carrier": {
"id": 14,
"name": "Zim",
"scac": "ZIMU"
},
"count": 1,
"max_duration": 12,
"min_duration": 12,
"min_duration_ts_count": 0
},
...
],
"available_destination_ports": [
{
"count": 1,
"port": {
"code": "BRIOA",
"country": {
"id": "BR",
"name": "Brazil"
},
"id": 5058,
"latlong": [
-33.85,
151.2
],
"name": "Itapoa",
"region": {
"country_id": "BR",
"id": 78,
"name": "Santa Catarina"
}
}
},
...
],
"available_origin_ports": [
{
"count": 1,
"port": {
"code": "ARBUE",
"country": {
"id": "AR",
"name": "Argentina"
},
"id": 247,
"latlong": [
-33.85,
151.2
],
"name": "Buenos Aires",
"region": {
"country_id": "AR",
"id": 3,
"name": "Distrito Federal"
}
}
},
...
],
"available_transhipments": [
1
],
"count": 1,
"max_duration": 12,
"min_duration": 11,
"selected_carriers": [
14
],
"excluded_carriers": [],
"selected_duration.gte": 12,
"selected_duration.lte": 12,
"selected_transhipments": [
1
]
}
"items": [
{
"carrier": {
"id": 14,
"name": "Zim",
"scac": "ZIMU"
},
"duration": 12,
"legs": [
{
"distance": {
"miles": 429
},
"end": {
"date": "2016-05-25",
"port": {
"code": "BRRIG",
"country": {
"id": "BR",
"name": "Brazil"
},
"id": 5686,
"latlong": [
-33.85,
151.2
],
"name": "Rio Grande",
"region": {
"country_id": "BR",
"id": 77,
"name": "Rio Grande do Sul"
},
"terminals": [
{ "name": "TECON Container Terminal", "code": "TECRG" }
],
}
},
"route": {
"code": "GSA",
"id": 14591,
"name": "GULF SOUTH AMERICA SERVICE"
},
"schedule_id": 18289925,
"start": {
"date": "2016-05-21",
"port": {
"code": "ARBUE",
"country": {
"id": "AR",
"name": "Argentina"
},
"id": 247,
"latlong": [
-33.85,
151.2
],
"name": "Buenos Aires",
"region": {
"country_id": "AR",
"id": 3,
"name": "Distrito Federal"
},
"terminals": [
{ "name": "Exolgan Container Terminal", "code": "EXOL" }
]
}
},
"vessel": {
"id": 3949,
"imo": "9231262",
"name": "E.R. SWEDEN"
},
"voyage": "8"
},
{
"end": {
"date": "2016-06-02",
"port": {
"code": "BRIOA",
"country": {
"id": "BR",
"name": "Brazil"
},
"id": 5058,
"latlong": [
-33.85,
151.2
],
"name": "Itapoa",
"region": {
"country_id": "BR",
"id": 78,
"name": "Santa Catarina"
},
"terminals": [
{ "name": "Itapoa Container Terminal", "code": "ITP" }
]
}
},
"route": {
"code": "SAM",
"id": 1729,
"name": "SOUTH AMERICA MEDITERRANEAN SERVICE"
},
"schedule_id": 18290644,
"start": {
"date": "2016-05-29",
"port": {
"code": "BRRIG",
"country": {
"id": "BR",
"name": "Brazil"
},
"id": 5686,
"latlong": [
-33.85,
151.2
],
"name": "Rio Grande",
"region": {
"country_id": "BR",
"id": 77,
"name": "Rio Grande do Sul"
},
"terminals": [
{ "name": "TECON Container Terminal", "code": "TECRG" }
]
}
},
"vessel": {
"id": 8356,
"imo": "9480203",
"name": "MSC CADIZ"
},
"voyage": "24"
}
]
},
...
],
}Each result item contains a carrier, duration and a legs list. The legs list will contain between 1 and 3 elements. The start and end objects within each leg give details of the leg start port and date and end port and date respectively.
terminals will only be included if the with_terms parameter was set.
distance will only be included if the with_distances parameter was set and distance data is available for the leg. When present it will contain miles and (where relevant) a waypoint attribute.
Return a list of actual port calls that satisfy the specified criteria.
vessel_id/vessel_imo: Only return calls made by this vessel.ports_id/ports_code: Comma-separated list of port IDs or codes. Only return calls at the specified ports.sort parameter: Comma-separated list of fields to order the returned items by. Supported field names are ata_utc, port, vessel. The default, if no ordering is specified, is ata_utc.with_nearby_ports: If set to 1, ports that are nearby to the specified ports will also be included.{
"summary": {
"count": 36192
},
"items": [
{
"ata": "2020-03-01T08:03:06",
"ata_utc": "2020-03-01T00:03:06",
"atd": "2020-03-01T21:19:40",
"atd_utc": "2020-03-01T13:19:40",
"port": {
"code": "CNNGB",
"country": {
"id": "CN",
"name": "China"
},
"id": 9980,
"latlong": [
29.9833,
121.9
],
"name": "Ningbo",
"region": {
"country_id": "CN",
"id": 144,
"name": "Zhejiang"
}
},
"vessel": {
"id": 39084,
"imo": "9681247",
"name": "KOTA SEJARAH"
}
},
...
]
}Returns the remaining quota of API calls available in the current period. Note that this may not include the most recent calls.
This end-point does not accept any parameters and limit and offset can not be used.
{
"summary": {
"remaining_quota": 142105
},
}No summary.count or items are included in the response for this end-point.
Return a list of vessels that satisfy the specified criteria.
id, imo, call_sign, mmsi, name, carrier_id/carrier_scac: Exact match parameterssearch parameter: Matches any vessel name, IMO or call sign which begins with the specified value.sort parameter: Comma-separated list of fields to order the returned items by. Supported field names are carrier and vessel_name. The default, if no ordering is specified, is undefined.{
"summary": {
"count": 1
}
"items": [
{
"avg_teu": 3280,
"beam": "32.2",
"call_sign": "H9WV",
"carrier": {
"id": 9,
"name": "NYK",
"scac": "NYKS"
},
"co2": "136.8498",
"country": {
"id": "SG",
"name": "Singapore"
},
"draught": "13.5",
"dwt": 66750,
"engine_design": "B&W",
"engine_type": "9K90MC-C",
"gross_tonnage": 56100,
"handling_gear": "cont",
"id": 6306,
"imo": "9416989",
"length": "294.0",
"max_teu": 4922,
"mmsi": "563079000",
"name": "NYK ROMULUS",
"net_tonnage": 23203,
"owner": {
"id": 459,
"name": "Nippon Yusen Kaisha"
},
"port_registry": "SGSIN",
"power": "41129.000",
"previous_names": [],
"reefer_teu": 400,
"sfc": "165.00",
"ship_builder": "Hyundai Samho Heavy Industries Co. Ltd., South Kor",
"ship_type": "Container Ship",
"speed": "23.5",
"yard_hull": "S375",
"year_built": 2009
}
],
...
}Return a list of vessel schedules that satisfy the specified criteria.
id, vessel_id/vessel_imo, voyage, route_id, carrier_id/carrier_scac, start_port_id/start_port_code, end_port_id/end_port_code: Exact match parametersstart_date.gte/start_date.lte/start_date.lt: Only include schedules with a start date greater-than-or-equal, less-than-or-equal or less-than the specified date.end_date.gte/end_date.lte/end_date.lt: Only include schedules with an end date greater-than-or-equal, less-than-or-equal or less-than the specified date.carrier_kinds: Comma-separated list of carrier kinds to filter by. Recognised values are deepsea, shortsea,feeder, roro and nvocc. If not specified, this defaults to deepsea,shortsea,feeder.sort parameter: Comma-separated list of fields to order the returned items by. Supported field names are carrier_name, route_name, start_date, vessel_name and voyage, . The default, if no ordering is specified, is undefined.with_terms: If set to 1, terminals will be included for each port in the response.{
"summary": {
"count": 2
}
"items": [
{
"carrier": {
"id": 6,
"name": "COSCO",
"scac": "COSU"
},
"end_date": "2016-06-22",
"end_port": {
"code": "KRPUS",
"country": {
"id": "KR",
"name": "South Korea"
},
"id": 35103,
"latlong": [
-33.85,
151.2
],
"name": "Busan",
"region": {
"country_id": "KR",
"id": 666,
"name": "Busan Gwang'yeogsi [Pusan-Kwangyokshi]"
},
"terminals": []
},
"id": 10739655,
"last_update": "2016-07-29T07:50:09",
"route": {
"code": "GME",
"id": 11491,
"name": "GME GULF OF MEXICO EXPRESS GME"
},
"start_date": "2016-04-21",
"start_port": {
"code": "CNSHA",
"country": {
"id": "CN",
"name": "China"
},
"id": 10043,
"latlong": [
-33.85,
151.2
],
"name": "Shanghai",
"region": {
"country_id": "CN",
"id": 142,
"name": "Shanghai"
},
"terminals": [
{ "name": "Shanghai Shengdong International Cont Terminal Ltd" }
]
},
"vessel": {
"id": 9477,
"imo": "9484352",
"name": "COSCO JEDDAH"
},
"voyage": "4"
}
],
...
}terminals will only be included if the with_terms parameter was set.