{
  "openapi": "3.1.0",
  "info": {
    "title": "Best Shipping Agent API",
    "version": "1.0.0",
    "summary": "Read-only China shipping-agent price comparison, read off each provider's own calculator.",
    "description": "Independent comparison of China shipping agents (Taobao / Weidian / 1688 forwarding): each price was read off the provider's own public calculator in a real browser and is published with a timestamped recording. No ads, no affiliate links, no paid placement. Promotional prices are excluded; prices exist only at the captured checkpoint weights and are never interpolated. Free, no key, CORS open.",
    "contact": {
      "name": "Best Shipping Agent",
      "email": "hello@bestshippingagent.com",
      "url": "https://bestshippingagent.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://bestshippingagent.com"
    }
  ],
  "externalDocs": {
    "description": "Methodology",
    "url": "https://bestshippingagent.com/about"
  },
  "paths": {
    "/api/v1/quotes": {
      "get": {
        "operationId": "compareShippingQuotes",
        "summary": "Compare shipping quotes at one parcel weight",
        "description": "Every published shipping route at one checkpoint weight, cheapest first, for the published destination. Use it to answer 'which shipping agent is cheapest for an N kg parcel'.",
        "parameters": [
          {
            "name": "weight_g",
            "in": "query",
            "required": true,
            "description": "Parcel weight in grams; must be a captured checkpoint.",
            "schema": {
              "type": "integer",
              "enum": [
                500,
                750,
                1000,
                2000,
                5000,
                10000,
                20000
              ]
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 destination.",
            "schema": {
              "type": "string",
              "enum": [
                "US"
              ],
              "default": "US"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quotes, cheapest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "country",
                    "weightG",
                    "currency",
                    "quotes"
                  ],
                  "properties": {
                    "country": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "weightG": {
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string",
                      "const": "USD"
                    },
                    "snapshotGeneratedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "methodology": {
                      "type": "string",
                      "format": "uri"
                    },
                    "quotes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "provider",
                          "providerId",
                          "line",
                          "priceUsd",
                          "accountRequired"
                        ],
                        "properties": {
                          "provider": {
                            "type": "string",
                            "description": "Shipping agent name."
                          },
                          "providerId": {
                            "type": "string",
                            "description": "Stable provider id."
                          },
                          "providerUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "line": {
                            "type": "string",
                            "description": "The provider's shipping line."
                          },
                          "priceUsd": {
                            "type": "number",
                            "description": "Total shipping price the provider's own calculator displayed, in USD."
                          },
                          "deliveryEstimate": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Delivery time as the provider stated it."
                          },
                          "capturedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time",
                            "description": "When the price was read off the provider's calculator."
                          },
                          "proofVideoUrl": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri",
                            "description": "Timestamped screen recording the price was read from."
                          },
                          "accountRequired": {
                            "type": "boolean",
                            "description": "True when the provider only quotes to signed-in accounts."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unpublished country or a weight that is not a checkpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "hint"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "description": "Stable machine-readable error code."
                        },
                        "message": {
                          "type": "string",
                          "description": "What went wrong."
                        },
                        "hint": {
                          "type": "string",
                          "description": "How to fix the request."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/providers": {
      "get": {
        "operationId": "listShippingProviders",
        "summary": "List the compared shipping agents",
        "description": "The shipping agents on the board, their shipping lines, and the fixed comparison inputs (destination, item profile, parcel dimensions, checkpoint weights).",
        "responses": {
          "200": {
            "description": "Providers and comparison inputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "comparison",
                    "providers"
                  ],
                  "properties": {
                    "comparison": {
                      "type": "object"
                    },
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "lines"
                        ],
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "accountRequired": {
                            "type": "boolean"
                          },
                          "lines": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "How to fix the request."
              }
            }
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "provider",
          "providerId",
          "line",
          "priceUsd",
          "accountRequired"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "description": "Shipping agent name."
          },
          "providerId": {
            "type": "string",
            "description": "Stable provider id."
          },
          "providerUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "line": {
            "type": "string",
            "description": "The provider's shipping line."
          },
          "priceUsd": {
            "type": "number",
            "description": "Total shipping price the provider's own calculator displayed, in USD."
          },
          "deliveryEstimate": {
            "type": [
              "string",
              "null"
            ],
            "description": "Delivery time as the provider stated it."
          },
          "capturedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the price was read off the provider's calculator."
          },
          "proofVideoUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Timestamped screen recording the price was read from."
          },
          "accountRequired": {
            "type": "boolean",
            "description": "True when the provider only quotes to signed-in accounts."
          }
        }
      }
    }
  }
}