{
  "openapi": "3.1.0",
  "info": {
    "title": "China Data Portal dataset and tariff endpoints",
    "version": "2",
    "description": "Covers four operations: the dataset catalog, dataset detail and download, public tariff lookup, and prepaid tariff lookup."
  },
  "servers": [
    {
      "url": "https://chinadata.live/api/v2"
    }
  ],
  "security": [],
  "paths": {
    "/datasets": {
      "get": {
        "operationId": "listDatasets",
        "summary": "List datasets in the statistical catalog",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request limit reached"
          },
          "500": {
            "description": "Catalog query failed."
          },
          "503": {
            "description": "Catalog is not ready."
          }
        }
      }
    },
    "/data/{id}": {
      "get": {
        "operationId": "getDataset",
        "summary": "Get one dataset and its observations",
        "parameters": [
          {
            "name": "id",
            "description": "Dataset ID or slug",
            "required": true,
            "schema": {
              "type": "string"
            },
            "in": "path"
          },
          {
            "name": "format",
            "description": "Download format",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            },
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset"
          },
          "410": {
            "description": "Dataset retired."
          },
          "429": {
            "description": "Request limit reached"
          },
          "500": {
            "description": "Dataset query failed."
          },
          "503": {
            "description": "Published dataset temporarily unavailable."
          }
        }
      }
    },
    "/tariffs": {
      "get": {
        "operationId": "getTariffs",
        "summary": "Look up tariff rates within the free quota",
        "parameters": [
          {
            "$ref": "#/components/parameters/hs_code"
          },
          {
            "$ref": "#/components/parameters/origin_country"
          },
          {
            "$ref": "#/components/parameters/direction"
          },
          {
            "$ref": "#/components/parameters/quota"
          },
          {
            "$ref": "#/components/parameters/date"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid HS code, country, direction, quota, or date."
          },
          "404": {
            "description": "hs_code_not_found: no matching tariff lines."
          },
          "429": {
            "description": "Free daily IP lookup quota reached."
          },
          "500": {
            "description": "tariff_lookup_failed: lookup failed."
          },
          "503": {
            "description": "database_unavailable: tariff storage is unavailable."
          }
        }
      }
    },
    "/payg/tariffs": {
      "get": {
        "operationId": "getMeteredTariffs",
        "summary": "Look up tariff rates using one prepaid credit",
        "parameters": [
          {
            "$ref": "#/components/parameters/hs_code"
          },
          {
            "$ref": "#/components/parameters/origin_country"
          },
          {
            "$ref": "#/components/parameters/direction"
          },
          {
            "$ref": "#/components/parameters/quota"
          },
          {
            "$ref": "#/components/parameters/date"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "authentication_required or invalid_api_key: supply a valid bearer key."
          },
          "403": {
            "description": "key_revoked or key_expired: the supplied key is inactive."
          },
          "404": {
            "description": "coverage_unavailable: no matching tariff lines."
          },
          "422": {
            "description": "Invalid HS code, country, direction, quota, or date."
          },
          "429": {
            "description": "request_quota_exceeded: prepaid lookup credits are exhausted. Additional credit is required before another lookup."
          },
          "503": {
            "description": "data_temporarily_unavailable: authentication storage or tariff data unavailable."
          }
        },
        "security": [
          {
            "tariffKey": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tariffKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "cdp_ API key"
      }
    },
    "parameters": {
      "hs_code": {
        "name": "hs_code",
        "description": "Six- or eight-digit HS code",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^(?:[0-9]{6}|[0-9]{8})$"
        },
        "in": "query"
      },
      "origin_country": {
        "name": "origin_country",
        "description": "Two-letter country of origin",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z]{2}$"
        },
        "in": "query"
      },
      "direction": {
        "name": "direction",
        "description": "Trade direction",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "import",
            "export"
          ],
          "default": "import"
        },
        "in": "query"
      },
      "quota": {
        "name": "quota",
        "description": "Quota treatment",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "auto",
            "in"
          ],
          "default": "auto"
        },
        "in": "query"
      },
      "date": {
        "name": "date",
        "description": "Date of tariff lookup",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date"
        },
        "in": "query"
      }
    }
  }
}