JSONCargo

https://jsoncargo.com/documentation-api
Admin
JSONCargo is a container and vessel tracking API that provides developers with real-time shipment...
Tokens:16,495
Snippets:91
Trust Score:6.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Get Container Details - Python Example

Source: https://jsoncargo.com/documentation-api

Python example using requests library to call the Get Container Details endpoint. Requires requests installed.

```python
import requests
response = requests.get(
  'https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC',
  headers={'x-api-key': 'YOUR_API_KEY'}
)
print(response.json())
```

--------------------------------

### Get Container Details - Node.js Example

Source: https://jsoncargo.com/documentation-api

Node.js example using axios to call the Get Container Details endpoint. Requires axios installed.

```javascript
const axios = require('axios');
axios.get('https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
}).then(res => console.log(res.data));
```

--------------------------------

### Get Container Details - Go Example

Source: https://jsoncargo.com/documentation-api

Go example using net/http to call the Get Container Details endpoint. Imports fmt, io, and net/http.

```go
package main
import ("fmt"; "io"; "net/http")
func main() {
  req, _ := http.NewRequest("GET", "https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC", nil)
  req.Header.Add("x-api-key", "YOUR_API_KEY")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

--------------------------------

### Get Container Details - Java Example

Source: https://jsoncargo.com/documentation-api

Java example using OkHttpClient to call the Get Container Details endpoint. Requires OkHttp library.

```java
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
  .url("https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC")
  .addHeader("x-api-key", "YOUR_API_KEY")
  .build();
System.out.println(client.newCall(request).execute().body().string());
```

--------------------------------

### Get Container Details - PHP Example

Source: https://jsoncargo.com/documentation-api

PHP example using cURL to call the Get Container Details endpoint. Uses curl_init and curl_setopt_array.

```php
<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
]);
echo curl_exec($curl);
curl_close($curl);
```

--------------------------------

### Get Container Details - Ruby Example

Source: https://jsoncargo.com/documentation-api

Ruby example using net/http to call the Get Container Details endpoint. Requires uri and net/http.

```ruby
require "uri"; require "net/http"
url = URI("https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC")
req = Net::HTTP::Get.new(url)
req["x-api-key"] = "YOUR_API_KEY"
puts Net::HTTP.start(url.host){ |h| h.request(req) }.read_body
```

--------------------------------

### Response sample for Get Bill of Lading Containers

Source: https://jsoncargo.com/documentation-api

Example success response showing the bill of lading number, shipping line name, associated container count, container numbers, and last updated timestamp.

```json
{
  "data": {
    "bill_of_lading": "6464150910",
    "shipping_line_name": "COSCO SHIPPING Lines Co",
    "associated_containers": 1,
    "associated_container_numbers": [
      "OOLU9372428"
    ],
    "last_updated": "2026-09-28 09:30"
  }
}
```

--------------------------------

### Pro vessel tracking response sample

Source: https://jsoncargo.com/documentation-api

Example response for the pro endpoint showing all basic and additional fields.

```json
{
  "data": {
    "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
    "name": "MAERSK CHENNAI",
    "mmsi": "566093000",
    "imo": "9525338",
    "eni": null,
    "country_iso": "SG",
    "type": "Cargo - Hazard A (Major)",
    "type_specific": "Container Ship",
    "lat": 5.519612,
    "lon": 0.02949333,
    "speed": 0.1,
    "course": 133,
    "heading": 161,
    "current_draught": 12.9,
    "navigation_status": null,
    "destination": "CGPNR>GHTEM",
    "dest_port_uuid": "4e16eec7-c821-423f-7a61-31ca9cdd4601",
    "dest_port": "TEMA",
    "dest_port_unlocode": "GHTEM",
    "dep_port_uuid": "11ccc7a1-cb91-bfd8-fefd-520b892be1da",
    "dep_port": "POINTE NOIRE",
    "dep_port_unlocode": "CGPNR",
    "last_position_epoch": 1721925300,
    "last_position_UTC": "2024-07-25T16:35:00Z",
    "atd_epoch": 1721391180,
    "atd_UTC": "2024-07-19T12:13:00Z",
    "eta_epoch": 1721633940,
    "eta_UTC": "2024-07-22T07:39:00Z",
    "timezone_offset_sec": 0,
    "timezone": "GMT"
  }
}
```

--------------------------------

### Example error response for invalid_request

Source: https://jsoncargo.com/documentation-api

Shown under the 400 Invalid request response. The title varies based on the invalid input; this example shows a missing shipping_line parameter.

```json
{
  "error": {
    "code": "invalid_request",
    "title": "Missing required parameter shipping_line. Please provide shipping_line to select the carrier for Bill of Lading 6464150910.",
    "retryable": false
  }
}
```

--------------------------------

### Get Container Details - cURL Example

Source: https://jsoncargo.com/documentation-api

cURL command to call the Get Container Details endpoint for container MEDU9091004 at MSC. Replace YOUR_API_KEY with your actual API key.

```bash
curl --location 'https://api.jsoncargo.com/api/v1/containers/MEDU9091004/?shipping_line=MSC' \
  --header 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Port Finder - Response sample

