myhamilton311

A Python library for the MyHamilton 311 app API — the City of Hamilton, Ohio's citizen service request platform, backed by SeeClickFix.

Reverse-engineered from mitmproxy captures of the MyHamilton 311 iOS app (build 3884).

Installation

pip install requests          # only runtime dependency
# or, from this repo:
pip install -e .

Quick Start

Unauthenticated — browse public issues

from myhamilton311 import MyHamilton311Client

client = MyHamilton311Client()

# Bounding box roughly covering Hamilton, OH
issues = client.get_issues(
    min_lat=39.368, min_lng=-84.588,
    max_lat=39.432, max_lng=-84.539,
)

print(f"{issues.pagination.entries} total issues found")
for issue in issues.issues:
    print(f"[{issue.status}] #{issue.id} — {issue.summary}")
    print(f"  {issue.address}")

Authenticated — profile, my issues, city notices

from myhamilton311 import MyHamilton311Client, authenticate

# Opens a browser tab for CivicPlus / SeeClickFix login
token = authenticate()

client = MyHamilton311Client(access_token=token)

profile = client.get_profile()
print(f"Logged in as {profile.name} ({profile.email})")

for notice in client.get_notices_iter():
    print(f"[{notice.published_at}] {notice.sender}: {notice.subject}")

If you already have a token (e.g. from a mitmproxy capture), supply it directly:

client = MyHamilton311Client(access_token="FvzaRk7i-HacbIx...")

API Reference

MyHamilton311Client

authenticate(mode, port, timeout)

Opens the system browser to complete the CivicPlus / SeeClickFix OAuth 2.0 implicit flow. Returns the Bearer access token string.

Protocol Notes

Reverse-engineered from 8 mitmproxy capture files covering:

1. Initial app load — GET /scf/v1/mobile_app_config, GET /api/v3/bulletin_boards
2. Browse issues — GET /api/v2/issues?…bbox…
3. Registration — OAuth implicit flow → CivicPlus identity provider (IDS4) → OTP email verification → accept terms
4. Sign out — GET /oauth/logout → CivicPlus backchannel logout
5. Sign in — Email-based lookup → CivicPlus password page → OAuth token
6. Notices — GET /api/v2/profile/notices
7. View issue (authenticated) — GET /api/v2/issues/{id}?details=true
8. View issue (unauthenticated) — same endpoint, no Bearer token

Authentication flow

App → GET /oauth/authorize?client_id=zBmhzPX…&response_type=token&scf_login=choose
    ← 302 → /oauth/login

User enters email → POST /oauth/login
    ← 302 → /federated_logins/ids4/1118?email=…  (CivicPlus IDP)

CivicPlus handles password entry → POST /federated_logins/ids4/callback (code + id_token JWT)
    ← 302 → /oauth/authorize  (SCF exchanges code for token)
    ← 302 → com.citysourced.hamiltonoh://oauth/callback#access_token=<BEARER_TOKEN>

Key constants

Legal

This library is for research and personal use only. The SeeClickFix API is proprietary. Be respectful of rate limits and do not use this library for scraping at scale.