{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Neighborhoods API",
    "description": "Free REST API for Tokyo neighborhood crime statistics. 5,078 neighborhoods, 7 years of data (2018-2024), 37 crime categories. Sourced from Tokyo Metropolitan Police Department open data.",
    "version": "1.0.0",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "Japan Neighborhoods",
      "url": "https://japanneighborhoods.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://japanneighborhoods.com/api/v1"
    }
  ],
  "paths": {
    "/wards": {
      "get": {
        "summary": "List all wards",
        "description": "Returns all 49 Tokyo wards/cities with 2024 crime summaries.",
        "operationId": "getWards",
        "responses": {
          "200": {
            "description": "List of wards with crime data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Ward" }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/wards/{slug}": {
      "get": {
        "summary": "Get ward detail",
        "description": "Returns ward detail with all neighborhoods and crime data.",
        "operationId": "getWard",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "shibuya"
          }
        ],
        "responses": {
          "200": { "description": "Ward detail with neighborhoods" },
          "404": { "description": "Ward not found" }
        }
      }
    },
    "/neighborhoods/{ward}/{neighborhood}": {
      "get": {
        "summary": "Get neighborhood detail",
        "description": "Full neighborhood detail: 7-year crime history, breakdown, safety grade, nearest stations.",
        "operationId": "getNeighborhood",
        "parameters": [
          {
            "name": "ward",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "shibuya"
          },
          {
            "name": "neighborhood",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "jingumae-1"
          }
        ],
        "responses": {
          "200": { "description": "Neighborhood detail with crime history and stations" },
          "404": { "description": "Neighborhood not found" }
        }
      }
    },
    "/rankings/safest": {
      "get": {
        "summary": "Safest neighborhoods ranking",
        "description": "Top 50 safest neighborhoods in Tokyo (2024).",
        "operationId": "getSafestRankings",
        "responses": {
          "200": { "description": "Ranked list of safest neighborhoods" }
        }
      }
    },
    "/crime/trends": {
      "get": {
        "summary": "City-wide crime trends",
        "description": "Annual crime trends for Tokyo 23 special wards (2018-2024) with category breakdowns.",
        "operationId": "getCrimeTrends",
        "responses": {
          "200": { "description": "Annual trends and 2024 breakdown" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Ward": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name_en": { "type": "string" },
          "name_ja": { "type": "string" },
          "type": { "type": "string" },
          "total_crimes_2024": { "type": "integer" },
          "neighborhood_count": { "type": "integer" },
          "avg_crime_rate_per_1000": { "type": "number" }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "count": { "type": "integer" },
          "year": { "type": "integer" },
          "source": { "type": "string" },
          "license": { "type": "string" },
          "attribution": { "type": "string" }
        }
      }
    }
  }
}
