{
  "openapi": "3.1.0",
  "info": {
    "title": "臺灣匹克球時尚 PICKLEBALL.FASHION 開放資料 API",
    "version": "2026-10-27",
    "summary": "臺灣匹克球場地、球拍、球衣配件、規則教學、新聞與賽事活動之唯讀靜態開放資料介面。",
    "description": "每日隨網站更新一次，無須 API 金鑰，支援跨來源讀取（CORS）。個人、非商業、學術研究、新聞報導與 AI 助理可自由引用，請標註來源為 pickleball.fashion 並附上專頁網址。",
    "contact": {
      "name": "臺灣匹克球時尚 PICKLEBALL.FASHION",
      "url": "https://pickleball.fashion/feedback/"
    },
    "license": {
      "name": "依本站著作權政策開放引用（需標註來源）",
      "url": "https://pickleball.fashion/copyright/"
    }
  },
  "servers": [
    {
      "url": "https://pickleball.fashion",
      "description": "正式站（每日更新）"
    }
  ],
  "paths": {
    "/api/courts-full.json": {
      "get": {
        "operationId": "listCourtsFull",
        "summary": "取得全臺匹克球場完整資料",
        "description": "回傳全臺 201 座營業中球場的地址、座標、室內外、面數、設施、收費、營業時段、訂位連結與原始出處。",
        "responses": {
          "200": {
            "description": "球場完整清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CourtFull"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/courts.json": {
      "get": {
        "operationId": "listCourtsGeo",
        "summary": "取得球場輕量定位索引",
        "description": "僅含座標、室內外與收費摘要，供地圖與距離排序使用。",
        "responses": {
          "200": {
            "description": "球場輕量清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/courts.csv": {
      "get": {
        "operationId": "downloadCourtsCsv",
        "summary": "下載全臺球場 CSV 試算表（含 UTF-8 BOM）",
        "responses": {
          "200": {
            "description": "CSV 表格",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/paddles.json": {
      "get": {
        "operationId": "listPaddles",
        "summary": "取得臺灣市售匹克球拍規格與通路清單",
        "description": "回傳 166 支球拍之品牌、型號、厚度、核心、拍面材質、重量、握把尺寸、售價區間與臺灣購買通路。",
        "responses": {
          "200": {
            "description": "球拍清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Paddle"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/apparel.json": {
      "get": {
        "operationId": "listApparel",
        "summary": "取得匹克球服飾、球鞋與配件清單",
        "description": "回傳 154 件球衣、球褲裙、專用球鞋、球與配件之材質、機能、售價區間與通路。",
        "responses": {
          "200": {
            "description": "服飾與配件清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/events.json": {
      "get": {
        "operationId": "listEvents",
        "summary": "取得臺灣匹克球近期與歷屆賽事活動",
        "description": "回傳 85 場賽事、講習與體驗活動之日期、地點、主辦單位、報名狀態與來源公告。",
        "responses": {
          "200": {
            "description": "活動清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EventItem"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/news.json": {
      "get": {
        "operationId": "listNews",
        "summary": "取得臺灣匹克球新聞改寫摘要",
        "description": "回傳 107 則新聞之標題、自有改寫摘要、分類、發布時間與原始報導出處。",
        "responses": {
          "200": {
            "description": "新聞清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NewsItem"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/learn.json": {
      "get": {
        "operationId": "listLessons",
        "summary": "取得匹克球規則與新手教學課程全文",
        "description": "回傳 23 堂課之單元、課次、摘要、Markdown 全文、自製圖解與參考來源。",
        "responses": {
          "200": {
            "description": "教學課程清單",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/events.ics": {
      "get": {
        "operationId": "downloadEventsCalendar",
        "summary": "訂閱或下載近期活動 iCalendar 行事曆（RFC 5545）",
        "responses": {
          "200": {
            "description": "iCalendar 行事曆",
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/feed.json": {
      "get": {
        "operationId": "getNewsJsonFeed",
        "summary": "取得最新 40 則新聞 JSON Feed 1.1 訂閱源",
        "responses": {
          "200": {
            "description": "JSON Feed 1.1",
            "content": {
              "application/feed+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/feed.xml": {
      "get": {
        "operationId": "getNewsRssFeed",
        "summary": "取得最新 40 則新聞 RSS 2.0 訂閱源",
        "responses": {
          "200": {
            "description": "RSS 2.0 XML",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CourtFull": {
        "type": "object",
        "required": [
          "id",
          "name",
          "city",
          "indoor",
          "facilities",
          "status",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "district": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "indoor": {
            "type": "boolean"
          },
          "courts": {
            "type": [
              "integer",
              "null"
            ]
          },
          "surface": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "booking_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "hours_weekday": {
            "type": [
              "string",
              "null"
            ]
          },
          "hours_weekend": {
            "type": [
              "string",
              "null"
            ]
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ]
          },
          "facilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string"
          },
          "opened": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Paddle": {
        "type": "object",
        "required": [
          "id",
          "brand",
          "model",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "thickness_mm": {
            "type": [
              "number",
              "null"
            ]
          },
          "core": {
            "type": [
              "string",
              "null"
            ]
          },
          "face": {
            "type": [
              "string",
              "null"
            ]
          },
          "weight_min_g": {
            "type": [
              "number",
              "null"
            ]
          },
          "weight_max_g": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_min_twd": {
            "type": [
              "integer",
              "null"
            ]
          },
          "price_max_twd": {
            "type": [
              "integer",
              "null"
            ]
          },
          "official_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "buy": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "EventItem": {
        "type": "object",
        "required": [
          "id",
          "title",
          "start",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": [
              "string",
              "null"
            ]
          },
          "start": {
            "type": "string",
            "format": "date"
          },
          "end": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "venue": {
            "type": [
              "string",
              "null"
            ]
          },
          "organizer": {
            "type": [
              "string",
              "null"
            ]
          },
          "fee_twd": {
            "type": [
              "integer",
              "null"
            ]
          },
          "registration_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "registration_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "NewsItem": {
        "type": "object",
        "required": [
          "id",
          "title",
          "summary",
          "published",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "published": {
            "type": "string"
          },
          "source_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}