Source: https://jsoncargo.com/documentation-api

Example successful response containing an array of port objects with details such as port name, coordinates, port type, and UN/LOCODE.

```json
{
  "data": [
    {
      "port_name": "LONDON",
      "port_code": null,
      "country": null,
      "lat": 51.49743,
      "lon": -0.04960075,
      "port_type": "Port",
      "size": null,
      "area": null,
      "city": null,
      "unlocode": "GBLON"
    },
    {
      "port_name": "NEW LONDON",
      "port_code": null,
      "country": null,
      "lat": 41.35305,
      "lon": -72.08705,
      "port_type": "Port",
      "size": null,
      "area": null,
      "city": null,
      "unlocode": "USNED"
    }
  ]
}
```

--------------------------------

### API Key Stats Response Sample

Source: https://jsoncargo.com/documentation-api

Sample JSON response for the Get API Key Usage Stats endpoint (GET /api/v1/api_key/stats). Shows plan, total requests, requests made, and requests available.

```json
{
  "data": {
    "plan": "MARINER",
    "requests_total": 10000,
    "requests_made": 6,
    "requests_available": 9994
  }
}
```

--------------------------------

### Response sample for bulk vessel tracking

Source: https://jsoncargo.com/documentation-api

Example response containing an array of vessel objects with live tracking data, including position, speed, and destination.

```json
{
  "data": [
    {
      "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
      "name": "MAERSK CHENNAI",
      "mmsi": "566093000",
      "imo": "9525338",
      "eni": null,
      "country_iso": "SG",
      "type": "Cargo - Hazard A (Major)",
      "type_specific": "Container Ship",
      "lat": 5.519552,
      "lon": 0.0297,
      "speed": 0,
      "course": 0,
      "heading": 169,
      "navigation_status": null,
      "destination": "CGPNR>GHT",
      "last_position_epoch": 1721927100,
      "last_position_UTC": "2024-07-25T17:05:00Z",
      "eta_epoch": null,
      "eta_UTC": null
    },
    {
      "uuid": "17959a4c-f5a9-ed71-1a42-5bfab00670ef",
      "name": "GARGANO",
      "mmsi": "235362000",
      "imo": "9249403",
      "eni": null,
      "country_iso": "GB",
      "type": "Other",
      "type_specific": "Supply Vessel",
      "lat": 54.01164,
      "lon": 6.747243,
      "speed": 0,
      "course": 218,
      "heading": 269,
      "navigation_status": null,
      "destination": "RWE OWF",
      "last_position_epoch": 1721927100,
      "last_position_UTC": "2024-07-25T17:05:00Z",
      "eta_epoch": null,
      "eta_UTC": null
    }
  ]
}
```

--------------------------------

### Vessel Specs Details - Response sample

Source: https://jsoncargo.com/documentation-api

