Instagram Follower Checker

Local web app that analyzes Instagram follower/following relationships from the official data export.

Stack: Python 3.8+ / Flask · Vanilla JS SPA (no build step) · No database · No auth · All processing in-memory

---

Docs

• HOW_TO_USE.md — dev setup, dependencies, configuration
• INSTAGRAM_EXPORT.md — Instagram JSON schema reference

---

Architecture

Browser (SPA)  ──POST /analyze──>  Flask backend
                                        │
                                        ├── parse_zip()  or  parse_json_files()
                                        │       ├── extract_following_with_ts()
                                        │       ├── extract_followers_with_ts()
                                        │       ├── extract_unfollowed()
                                        │       └── extract_pending()
                                        └── build_response()  ──>  JSON

Stateless request/response — no session, no disk writes, no external calls.

---

Project structure

insta-project/
├── app.py                       # Flask server + all parsing logic
├── requirements.txt             # flask, flask-cors
├── static/
│   └── index.html               # SPA: upload → dashboard → section detail pages
├── sample-export/               # Mock Instagram export for manual testing
│   └── connections/
│       └── followers_and_following/
│           ├── following.json
│           ├── followers_1.json
│           ├── recently_unfollowed_profiles.json
│           └── pending_follow_requests.json
├── README.md
├── HOW_TO_USE.md
└── INSTAGRAM_EXPORT.md

---

Quick start

python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
python3 app.py
# → http://localhost:5000

See HOW_TO_USE.md for full setup details.

---

API

POST /analyze

Accepts multipart/form-data. Two modes:

ZIP mode

Field	Type	Notes
zip	file	Full Instagram export ZIP

JSON mode

Field	Type	Required	File
following	file	yes	following.json
followers	file	yes	followers_1.json
unfollowed	file	no	recently_unfollowed_profiles.json
pending	file	no	pending_follow_requests.json

Response

{
  "following_count": 300,
  "followers_count": 280,
  "mutual_count": 250,
  "not_following_back":       [{ "username": "alice", "following_since": 1672531200 }],
  "not_following_back_count": 50,
  "not_followed_back":        [{ "username": "bob",   "followed_since":  1690000000 }],
  "not_followed_back_count":  30,
  "recently_unfollowed":      [{ "username": "carol", "name": "Carol S.", "timestamp": 1716000000 }],
  "recently_unfollowed_count": 5,
  "pending_follow_requests":  [{ "username": "dave",  "name": "Dave M.", "timestamp": 1714000000 }],
  "pending_follow_requests_count": 3
}

All timestamps are Unix seconds. Errors return { "error": "..." } with a 4xx/5xx status.

---

Key implementation notes

• following.json stores username in the top-level "title" field. followers_N.json stores it in string_list_data[0].value. These are different — see INSTAGRAM_EXPORT.md.
• Multiple followers_N.json files (for large accounts) are detected via regex and merged.
• Instagram double-encodes non-ASCII in name fields. Fixed by fix_encoding(): s.encode('latin-1').decode('utf-8').
• recently_unfollowed_profiles.json and pending_follow_requests.json share an identical schema — both are parsed by _extract_named_list().

---

Privacy

No network calls beyond localhost. Nothing is written to disk. The uploaded files are read into memory, parsed, and discarded within the request.