From 590f9b8d927ddf0707559377386e208e52031288 Mon Sep 17 00:00:00 2001
From: Arnav Dhablania <63648338+ArnavDhablania@users.noreply.github.com>
Date: Mon, 17 Nov 2025 11:57:23 -0800
Subject: [PATCH] added structure and README

---
 .env.example         |  1 +
 README.md            | 95 +++++++++++++++++++++++++++++++++++++++++++-
 data/clean/clean.txt |  1 +
 data/raw/raw.txt     |  1 +
 docs/docs.txt        |  1 +
 requirements.txt     |  0
 scripts/scripts.txt  |  1 +
 7 files changed, 98 insertions(+), 2 deletions(-)
 create mode 100644 .env.example
 create mode 100644 data/clean/clean.txt
 create mode 100644 data/raw/raw.txt
 create mode 100644 docs/docs.txt
 create mode 100644 requirements.txt
 create mode 100644 scripts/scripts.txt

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..9df8f71
--- /dev/null
+++ b/.env.example
@@ -0,0 +1 @@
+Translink_Api_Key=Change_Me
diff --git a/README.md b/README.md
index 2de85e8..8992e3c 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,93 @@
-# Translink
-The repository is responsible for Translink related tasks for UBC Live
+## Description:
+This repository is responsible for TransLink related tasks for UBC Live 
+
+## Data format: 
+- Data is retrieved from TransLink's GTFS Static and GTFS-Realtime APIs. 
+- Static data (routes, stops, stop times, trips) is provided in CSV format.
+- Realtime data (vehicle positions, trip updates. service alerts) is provided in Protocol Buffer (.pb) format which is coverted into JSON. 
+
+## Data format (CSV):
+### Header definitions
+**route_number**
+Public bus route number derived from GTFS static 
+```csv
+"99
+```
+**vehicle_id**
+Unique identifier for the bus reporting real-time data.
+```csv
+"8137"
+```
+**latitude, longitude**
+Current GPS coordinates of the bus from the realtime feed.
+```csv
+49.2637,-123.16814
+```
+**timestamp**
+The UNIX timestamp when the update was recorded.
+Converted to ISO-8601 for consistency.
+```csv
+"2025-11-15T23:45:02Z"
+```
+**stop_id**
+ID of the upcoming stop the bus is traveling toward.
+Comes directly from stopId in the vehicle position entity.
+```csv
+"59"
+```
+**current_stop_sequence**
+Index of the stop along the trip pattern according to GTFS-Realtime.
+```csv
+15
+```
+**arrival_estimate** (derived)
+Estimated arrival time (in minutes) until the vehicle reaches stop_id.
+Computed by our pipeline (TransLink does not provide this directly).
+```csv
+3
+```
+**occupancy**
+Crowding level of the bus.
+Only present when TransLink includes congestionLevel.
+```pb
+"FULL"
+"MANY_SEATS"
+"EMPTY"
+```
+### Example
+
+```csv
+route_number,vehicle_id,latitude,longitude,timestamp,stop_id,current_stop_sequence,arrival_estimate,occupancy
+"99","8137",49.2637,-123.16814,"2025-11-15T23:45:02Z","59",15,3,"MANY_SEATS"
+```
+
+- Raw data will be in `data/raw/` and cleaned data in `data/raw/clean/`. 
+- **Note:** The format of the data or CSV file may be changed as requirements evolve
+
+## Setup Instructions 
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/UBC-Live/Translink.git
+   cd Translink
+   ```
+
+2. **Create virtual environment** 
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+   
+   To deactivate:
+   ```bash
+   deactivate
+   ```
+
+3. **Set up environment variables**
+   Create a copy .env.example contents into a new .env file, then put in API information.
+   Copy .env.example contents into a new .env file, then put in API information. **This file is local and should not be pushed, as specified in .gitignore** 
+
+4. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
\ No newline at end of file
diff --git a/data/clean/clean.txt b/data/clean/clean.txt
new file mode 100644
index 0000000..8b0de11
--- /dev/null
+++ b/data/clean/clean.txt
@@ -0,0 +1 @@
+put clean data in this folder
\ No newline at end of file
diff --git a/data/raw/raw.txt b/data/raw/raw.txt
new file mode 100644
index 0000000..bd839da
--- /dev/null
+++ b/data/raw/raw.txt
@@ -0,0 +1 @@
+put raw data in this folder
\ No newline at end of file
diff --git a/docs/docs.txt b/docs/docs.txt
new file mode 100644
index 0000000..e59695e
--- /dev/null
+++ b/docs/docs.txt
@@ -0,0 +1 @@
+put docs here
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/scripts.txt b/scripts/scripts.txt
new file mode 100644
index 0000000..4117509
--- /dev/null
+++ b/scripts/scripts.txt
@@ -0,0 +1 @@
+put scripts in this folder
\ No newline at end of file