Example successful response containing static vessel specifications such as name, MMSI, IMO, dimensions, tonnage, and speed.

```json
{
  "data": {
    "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
    "name": "MAERSK CHENNAI",
    "name_ais": "MAERSK CHENNAI",
    "mmsi": "566093000",
    "imo": "9525338",
    "eni": null,
    "country_iso": "SG",
    "country_name": "Singapore",
    "callsign": "9V9409",
    "type": "Cargo - Hazard A (Major)",
    "type_specific": "Container Ship",
    "gross_tonnage": 50869,
    "deadweight": 68898,
    "teu": "4500",
    "liquid_gas": null,
    "length": 249.12,
    "breadth": 37.4,
    "draught_avg": 10.021295387634936,
    "draught_max": 14.2,
    "speed_avg": 7.4,
    "speed_max": 20,
    "year_built": "2011",
    "is_navaid": false,
    "home_port": "SINGAPORE"
  }
}
```

--------------------------------

### GET /api/v1/vessel/basic

Source: https://jsoncargo.com/documentation-api

Fetches basic live position and status for a vessel using UUID, MMSI, or IMO as the identifier.

```APIDOC
## GET /api/v1/vessel/basic

### Description
Fetches basic live position and status for a vessel using UUID, MMSI, or IMO as the identifier.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/vessel/basic

### Parameters
#### Query Parameters
- **uuid** (string) - Required - One required identifier
- **mmsi** (string) - Required - One required identifier
- **imo** (string) - Required - One required identifier

### Response
#### Success Response (200)
Basic vessel details retrieved successfully

| Field | Type |
|---|---|
| uuid | string |
| name | string |
| mmsi | string |
| imo | string |
| eni | string |
| country_iso | string |
| type | string |
| type_specific | string |
| lat | number |
| lon | number |
| speed | number |
| course | number |
| heading | number |
| navigation_status | string |
| destination | string |
| last_position_epoch | integer |
| last_position_UTC | string |
| eta_epoch | integer |
| eta_UTC | string |

#### Response Example
```json
{
  "data": {
    "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
    "name": "MAERSK CHENNAI",
    "mmsi": "566093000",
    "imo": "9525338",
    "eni": null,
    "country_iso": "SG",
    "type": "Cargo - Hazard A (Major)",
    "type_specific": "Container Ship",
    "lat": 5.51935,
    "lon": 0.02906167,
    "speed": 0.1,
    "course": 256,
    "heading": 144,
    "navigation_status": null,
    "destination": "CGPNR>GHTEM",
    "last_position_epoch": 1721842560,
    "last_position_UTC": "2024-07-24T17:36:00Z",
    "eta_epoch": 1721633940,
    "eta_UTC": "2024-07-22T07:39:00Z"
  }
}
```

#### Error Responses

##### 400 Invalid request
```json
{
  "error": {
    "title": "Invalid request"
  }
}
```

##### 404 Vessel not found
```json
{
  "error": {
    "title": "Vessel not found"
  }
}
```

##### 429 Too many requests
```json
{
  "error": {
    "title": "Too many requests"
  }
}
```

##### 500 Internal server error
```json
{
  "error": {
    "title": "Internal server error"
  }
}
```
```

--------------------------------

### GET /api/v1/vessel/specs

Source: https://jsoncargo.com/documentation-api

Fetch static technical specifications for a vessel by UUID, MMSI, or IMO. Use GET /api/v1/vessel/specs with one of the required query parameters.

