Shipping Data Repository - Acuity Lab API Documentation

Base URL: https://acuitylab.net/api/shipping

Authentication

All requests to the Shipping Data API require an API key. Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Error Responses

200 OK: Request was successful.
400 Bad Request: The request was invalid.
401 Unauthorized: API key is missing or invalid.
403 Forbidden: The API key does not have permissions for the requested resource.
404 Not Found: The requested resource could not be found.
500 Internal Server Error: Something went wrong on the server side.

2.1 GET /shipping/ports

Retrieve shipping data by ports, including the list of ships arriving and departing from specific ports.

GET https://acuitylab.net/api/shipping/ports?port_name=LosAngeles&country=US&date_range=2024-01-01to2024-01-31

{
    "port": "Los Angeles",
    "country": "US",
    "ships": [
        {
            "ship_id": "SHIP12345",
            "ship_name": "Evergreen Voyager",
            "arrival_date": "2024-02-20",
            "departure_date": "2024-02-22",
            "cargo_type": "containers",
            "cargo_weight": "30000 tons"
        },
        {
            "ship_id": "SHIP67890",
            "ship_name": "Horizon Trader",
            "arrival_date": "2024-02-25",
            "departure_date": "2024-02-27",
            "cargo_type": "bulk goods",
            "cargo_weight": "40000 tons"
        }
    ]
}

2.2 GET /shipping/ships

Retrieve data on individual ship movements, including arrival and departure times, cargo details, and routes.

GET https://acuitylab.net/api/shipping/ships?ship_id=SHIP98765&cargo_type=containers&date_range=2024-01-01to2024-01-31

{
    "ship_id": "SHIP98765",
    "ship_name": "Atlantic Mariner",
    "movements": [
        {
            "port": "Shanghai",
            "arrival_date": "2024-03-10",
            "departure_date": "2024-03-12",
            "route": "Shanghai to Los Angeles",
            "cargo": {
                "type": "containers",
                "weight": "35000 tons"
            }
        },
        {
            "port": "Los Angeles",
            "arrival_date": "2024-03-20",
            "departure_date": "2024-03-22",
            "route": "Los Angeles to Rotterdam",
            "cargo": {
                "type": "containers",
                "weight": "37000 tons"
            }
        }
    ]
}

2.3 GET /shipping/delays

Retrieve information about shipping delays caused by various factors (weather, port congestion, strikes, etc.).

GET https://acuitylab.net/api/shipping/delays?region=Asia&country=China&delay_cause=weather

{
    "region": "Asia",
    "country": "China",
    "delays": [
        {
            "port": "Shanghai",
            "delay_cause": "Weather",
            "delay_duration": "2 days",
            "impact": "50 ships delayed"
        },
        {
            "port": "Hong Kong",
            "delay_cause": "Congestion",
            "delay_duration": "3 days",
            "impact": "30 ships delayed"
        }
    ]
}

2.4 GET /shipping/cargo-status

Retrieve the real-time status of cargo shipments, including location, estimated delivery, and condition.

GET https://acuitylab.net/api/shipping/cargo-status?cargo_id=CARGO12345&shipment_status=intransit

{
    "cargo_id": "CARGO12345",
    "cargo_type": "oil",
    "status": "in transit",
    "last_known_location": {
        "latitude": "24.156",
        "longitude": "-89.567",
        "timestamp": "2024-03-05T12:00:00Z"
    },
    "estimated_delivery": "2024-03-10"
}

2.5 GET /shipping/ports-traffic

Retrieve real-time data on port traffic, including the number of ships arriving and departing.

GET https://acuitylab.net/api/shipping/ports-traffic?port_name=Singapore&date_range=2024-01-01to2024-01-31

{
    "port": "Singapore",
    "traffic": {
        "arrivals": 120,
        "departures": 115,
        "average_wait_time": "2 hours"
    }
}

2.6 GET /shipping/rates

Retrieve shipping rates based on cargo type, route, and port conditions.

GET https://acuitylab.net/api/shipping/rates?cargo_type=containers&origin_port=Shanghai&destination_port=LosAngeles

{
    "cargo_type": "containers",
    "origin_port": "Shanghai",
    "destination_port": "Los Angeles",
    "rate": {
        "amount": "$2,500",
        "currency": "USD",
        "conditions": "Based on current port congestion"
    }
}

2.7 GET /shipping/environmental-impact

Retrieve data on the environmental impact of shipping activities, including carbon emissions per route.

GET https://acuitylab.net/api/shipping/environmental-impact?ship_id=SHIP12345&route=ShanghaiToLosAngeles

{
    "ship_id": "SHIP12345",
    "route": "Shanghai to Los Angeles",
    "carbon_emissions": {
        "total_emissions": "500 tons CO2",
        "efficiency": "20 tons per day",
        "offset_program": "Reforestation in the Amazon"
    }
}