{
  "openapi": "3.0.3",
  "info": {
    "title": "SHAQ Logistics Freight API",
    "description": "Real-time ocean freight rate search, booking, and tracking API. 160,000+ live carrier rates from COSCO and other shipping lines for 487+ trade lanes from China to global destinations.",
    "version": "1.0.0",
    "contact": {
      "name": "SHAQ Logistics",
      "url": "https://search.shaq-logistics.com",
      "email": "support@shaq-logistics.com"
    }
  },
  "servers": [
    {
      "url": "https://search.shaq-logistics.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/search-rates": {
      "get": {
        "summary": "Search freight rates",
        "description": "Search real-time FCL and LCL freight rates between two ports.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Origin port name (e.g., Shenzhen, Shanghai, Ningbo)"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Destination port name (e.g., Los Angeles, Hamburg)"
          },
          {
            "name": "container_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "20GP",
                "40GP",
                "40HQ"
              ]
            },
            "description": "Container type for FCL. Omit for LCL."
          }
        ],
        "responses": {
          "200": {
            "description": "List of freight rates with carrier, price, transit time"
          }
        }
      }
    },
    "/api/ports": {
      "get": {
        "summary": "Search ports",
        "description": "Search ports by name, code, or country. Supports aliases (e.g., YANTIAN -> Shenzhen).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Search query"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "Max results"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching ports"
          }
        }
      }
    },
    "/api/freight-index": {
      "get": {
        "summary": "Get freight market index",
        "description": "Market rate index for major trade lanes.",
        "responses": {
          "200": {
            "description": "Freight index data"
          }
        }
      }
    },
    "/api/bookings": {
      "post": {
        "summary": "Create booking",
        "description": "Create a shipping booking. Required fields: contact_name, contact_phone, contact_email, supplier_name, supplier_phone, supplier_email, po_number.",
        "responses": {
          "200": {
            "description": "Booking created with booking number"
          }
        }
      }
    },
    "/api/bookings/{booking_id}": {
      "get": {
        "summary": "Track booking",
        "description": "Track booking status, ETD, ETA, and milestones.",
        "parameters": [
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booking status and tracking info"
          }
        }
      }
    },
    "/api/subscribe-rate": {
      "post": {
        "summary": "Subscribe to rate alerts",
        "description": "Subscribe to email notifications when rates change for specific routes.",
        "responses": {
          "200": {
            "description": "Subscription confirmed"
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "summary": "Submit contact inquiry",
        "description": "Submit a contact form inquiry.",
        "responses": {
          "200": {
            "description": "Inquiry submitted"
          }
        }
      }
    },
    "/sse": {
      "get": {
        "summary": "MCP Server (SSE)",
        "description": "Model Context Protocol server over Server-Sent Events. Connect AI assistants (Claude, Cursor, ChatGPT) to search freight rates, create bookings, and track shipments.",
        "responses": {
          "200": {
            "description": "SSE stream for MCP protocol"
          }
        }
      }
    }
  }
}