```APIDOC
## [GET] /api/v1/vessel/specs

### Description
Fetches static technical specifications for a vessel by UUID, MMSI, or IMO.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/vessel/specs

### Parameters
#### Query Parameters
- **uuid** (string) - one required - The vessel UUID.
- **mmsi** (string) - one required - The vessel MMSI.
- **imo** (string) - one required - The vessel IMO number.

### Response
#### Success Response (200)
- **data** (object) - Contains vessel technical specifications.
  - **uuid** (string) - Vessel UUID.
  - **name** (string) - Vessel name.
  - **name_ais** (string) - Vessel name as used in AIS.
  - **mmsi** (string) - MMSI number.
  - **imo** (string) - IMO number.
  - **eni** (string or null) - ENI number if applicable.
  - **country_iso** (string) - Country ISO code.
  - **country_name** (string) - Country name.
  - **callsign** (string) - Callsign.
  - **type** (string) - Vessel type.
  - **type_specific** (string) - Specific vessel type.
  - **gross_tonnage** (number) - Gross tonnage.
  - **deadweight** (number) - Deadweight tonnage.
  - **teu** (string) - TEU capacity.
  - **liquid_gas** (null or number) - Liquid gas capacity.
  - **length** (number) - Vessel length in meters.
  - **breadth** (number) - Vessel breadth in meters.
  - **draught_avg** (number) - Average draught in meters.
  - **draught_max** (number) - Maximum draught in meters.
  - **speed_avg** (number) - Average speed in knots.
  - **speed_max** (number) - Maximum speed in knots.
  - **year_built** (string) - Year built.
  - **is_navaid** (boolean) - Whether the vessel is a navigational aid.
  - **home_port** (string) - Home port.

#### Response Example
{
  "data": {
    "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
    "name": "MAERSK CHENNAI",
    "name_ais": "MAERSK CHENNAI",
    "mmsi": "566093000",
    "imo": "9525338",
    "eni": null,
    "country_iso": "SG",
    "country_name": "Singapore",
    "callsign": "9V9409",
    "type": "Cargo - Hazard A (Major)",
    "type_specific": "Container Ship",
    "gross_tonnage": 50869,
    "deadweight": 68898,
    "teu": "4500",
    "liquid_gas": null,
    "length": 249.12,
    "breadth": 37.4,
    "draught_avg": 10.021295387634936,
    "draught_max": 14.2,
    "speed_avg": 7.4,
    "speed_max": 20,
    "year_built": "2011",
    "is_navaid": false,
    "home_port": "SINGAPORE"
  }
}

#### Error Responses
- **400 Invalid request** - {"error":{"title":"Invalid request"}}
- **404 Vessel not found** - {"error":{"title":"Vessel not found"}}
- **429 Too many requests** - {"error":{"title":"Too many requests"}}
- **500 Internal server error** - {"error":{"title":"Internal server error"}}

```

--------------------------------

### Response sample for basic vessel details

Source: https://jsoncargo.com/documentation-api

Example of a successful 200 response containing vessel details such as uuid, name, mmsi, imo, position, speed, course, and timestamps.

```json
{
  "data": {
    "uuid": "b8625b67-7142-cfd1-7b85-595cebfe4191",
    "name": "MAERSK CHENNAI",
    "mmsi": "566093000",
    "imo": "9525338",
    "eni": null,
    "country_iso": "SG",
    "type": "Cargo - Hazard A (Major)",
    "type_specific": "Container Ship",
    "lat": 5.51935,
    "lon": 0.02906167,
    "speed": 0.1,
    "course": 256,
    "heading": 144,
    "navigation_status": null,
    "destination": "CGPNR>GHTEM",
    "last_position_epoch": 1721842560,
    "last_position_UTC": "2024-07-24T17:36:00Z",
    "eta_epoch": 1721633940,
    "eta_UTC": "2024-07-22T07:39:00Z"
  }
}
```

--------------------------------

### GET /api/v1/port/find

Source: https://jsoncargo.com/documentation-api

Fetches port details by coordinates and radius, name, country code, or port type. At least one parameter must be provided.

