Shipments API

Search, retrieve, and analyze global shipment data to identify market opportunities.

POST/api/v1/shipments/search

Search shipment records based on origin, destination, HS codes, and other criteria.

Request Body

{
  "origin": "US",
  "destination": "CN",
  "hsCode": "8517",
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "limit": 100,
  "offset": 0
}

Response

{
  "success": true,
  "data": {
    "shipments": [
      {
        "id": "shp_123456789",
        "origin": "US",
        "destination": "CN",
        "hsCode": "8517",
        "description": "Telephones for cellular networks",
        "quantity": 10000,
        "weight": 5000,
        "value": 250000,
        "currency": "USD",
        "shipDate": "2024-06-15",
        "shipper": {
          "name": "Tech Corp",
          "country": "US"
        },
        "consignee": {
          "name": "Electronics Ltd",
          "country": "CN"
        }
      }
    ],
    "total": 1234,
    "limit": 100,
    "offset": 0
  }
}

GET/api/v1/shipments/:id

Retrieve detailed information about a specific shipment.

Path Parameters

Parameter	Type	Description
id	string	Unique shipment identifier

Response

{
  "success": true,
  "data": {
    "id": "shp_123456789",
    "origin": "US",
    "destination": "CN",
    "hsCode": "8517",
    "description": "Telephones for cellular networks",
    "quantity": 10000,
    "weight": 5000,
    "value": 250000,
    "currency": "USD",
    "shipDate": "2024-06-15",
    "shipper": {
      "name": "Tech Corp",
      "address": "123 Tech Street",
      "city": "San Francisco",
      "country": "US"
    },
    "consignee": {
      "name": "Electronics Ltd",
      "address": "456 Import Ave",
      "city": "Shanghai",
      "country": "CN"
    }
  }
}

POST/api/v1/shipments/analyze

Get analytics and insights from shipment data including trends, top markets, and trade flows.

Request Body

{
  "hsCode": "8517",
  "origin": "US",
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "groupBy": "destination"
}

Response

{
  "success": true,
  "data": {
    "totalShipments": 1234,
    "totalValue": 125000000,
    "topDestinations": [
      {
        "country": "CN",
        "shipments": 456,
        "value": 45000000
      },
      {
        "country": "JP",
        "shipments": 234,
        "value": 28000000
      }
    ],
    "monthlyTrend": [
      { "month": "2024-01", "shipments": 98, "value": 9800000 },
      { "month": "2024-02", "shipments": 102, "value": 10200000 }
    ]
  }
}