{
 "openapi": "3.1.0",
 "info": {
  "title": "tokeilab API",
  "version": "v1",
  "license": {
   "name": "CC BY 4.0（データ）",
   "identifier": "CC-BY-4.0"
  },
  "description": "東京23区の建物ごとの日照時間（PLATEAU から計算）を返す API。使い方: https://tokeilab.org/sunlight/api/ 。項目の意味: https://tokeilab.org/schema/sunlight/ 。静的ページもすべて /path/index.json で JSON を返します。API キー不要、IP ごとに毎分20回まで。課金は未有効化（導入時は x402 など1回ごとの支払い）。"
 },
 "servers": [
  {
   "url": "https://api.tokeilab.org"
  }
 ],
 "externalDocs": {
  "description": "API の使い方",
  "url": "https://tokeilab.org/sunlight/api/"
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "API キー（現在は発行していない。課金は x402 など1回ごとの支払いで導入予定）"
   }
  },
  "schemas": {
   "Envelope": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {},
     "meta": {
      "type": "object",
      "required": [
       "generated_at",
       "data_through",
       "source",
       "license",
       "schema_url",
       "api_version",
       "cost_units"
      ]
     }
    }
   },
   "Problem": {
    "type": "object",
    "description": "RFC 9457。type は https://tokeilab.org/problems/<種類>/ 。402 には payment_methods[] と pricing_url が付く",
    "properties": {
     "type": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "status": {
      "type": "integer"
     },
     "detail": {
      "type": "string"
     },
     "instance": {
      "type": "string"
     },
     "payment_methods": {
      "type": "array"
     },
     "pricing_url": {
      "type": "string"
     }
    }
   }
  }
 },
 "security": [
  {}
 ],
 "paths": {
  "/api/v1/sunlight/building/{building_id}": {
   "get": {
    "summary": "建物1棟の要約（12/15 最良面・最上階、12/15 南面・1階、年間平均）と用途・高さ・階数",
    "parameters": [
     {
      "name": "building_id",
      "in": "path",
      "required": true,
      "description": "PLATEAU の建物 ID（uro:buildingID）。形式: 5桁の市区町村コード-bldg-数字",
      "example": "13112-bldg-202748",
      "schema": {
       "type": "string",
       "pattern": "^\\d{5}-bldg-\\d+$"
      }
     }
    ],
    "x-cost-units": 1,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    },
    "x-example": "https://api.tokeilab.org/api/v1/sunlight/building/13112-bldg-202748"
   }
  },
  "/api/v1/sunlight/building/{building_id}/full": {
   "get": {
    "summary": "建物1棟の全結果: 面×階（1階・中間階・最上階）×12か月の直射時間と日が当たる時間帯、影をつくる建物上位5件",
    "parameters": [
     {
      "name": "building_id",
      "in": "path",
      "required": true,
      "description": "PLATEAU の建物 ID（uro:buildingID）。形式: 5桁の市区町村コード-bldg-数字",
      "example": "13112-bldg-202748",
      "schema": {
       "type": "string",
       "pattern": "^\\d{5}-bldg-\\d+$"
      }
     }
    ],
    "x-cost-units": 3,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    },
    "x-example": "https://api.tokeilab.org/api/v1/sunlight/building/13112-bldg-202748/full"
   }
  },
  "/api/v1/sunlight/near": {
   "get": {
    "summary": "1地点の周り: 半径 r m 以内（最大300 m）の建物を近い順に最大50件、要約つき",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": true,
      "description": "緯度（世界測地系、度）",
      "example": 35.6427,
      "schema": {
       "type": "number",
       "minimum": 35.4,
       "maximum": 35.9
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": true,
      "description": "経度（世界測地系、度）",
      "example": 139.6687,
      "schema": {
       "type": "number",
       "minimum": 139.5,
       "maximum": 140.0
      }
     },
     {
      "name": "r",
      "in": "query",
      "required": false,
      "description": "半径（m）。省略時 100",
      "example": 50,
      "schema": {
       "type": "number",
       "minimum": 1,
       "maximum": 300,
       "default": 100
      }
     }
    ],
    "x-cost-units": 2,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    },
    "x-example": "https://api.tokeilab.org/api/v1/sunlight/near?lat=35.6427&lon=139.6687&r=50"
   }
  },
  "/api/v1/sunlight/town/{town_code}/buildings": {
   "get": {
    "summary": "町丁目の建物一覧（100件ずつ）、要約つき",
    "parameters": [
     {
      "name": "town_code",
      "in": "path",
      "required": true,
      "description": "町丁目コード（2020年国勢調査の小地域、9桁または11桁）。一覧: https://tokeilab.org/sunlight/towns.json",
      "example": "13112004002",
      "schema": {
       "type": "string",
       "pattern": "^\\d{9}(\\d{2})?$"
      }
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "description": "ページ番号（1から、100件ずつ）",
      "example": 1,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "default": 1
      }
     }
    ],
    "x-cost-units": 2,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    },
    "x-example": "https://api.tokeilab.org/api/v1/sunlight/town/13112004002/buildings?page=1"
   }
  },
  "/api/v1/sunlight/point": {
   "get": {
    "summary": "任意の地点・高さのその場計算（仕様のみ。現在は 501 を返す）",
    "parameters": [
     {
      "name": "lat",
      "in": "query",
      "required": true,
      "description": "緯度（世界測地系、度）",
      "example": 35.6427,
      "schema": {
       "type": "number",
       "minimum": 35.4,
       "maximum": 35.9
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": true,
      "description": "経度（世界測地系、度）",
      "example": 139.6687,
      "schema": {
       "type": "number",
       "minimum": 139.5,
       "maximum": 140.0
      }
     },
     {
      "name": "height_m",
      "in": "query",
      "required": true,
      "description": "地面からの高さ（m）",
      "example": 10,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 400
      }
     }
    ],
    "x-cost-units": 5,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sunlight/bulk/{ward_code}": {
   "get": {
    "summary": "区全体の結果 Parquet への署名付き URL（1時間有効）",
    "parameters": [
     {
      "name": "ward_code",
      "in": "path",
      "required": true,
      "description": "区コード 13101（千代田区）〜 13123（江戸川区）",
      "example": "13112",
      "schema": {
       "type": "string",
       "pattern": "^131(0[1-9]|1\\d|2[0-3])$"
      }
     }
    ],
    "x-cost-units": 20,
    "x-pricing-url": "https://tokeilab.org/pricing/",
    "responses": {
     "200": {
      "description": "OK（data と meta）",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "400": {
      "description": "パラメータの誤り",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "401": {
      "description": "認証情報が正しくない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "402": {
      "description": "支払いが必要（課金有効時のみ）",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "404": {
      "description": "見つからない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "429": {
      "description": "回数の上限を超えた",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "501": {
      "description": "未実装",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     },
     "503": {
      "description": "一時的に使えない",
      "content": {
       "application/problem+json": {
        "schema": {
         "$ref": "#/components/schemas/Problem"
        }
       }
      }
     }
    },
    "x-example": "https://api.tokeilab.org/api/v1/sunlight/bulk/13112"
   }
  }
 }
}