```APIDOC
## [GET] /api/v1/port/find

### Description
Fetches port details by coordinates and radius, name, country code, or port type. At least one parameter must be provided.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/port/find

### Parameters
#### Query Parameters
- **lat** (number) - Optional - Latitude of the location.
- **lon** (number) - Optional - Longitude of the location.
- **radius** (number) - Optional - Search radius in nautical miles.
- **name** (string) - Optional - Port name.
- **country_iso** (string) - Optional - Country ISO code.
- **port_type** (string) - Optional - Port type.
- **fuzzy** (integer) - Optional - Enable fuzzy matching.

### Response
#### Success Response (200)
- **data** (array of objects) - List of ports.
  - **port_name** (string) - Port name.
  - **port_code** (string or null) - Port code.
  - **country** (string or null) - Country name.
  - **lat** (number) - Latitude.
  - **lon** (number) - Longitude.
  - **port_type** (string) - Port type.
  - **size** (string or null) - Port size.
  - **area** (string or null) - Port area.
  - **city** (string or null) - City.
  - **unlocode** (string) - UN/LOCODE code.

#### Response Example
{
  "data": [
    {
      "port_name": "LONDON",
      "port_code": null,
      "country": null,
      "lat": 51.49743,
      "lon": -0.04960075,
      "port_type": "Port",
      "size": null,
      "area": null,
      "city": null,
      "unlocode": "GBLON"
    },
    {
      "port_name": "NEW LONDON",
      "port_code": null,
      "country": null,
      "lat": 41.35305,
      "lon": -72.08705,
      "port_type": "Port",
      "size": null,
      "area": null,
      "city": null,
      "unlocode": "USNED"
    }
  ]
}

#### Error Responses
- **400 Invalid request** - {"error":{"title":"Invalid request"}}
- **404 Port not found** - {"error":{"title":"Port not found"}}
- **429 Too many requests** - {"error":{"title":"Too many requests"}}
- **500 Internal server error** - {"error":{"title":"Internal server error"}}

```

--------------------------------

### Terminal Finder API Response Sample

Source: https://jsoncargo.com/documentation-api

Sample JSON response for the Terminal Finder API (GET /api/v1/terminal/). Shows terminal details including UN/LOCODE, coordinates, and address.

```json
{
    "data": [{
        "unlocode": "CNCQI",
        "alt_unlocode": "CNCHQ",
        "code": "CUNTAN",
        "terminal_name": "CUNTAN TERMINAL",
        "company_name": "CHONGQING INTERNATIONAL CONTAINER TERMINAL CO., LTD.",
        "lat": "29.618056",
        "lon": "106.591667",
        "url": "http://www.cqgj.com.cn/",
        "address": "No. 306, Hai'er Road, Jiangbei District, Chongqing, China"
    }]
}
```

--------------------------------

### Example 400 invalid_request error response

Source: https://jsoncargo.com/documentation-api

Shown for the 400 Invalid request response. The error code is invalid_request and is not retryable. The title varies based on the invalid input; this example shows an unknown shipping line.

```json
{
  "error": {
    "code": "invalid_request",
    "title": "Shipping line NOT_A_CARRIER for tracking number ABCD1234567 is not recognized. Supported shipping_line values are: MSC, ONE, COSCO, YANG_MING, EVERGREEN, CMA_CGM, MAERSK, HAPAG_LLOYD, HMM, ZIM, PIL.",
    "retryable": false
  }
}
```

--------------------------------

### Error Format Example

Source: https://jsoncargo.com/documentation-api

Shows the JSON structure of an error response with fields code, title, and retryable. The retryable field indicates whether the request may succeed later.

```json
{
  "error": {
    "code": "upstream_unavailable",
    "title": "Tracking data is temporarily unavailable. Please try again later.",
    "retryable": true
  }
}
```

--------------------------------

### Vessel Finder API response sample

Source: https://jsoncargo.com/documentation-api

Example success response for the Vessel Finder API. Shows a vessel object with fields like name, mmsi, country_iso, type, and dimensions, plus a meta object with a next pagination token (null on the last page).

