Endpoints docs updated

COS301-SE-2024 · Oct 1, 2024 · e8a09b8 · e8a09b8
1 parent e7499db
commit e8a09b8
Showing 1 changed file with 241 additions and 56 deletions.
diff --git a/documentation/occupi-docs/pages/api-documentation/ai-usage.mdx b/documentation/occupi-docs/pages/api-documentation/ai-usage.mdx
@@ -1,18 +1,19 @@
-# AI endpoint Usage
+# AI Endpoint Usage
 
-This page provides a detailed explanation of how to use the Occupi AI models.
-The Occupi AI models endpoint is a RESTful API that allows you to interact with the Occupi models programmatically.
-The Occupi AI models endpoint provides endpoints for receiving Occupancy predictions.
+This page provides a detailed explanation of how to use the Occupi AI models. The Occupi AI models endpoint is a RESTful API that allows you to interact with the Occupi models programmatically. The Occupi AI models endpoint provides predictions on office occupancy, attendance levels, and recommendations.
 
-
-- [AI endpoint Usage](#auth-usage)
+- [AI Endpoint Usage](#ai-endpoint-usage)
 - [Table of Contents](#table-of-contents)
   - [Base URL](#base-url)
   - [AI](#ai)
     - [Predict](#predict)
     - [Predict Week](#predict-week)
     - [Predict Date](#predict-date)
     - [Predict Week from Date](#predict-week-from-date)
+    - [Predict Hourly](#predict-hourly)
+    - [Predict Day](#predict-day)
+    - [Recommend](#recommend)
+    - [Recommend Office Times](#recommend-office-times)
 
 ## AI
 
@@ -33,21 +34,15 @@ The base URL for the AI model endpoint is:
 - **Success Response**
 
   - **Code:** 200
-  - **Content:** `{  "response": "Prediction API is up and running" }`
+  - **Content:** `{ "response": "Prediction API is up and running" }`
 
 - **Error Response**
   - **Code:** 500
   - **Content:** `{ "error": "models unavailable" }`
 
-**_Example json to send:_**
-
-```json copy
-{}
-```
-
 ### Predict
 
-The predict endpoint is used to make a prediction on the occupancy for the office space for the current date.
+The `predict` endpoint is used to make a prediction on the occupancy for the office space for the current date.
 
 - **URL**
 
@@ -60,100 +55,290 @@ The predict endpoint is used to make a prediction on the occupancy for the offic
 - **Success Response**
 
   - **Code:** 200
-  - **Content:** `{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #}`
+  - **Content:** 
+    ```json
+    {
+      "Day_of_Week": 1,
+      "Month": 8,
+      "Day_of_month": 10,
+      "Is_Weekend": false,
+      "Special_Event": 0,
+      "Predicted_Class": 2,
+      "Predicted_Attendance_Level": "50-100"
+    }
+    ```
 
 - **Error Response**
   - **Code:** 500
-  - **Content:** `{ "message": "An error occured" }`
-
-**_Example json to send:_**
-
-```json copy
-{}
-```
+  - **Content:** `{ "error": "An error occurred" }`
 
 ### Predict Week
 
-The predict week endpoint is used to make a prediction on the occupancy for the office space for the current week.
+The `predict_week` endpoint is used to make predictions on the occupancy for the office space for the current week (7 days starting from today).
 
 - **URL**
 
   `/predict_week`
 
 - **Method**
-    
+
   `GET`
 
 - **Success Response**
 
   - **Code:** 200
-  - **Content:** `{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #},{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #},...`
+  - **Content:** 
+    ```json
+    [
+      {
+        "Date": "2024-08-10",
+        "Day_of_Week": 1,
+        "Month": 8,
+        "Day_of_month": 10,
+        "Is_Weekend": false,
+        "Special_Event": 0,
+        "Predicted_Class": 2,
+        "Predicted_Attendance_Level": "50-100"
+      },
+      ...
+    ]
+    ```
 
 - **Error Response**
   - **Code:** 500
-  - **Content:** `{ "message": "An error occured" }`
-
-**_Example json to send:_**
-
-```json copy
-{}
-```
+  - **Content:** `{ "error": "An error occurred" }`
 
 ### Predict Date
 
-The predict date endpoint is used to make a prediction on the occupancy for the office space for a specific date.
+The `predict_date` endpoint is used to make predictions on the occupancy for a specific date.
 
 - **URL**
 
   `/predict_date?date=yyyy-mm-dd`
 
 - **Method**
-    
+
   `GET`
 
+- **Parameters**
+  - `date`: A specific date in the format `yyyy-mm-dd`.
+
 - **Success Response**
 
-    - **Code:** 200
-    - **Content:** `{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #}`
+  - **Code:** 200
+  - **Content:** 
+    ```json
+    {
+      "Date": "2024-08-10",
+      "Day_of_Week": 1,
+      "Month": 8,
+      "Day_of_month": 10,
+      "Is_Weekend": false,
+      "Special_Event": 0,
+      "Predicted_Class": 2,
+      "Predicted_Attendance_Level": "50-100"
+    }
+    ```
 
 - **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`
 
-    - **Code:** 500
-    - **Content:** `{ "message": "An error occured" }`
+### Predict Week from Date
 
-**_Example json to send:_**
+The `predict_week_from_date` endpoint is used to make predictions on the occupancy for the office space for the week starting from a specific date.
 
-```json copy
-{}
-```
+- **URL**
 
-### Predict Week from Date
+  `/predict_week_from_date?date=yyyy-mm-dd`
+
+- **Method**
+
+  `GET`
 
-The predict week from date endpoint is used to make a prediction on the occupancy for the office space for the week starting from a specific date.
+- **Parameters**
+  - `date`: A specific date in the format `yyyy-mm-dd`.
+
+- **Success Response**
+
+  - **Code:** 200
+  - **Content:** 
+    ```json
+    [
+      {
+        "Date": "2024-08-10",
+        "Day_of_Week": 1,
+        "Month": 8,
+        "Day_of_month": 10,
+        "Is_Weekend": false,
+        "Special_Event": 0,
+        "Predicted_Class": 2,
+        "Predicted_Attendance_Level": "50-100"
+      },
+      ...
+    ]
+    ```
+
+- **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`
+
+### Predict Hourly
+
+The `predict_hourly` endpoint is used to make predictions on the hourly occupancy for a specific date and hour.
 
 - **URL**
 
-  `/predict_week_from_date?date=yyyy-mm-dd`
+  `/predict_hourly?date=yyyy-mm-dd&hour=HH`
+
+- **Method**
+
+  `GET`
+
+- **Parameters**
+  - `date`: A specific date in the format `yyyy-mm-dd`.
+  - `hour`: The hour of the day (0-23).
+
+- **Success Response**
+
+  - **Code:** 200
+  - **Content:**
+    ```json
+    {
+      "Date": "2024-08-10",
+      "Hour": 10,
+      "Day_of_Week": 1,
+      "Month": 8,
+      "Day_of_month": 10,
+      "Is_Weekend": false,
+      "Special_Event": 0,
+      "Predicted_Class": 2,
+      "Predicted_Attendance_Level": "50-100"
+    }
+    ```
+
+- **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`
+
+### Predict Day
+
+The `predict_day` endpoint is used to make predictions for a specific date within a range of hours.
+
+- **URL**
+
+  `/predict_day?date=yyyy-mm-dd&start_hour=HH&end_hour=HH`
+
+- **Method**
+
+  `GET`
+
+- **Parameters**
+  - `date`: The date for the prediction (`yyyy-mm-dd`), defaulting to today's date.
+  - `start_hour`: The starting hour of the day (0-23).
+  - `end_hour`: The ending hour of the day (0-23).
+
+- **Success Response**
+
+  - **Code:** 200
+  - **Content:**
+    ```json
+    {
+      "Date": "2024-08-10",
+      "Day_of_Week": 1,
+      "Month": 8,
+      "Day_of_month": 10,
+      "Is_Weekend": false,
+      "Special_Event": 0,
+      "Hourly_Predictions": [
+        {
+          "Hour": 6,
+          "Predicted_Class": 2,
+          "Predicted_Attendance_Level": "50-100"
+        },
+        ...
+      ]
+    }
+    ```
+
+- **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`
+
+### Recommend
+
+The `recommend` endpoint is used to recommend the best day to visit the office based on predicted attendance levels.
+
+- **URL**
+
+  `/recommend`
 
 - **Method**
-     
-      `GET`
+
+  `GET`
 
 - **Success Response**
 
-    - **Code:** 200
-    - **Content:** `{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #},{"Day_of_Week": #,"Day_of_month": #,"Is_Weekend": false,"Month": #,"Predicted_Attendance_Level": "###-###","Predicted_Class": #,"Special_Event": #},...`
+  - **Code:** 200
+  - **Content:**
+    ```json
+    {
+      "Recommendation": "Best day(s) to go to the office based on predicted attendance levels for the next seven days, excluding weekends.",
+      "Recommended_Days": [
+        {
+          "Date": "2024-08-11",
+          "Day_of_Week": 1,
+          "Month": 8,
+          "Day_of_month": 11,
+          "Is_Weekend": false,
+          "Special_Event": 0,
+          "Predicted_Class": 2,
+          "Predicted_Attendance_Level": "50-100"
+        }
+      ]
+    }
+    ```
 
 - **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`
+
+### Recommend Office Times
+
+The `recommend_office_times` endpoint is used to recommend the best times to go to the office based on hourly predictions.
 
-    - **Code:** 500
-    - **Content:** `{ "message": "An error occured" }`
+- **URL**
+
+  `/recommend_office_times?date=yyyy-mm-dd&start_hour=HH&end_hour=HH`
+
+- **Method**
+
+  `GET`
 
-**_Example json to send:_**
+- **Parameters**
+  - `date`: The date for the prediction (`yyyy-mm-dd`), defaulting to today's date.
+  - `start_hour`: The starting hour of the day (0-23).
+  - `end_hour`: The ending hour of the day (0-23).
 
-```json copy
-{}
-```
+- **Success Response**
 
+  - **Code:** 200
+  - **Content:**
+    ```json
+    {
+      "Date": "2024-08-10",
+      "Day_of_Week": 1,
+      "Best_Times": [
+        {
+          "Hour": 6,
+          "Predicted_Class": 1,
+          "Predicted_Attendance_Level": "25-50",
+          "Recommendation": "Best time to go"
+        }
+      ]
+    }
+    ```
 
-
+- **Error Response**
+  - **Code:** 500
+  - **Content:** `{ "error": "An error occurred" }`