```json
{
  "data": [
    {
      "uuid": "335087a4-d70f-58ba-7e51-d8c0e26f069c",
      "name": "ERIC",
      "name_ais": "ERIC",
      "mmsi": "244700187",
      "imo": null,
      "eni": "2000604",
      "country_iso": "NL",
      "country_name": "Netherlands",
      "callsign": "PH5504",
      "type": "Tug",
      "type_specific": "Inland, Passenger Ship without Accommodation",
      "gross_tonnage": null,
      "deadweight": null,
      "teu": null,
      "liquid_gas": null,
      "length": 19.3,
      "breadth": 3.2,
      "draught_avg": null,
      "draught_max": null,
      "speed_avg": 6.7,
      "speed_max": 9,
      "year_built": null,
      "is_navaid": false,
      "home_port": null
    }
  ],
  "meta": {
    "next": null
  }
}
```

--------------------------------

### GET https://api.jsoncargo.com/api/v1/api_key/stats

Source: https://jsoncargo.com/documentation-api

Check your current plan, total requests, requests used, and requests remaining. No query parameters required; the response is based on the API key provided in the request header.

```APIDOC
## GET https://api.jsoncargo.com/api/v1/api_key/stats

### Description
Check your current plan, total requests, requests used, and requests remaining.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/api_key/stats

### Parameters
No query parameters required. The response is based on the API key provided in the request header.

### Response Sample
```
{
  "data": {
    "plan": "MARINER",
    "requests_total": 10000,
    "requests_made": 6,
    "requests_available": 9994
  }
}
```

### Error Responses
- 404 API key stats not found: ```
{
  "error": {
    "title": "API key stats not found"
  }
}
```
- 429 Too many requests: ```
{
  "error": {
    "title": "Too many requests"
  }
}
```
- 500 Internal server error: ```
{
  "error": {
    "title": "Internal server error"
  }
}
```
```

--------------------------------

### GET /api/v1/vessel/finder

Source: https://jsoncargo.com/documentation-api

Fetches static ship data. Search and filter vessels by name, type, flag state, tonnage, dimensions, and build year. Results are paged; use the 'next' parameter to fetch subsequent pages.

```APIDOC
## GET /api/v1/vessel/finder

### Description
Fetches static ship data. Search and filter vessels by name, type, flag state, tonnage, dimensions, and build year.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/vessel/finder

### Parameters
#### Query Parameters
- **name** (string) - Optional - Vessel name to search for.
- **fuzzy** (integer) - Optional - Enables fuzzy matching on the name.
- **type** (string) - Optional - Vessel type filter.
- **type_specific** (string) - Optional - Specific vessel type filter.
- **country_iso** (string) - Optional - Flag state ISO code filter.
- **gross_tonnage_min** (integer) - Optional - Minimum gross tonnage filter.
- **gross_tonnage_max** (integer) - Optional - Maximum gross tonnage filter.
- **deadweight_min** (integer) - Optional - Minimum deadweight filter.
- **deadweight_max** (integer) - Optional - Maximum deadweight filter.
- **length_min** (number) - Optional - Minimum length filter.
- **length_max** (number) - Optional - Maximum length filter.
- **breadth_min** (number) - Optional - Minimum breadth filter.
- **breadth_max** (number) - Optional - Maximum breadth filter.
- **year_built_min** (integer) - Optional - Minimum build year filter.
- **year_built_max** (integer) - Optional - Maximum build year filter.
- **next** (string) - Optional - Pagination token from the previous response's `meta.next`.

### Response
#### Success Response (200)
- **data** (array) - List of vessel objects.
- **data[].uuid** (string) - Unique identifier for the vessel.
- **data[].name** (string) - Vessel name.
- **data[].name_ais** (string) - AIS name.
- **data[].mmsi** (string) - MMSI number.
- **data[].imo** (string|null) - IMO number.
- **data[].eni** (string|null) - ENI number.
- **data[].country_iso** (string) - Country ISO code.
- **data[].country_name** (string) - Country name.
- **data[].callsign** (string) - Callsign.
- **data[].type** (string) - Vessel type.
- **data[].type_specific** (string) - Specific vessel type.
- **data[].gross_tonnage** (number|null) - Gross tonnage.
- **data[].deadweight** (number|null) - Deadweight.
- **data[].teu** (number|null) - TEU capacity.
- **data[].liquid_gas** (number|null) - Liquid gas capacity.
- **data[].length** (number) - Length in meters.
- **data[].breadth** (number) - Breadth in meters.
- **data[].draught_avg** (number|null) - Average draught.
- **data[].draught_max** (number|null) - Maximum draught.
- **data[].speed_avg** (number) - Average speed.
- **data[].speed_max** (number) - Maximum speed.
- **data[].year_built** (integer|null) - Year built.
- **data[].is_navaid** (boolean) - Whether the vessel is a navigational aid.
- **data[].home_port** (string|null) - Home port.
- **meta** (object) - Pagination metadata.
- **meta.next** (string|null) - Token for the next page, or null on the last page.

#### Response Example
```json
{
  "data": [
    {
      "uuid": "335087a4-d70f-58ba-7e51-d8c0e26f069c",
      "name": "ERIC",
      "name_ais": "ERIC",
      "mmsi": "244700187",
      "imo": null,
      "eni": "2000604",
      "country_iso": "NL",
      "country_name": "Netherlands",
      "callsign": "PH5504",
      "type": "Tug",
      "type_specific": "Inland, Passenger Ship without Accommodation",
      "gross_tonnage": null,
      "deadweight": null,
      "teu": null,
      "liquid_gas": null,
      "length": 19.3,
      "breadth": 3.2,
      "draught_avg": null,
      "draught_max": null,
      "speed_avg": 6.7,
      "speed_max": 9,
      "year_built": null,
      "is_navaid": false,
      "home_port": null
    }
  ],
  "meta": {
    "next": null
  }
}
```

#### Error Responses
- **400 Invalid request** - The request is malformed or missing required parameters.
  ```json
  {
    "error": {
      "title": "Invalid request"
    }
  }
  ```
- **404 Vessel not found** - No vessel matches the given criteria.
  ```json
  {
    "error": {
      "title": "Vessel not found"
    }
  }
  ```
- **429 Too many requests** - Rate limit exceeded.
  ```json
  {
    "error": {
      "title": "Too many requests"
    }
  }
  ```
- **500 Internal server error** - An unexpected error occurred on the server.
  ```json
  {
    "error": {
      "title": "Internal server error"
    }
  }
  ```
```

--------------------------------

### GET https://api.jsoncargo.com/api/v1/terminal/

Source: https://jsoncargo.com/documentation-api

Retrieve terminal details using a UN/LOCODE. The endpoint accepts a mandatory unlocode query parameter and optional pagination parameters.

```APIDOC
## GET https://api.jsoncargo.com/api/v1/terminal/

### Description
Retrieve terminal details using a UN/LOCODE.

### Method
GET

### Endpoint
https://api.jsoncargo.com/api/v1/terminal/

### Parameters
#### Query Parameters
- **unlocode** (string) - Required - Minimum 2 characters. UN/LOCODE of the port (e.g. CNCQI).
- **page / limit** (string) - Optional

### Response Sample
```
{
    "data": [{
        "unlocode": "CNCQI",
        "alt_unlocode": "CNCHQ",
        "code": "CUNTAN",
        "terminal_name": "CUNTAN TERMINAL",
        "company_name": "CHONGQING INTERNATIONAL CONTAINER TERMINAL CO., LTD.",
        "lat": "29.618056",
        "lon": "106.591667",
        "url": "http://www.cqgj.com.cn/",
        "address": "No. 306, Hai'er Road, Jiangbei District, Chongqing, China"
    }]
}
```
```

--------------------------------

### GET /api/v1/containers/bol/{bol_number}/

Source: https://jsoncargo.com/documentation-api

Retrieves the container numbers associated with a given Bill of Lading number. Requires a shipping line query parameter.

```APIDOC
## GET /api/v1/containers/bol/{bol_number}/

### Description
Fetches the container numbers associated with a Bill of Lading (B/L) number.

### Method
GET

### Endpoint
/api/v1/containers/bol/{bol_number}/

### Parameters
#### Path Parameters
- **bol_number** (string) - Required - Bill of Lading number. Alphanumeric characters only.

#### Query Parameters
- **shipping_line** (string) - Required - Shipping line for this request, for example `MAERSK`, `COSCO`, `CMA_CGM`, `YANG_MING`. See the Shipping Lines table.

### Response
#### Success Response (200)
- **bill_of_lading** (string) - Bill of lading number.
- **shipping_line_name** (string) - Name of the shipping line.
- **associated_containers** (integer) - Number of associated containers.
- **associated_container_numbers** (array of strings) - Container numbers associated with the bill of lading.
- **last_updated** (string) - Last updated timestamp.

#### Response Example
```json
{
  "data": {
    "bill_of_lading": "6464150910",
    "shipping_line_name": "COSCO SHIPPING Lines Co",
    "associated_containers": 1,
    "associated_container_numbers": [
      "OOLU9372428"
    ],
    "last_updated": "2026-09-28 09:30"
  }
}
```

### Error Responses
#### 400 Invalid request
- **Error code**: invalid_request - Not retryable. The title varies based on the issue.

| When | title |
|---|---|
| B/L number has non-alphanumeric characters | Bill of Lading {bol_number} is invalid. Must contain only alphanumeric characters. |
| shipping_line missing | Missing required parameter shipping_line. Please provide shipping_line to select the carrier for Bill of Lading {bol_number}. |
| Unknown shipping line | Shipping line {shipping_line} for Bill of Lading {bol_number} is not recognized. Supported shipping_line values are: {list}. |
| Shipping line not enabled | Shipping line {shipping_line} for Bill of Lading {bol_number} is not supported. Supported shipping_line values are: {list}. |
| Any other invalid input | The request is invalid. |

Example:
```json
{
  "error": {
    "code": "invalid_request",
    "title": "Missing required parameter shipping_line. Please provide shipping_line to select the carrier for Bill of Lading 6464150910.",
    "retryable": false
  }
}
```

#### 401 Missing API key
- Returned by the API-key check, so the body has `title` only.
```json
{
  "error": {
    "title": "API key header is missing."
  }
}
```

#### 403 Invalid API key
- Returned by the API-key check, so the body has `title` only. `{api_key}` is the key you sent.
- API key not found: `{"error":{"title":"API key {api_key} does not exist."}}`
- Key lacks admin permission: `{"error":{"title":"API key {api_key} does not have admin permissions."}}`

#### 404 Not found
- **Error code**: unknown_resource - Not retryable: no data was found for this Bill of Lading number and shipping line.
```json
{
  "error": {
    "code": "unknown_resource",
    "title": "The requested resource was not found.",
    "retryable": false
  }
}
```

#### 429 Rate limit exceeded
- The API key exceeded its per-minute or monthly quota. Returned by the API-key check, so the body has `title` only. Retry after the limit window passes.
- Per-minute limit: `{"error":{"title":"API key exceeded its rate limit (type=MINUTE)."}}`
- Monthly limit: `{"error":{"title":"API key exceeded its rate limit (type=MONTHLY)."}}`

#### 500 Internal server error
- **Error code**: internal_error - Retryable: an unexpected error on our side.
```json
{
  "error": {
    "code": "internal_error",
    "title": "An unexpected error occurred.",
    "retryable": true
  }
}
```

#### 502 Tracking data unavailable
- **Error codes**: upstream_unavailable (retryable) or content_unavailable (not retryable): tracking data for this request is temporarily unavailable, or is not available for this shipment.
- Temporarily unavailable (retryable):
```json
{
  "error": {
    "code": "upstream_unavailable",
    "title": "Tracking data is temporarily unavailable. Please try again later.",
    "retryable": true
  }
}
```
- Data not available (not retryable):
```json
{
  "error": {
    "code": "content_unavailable",
    "title": "Data for this request is currently unavailable.",
    "retryable": false
  }
}
```
```
Tokens:
Raw