# ποΈ PHL RENTAL LICENSE β CHANGE LOG
### *The history Philadelphia's public systems throw away.*
[](https://thumpersecure.github.io/phl-rental-license-log/)
[](https://thumpersecure.github.io/phl-rental-license-log/latest.json)
[](https://thumpersecure.github.io/phl-rental-license-log/violations_latest.json)
[](https://phl.carto.com/api/v2/sql)
[](#-how-it-works)
**`Every Active + Expired rental license, diffed daily. Every Β§9-3902 violation since 2010.`**
---
## π¬ What The City Keeps — And What It Discards
> **A rental license expires. Months pass. The landlord renews.**
> **Every trace that it ever lapsed β silently disappears.**
### π§ββοΈ Why this exists β for tenants
**When a landlord renews a lapsed rental license, the City overwrites the expiration date.** After the renewal, there is no longer any public record online that the license was ever expired β or on what dates.
That is a serious problem for tenants. A tenant in a dispute β often **months later, in court** β may need to prove the landlord's rental license was expired during their tenancy. But if they didn't screenshot it at the time, those expired dates are **gone from every City system.**
This log fixes that. It records every `Active β Expired` and `Expired β Active` transition **the day it happens, permanently β before the City erases it** β so anyone can look up, after the fact:
> **This license was expired on `[date]`, renewed on `[date]`, and lapsed for `[N]` days.**
### βοΈ Built to be used as evidence β without needing the maintainer
This project is designed so **you never have to ask the person who built it to vouch for the data.** Every daily log is anchored to the **Bitcoin blockchain** via [OpenTimestamps](#-cryptographic-timestamps--proof-the-data-existed-independent-of-github), which lets *anyone* independently prove the log's contents existed, unaltered, on a given date. A tenant can therefore cite these dates in court as **tamper-evident evidence** β no need for the maintainer to appear, explain how the data was retrieved, or attest to its authenticity. The Bitcoin proof does that on its own, forever.
Philadelphia publishes rental license data across **four public surfaces**. Every one shows only the license's **current** state:
| Surface | Expiration? | Renewal date? | Status history? |
|:--|:--:|:--:|:--:|
| πΊοΈ **Atlas** `atlas.phila.gov` | β no column | β | β |
| π **Property History** `li.phila.gov` | β no row | β | β |
| π’ **eCLIPSE** `eclipse.phila.gov` | β
| β οΈ partial | β |
| π **Carto API** `phl.carto.com` | β
| β
*(hidden field)* | β |
### π‘οΈ But violations are permanent
When L&I cites a property for operating **without a valid rental license**, that record does **not** get erased by a later renewal. It keeps its case number, its dates, its resolution β and a link to the official Notice of Violation PDF.
**That enforcement history reaches back to `2010`.**
### π― What each source can answer
| Question | Answer |
|:--|:--|
| Was this license expired on a given past date? | β **Not available** β overwritten |
| When was it last renewed? | β
**Available** β `mostrecentissuedate` |
| Was the property cited for operating unlicensed, and when? | β
**Permanent** β since 2010 |
> [!WARNING]
> **The gap that remains.** Not every lapse produces a violation. A license that expires and is renewed *before an inspector visits* leaves **no enforcement record and no status history**. Those lapses are invisible in every public system β which is exactly what the daily license log exists to catch.
---
## β‘ Two Logs, One Repo
```
phl.carto.com ββΆ daily pull ββΆ diff ββΆ append-only log ββΆ OpenTimestamps ββΆ git commit
(public) (deltas) (Bitcoin anchor) (+ .ots proof)
```
| Log | What | Coverage |
|:--|:--|:--|
| π **License log** | 99,348 Active/Expired rental licenses, diffed daily | **Forward** from `2026-08-21` |
| βοΈ **Violations archive** | 26,817 Β§9-3902 rental-license citations | **2010 β present** |
Every update is a timestamped Git commit, and **GitHub's Activity log records every push β including any force-push β with compare links, visible to anyone with read access.** That push history is outside the maintainer's control, which is what makes it worth citing. See [`REWRITE_LOG.md`](REWRITE_LOG.md) for a full account of any history changes.
---
## π Cryptographic Timestamps β proof the data existed, independent of GitHub
A git commit date is only as trustworthy as the person (or platform) who wrote it β it can be back-dated, and GitHub could in principle be compelled to rewrite history. So the daily job does one more thing: it **anchors each change log to the Bitcoin blockchain** using [OpenTimestamps](https://opentimestamps.org/).
Here's what that means in plain terms:
- Every day, the job computes a **SHA-256 hash** of each change log and submits *only that hash* to free public OpenTimestamps calendar servers. **The data itself never leaves the runner** β a hash reveals nothing about the contents, it just uniquely fingerprints them.
- The calendars batch thousands of hashes into a single Bitcoin transaction. Once that transaction is mined, the hash is **permanently embedded in a Bitcoin block**. Because rewriting a Bitcoin block would cost more than the network's entire mining economy, that block's timestamp becomes an independent, tamper-evident witness: *this exact file existed, unaltered, no later than this block.*
- The proof is saved next to the data as a small **`.ots` file** (e.g. `changes.ndjson.ots`) and committed to the repo. **These proofs are self-validating** β once a `.ots` carries its Bitcoin attestation, anyone can verify it with nothing but a Bitcoin node, *even if this repo, GitHub, and every calendar server disappear.*
> [!NOTE]
> **Why this matters here:** the whole point of this project is that Philadelphia's systems overwrite history. A back-datable git log would be a weak answer to that. A Bitcoin anchor is not β it proves the log's contents on a given day to anyone, forever, without asking you to trust GitHub or the maintainer.
### Verify it yourself
```bash
# one-time: install the client (no account, no API key)
pipx install opentimestamps-client # or: pip install opentimestamps-client
# grab a log and its proof
curl -O https://thumpersecure.github.io/phl-rental-license-log/changes.ndjson
curl -O https://thumpersecure.github.io/phl-rental-license-log/changes.ndjson.ots
ots info changes.ndjson.ots # shows the SHA-256 + which Bitcoin block(s) it's anchored in
ots verify changes.ndjson.ots # confirms the file matches the proof and the block timestamp
```
`ots info` lists the Bitcoin block heights the hash is committed to; `ots verify` recomputes the hash of your copy of `changes.ndjson` and checks it against the block. If someone hands you an altered log, the hash won't match and verification fails.
Proof files carried in the repo: **`changes.ndjson.ots`**, **`violations_changes.ndjson.ots`**, and the current month partition (**`changes/YYYY-MM.ndjson.ots`**). Each is refreshed the moment its data file changes, so the committed proof always anchors the current contents; every past state keeps its own confirmed proof in git history at that day's commit.
> [!NOTE]
> Timestamping is **best-effort and additive** β it never blocks or gates a daily data update. If a calendar server is briefly unreachable, that day's stamp is simply retried on the next run; the data log is unaffected.
---
## βΎοΈ How Long Can This Run Untouched?
Short answer: **indefinitely, with a light human touch roughly every year or two** β not "5 months," and not honestly "forever with zero hands." Here's the real accounting, because the honest version is more useful than a slogan.
**What costs nothing and never expires (the machinery is durable):**
| Component | Status |
|:--|:--|
| **GitHub Actions minutes** | Free and unmetered for public repos β one run/day is nothing |
| **GitHub Pages hosting** | No inactivity expiry; usage is far under every limit |
| **The Actions token** | Auto-issued fresh each run, self-renewing β nothing to rotate |
| **Existing Bitcoin timestamps** | Self-validating forever, independent of GitHub *and* of OpenTimestamps' own servers |
| **Data source** | `phl.carto.com` β public, no auth, no key to expire |
**The two things that eventually need a human:**
1. **GitHub's 60-day scheduled-workflow rule.** GitHub auto-disables a scheduled (cron) workflow *"when no repository activity has occurred in 60 days"* in a public repo. This job commits every day, so it **should** keep resetting that clock and run unattended β **but GitHub's docs do not explicitly state whether a commit made by the workflow's own bot counts as "activity,"** and their answer to that is undocumented. If bot commits count, this runs untouched for years. If they don't, the workflow would pause at day 60 and need one click ("Enable workflow") or any manual commit to resume. Either way the *data is never lost* β a paused job just stops adding new days until you nudge it. **This is the one thing worth glancing at once every couple of months.**
2. **Pinned action / runtime decay.** The workflow pins versioned actions (`actions/checkout`, `actions/setup-python`, `actions/cache`). GitHub retires the underlying runner Node runtimes on a schedule and eventually *removes* them rather than grandfathering old pins, so about **every 1β2 years** those pins need a version bump. It's a two-line edit when it comes due; ignoring it indefinitely is the thing that would ultimately break an otherwise-immortal job.
**Bottom line:** the infrastructure has no built-in expiry and no recurring cost, so there's no fixed lifespan β but "runs itself forever with nobody ever looking" isn't truthful. The accurate promise is **years of hands-off daily operation, punctuated by a ~1β2-year maintenance touch (an action-version bump) and a possible one-click re-enable if GitHub's 60-day rule turns out not to count bot commits.** Design-wise it's built to survive neglect: a missing state cache just self-re-baselines, a flaky calendar server just retries next day, and every timestamp already earned stays valid no matter what happens to this repo.
---
## π How To Use It
### 1οΈβ£ Grab the log
```bash
curl -O https://thumpersecure.github.io/phl-rental-license-log/changes.ndjson
```
One JSON object per line. No parsing ceremony.
### 2οΈβ£ Look up one license
```bash
grep '"licensenum":"602204"' changes.ndjson | jq .
```
### 3οΈβ£ Find every license that expired
```bash
jq -c 'select(.diff.licensestatus.to == "Expired")' changes.ndjson
```
### 4οΈβ£ Find every license renewed *after* it expired β the lapse detector
```bash
jq -c 'select(.diff.licensestatus.from == "Expired" and
.diff.licensestatus.to == "Active")' changes.ndjson
```
### 5οΈβ£ Every property cited for operating unlicensed
```bash
curl -O https://thumpersecure.github.io/phl-rental-license-log/violations_changes.ndjson
jq -c 'select(.new.violationcode | startswith("9-3902"))
| {case:.new.casenumber, addr:.new.address,
issued:.new.violationdate, resolved:.new.violationresolutiondate}' \
violations_changes.ndjson
```
### 6οΈβ£ Violations for one address β with the official NOV
```bash
grep '"address":"315-23 N 12TH ST"' violations_changes.ndjson | jq '.new.publicnov'
```
Each record carries `publicnov` β a direct link to the City's **official Notice of Violation PDF**.
### 7οΈβ£ Check the latest run
```bash
curl -s https://thumpersecure.github.io/phl-rental-license-log/latest.json | jq .
```
---
## π©Ή Known data anomalies
The log is append-only and timestamp-anchored, so it is never rewritten β bad City data is annotated, not deleted. Known events:
- **2026-10-21** β the City feed returned blank (NULL) address, ZIP, parcel, OPA account and owner for ~99,000 licenses; the log holds 99,038 `updated` records that are **not real changes**. The search page labels them as a feed outage.
- **2026-10-22** β no log entries exist (the daily push failed); that day's real transitions surface on 2026-10-23.
Full counts, verification steps and a Carto query: **[ANOMALIES.md](ANOMALIES.md)**.
---
## π¦ What's In Here
| File | What it is |
|:--|:--|
| **`changes.ndjson`** | π **Append-only.** One line per detected change. The whole point. |
| **`violations_changes.ndjson`** | βοΈ **Violations archive.** Β§9-3902 citations, 2010βpresent. |
| **`violations_latest.json`** | π Summary of the most recent violations run. |
| **`state.json`** | πΈ Last-known state of every tracked license (the diff basis). |
| **`latest.json`** | π Summary of the most recent run. |
| **`index.html`** | π The public page. |
### Change record shapes
```jsonc
// a license changed
{"ts":"β¦","licensenum":"602204","change":"updated",
"diff":{"licensestatus":{"from":"Expired","to":"Active"},
"expirationdate":{"from":"2026-02-28β¦","to":"2027-02-28β¦"}},
"new":{β¦}}
// first time we ever saw it
{"ts":"β¦","licensenum":"000001","change":"initial","new":{β¦}}
// left the Active/Expired set entirely
{"ts":"β¦","licensenum":"β¦","change":"left_set","last":{β¦}}
```
### Tracked fields
**Licenses** β `licensestatus` Β· `expirationdate` Β· `mostrecentissuedate` *(renewal)* Β· `inactivedate` Β· `address` Β· `opa_account_num` Β· `zip`
**Violations** β `violationcode` Β· `violationcodetitle` Β· `violationstatus` Β· `violationdate` Β· `violationresolutiondate` Β· `casestatus` Β· `underappeal` Β· `publicnov`
---
## π§ How It Works
| | |
|:--|:--|
| **Source** | `https://phl.carto.com/api/v2/sql` β public, no auth |
| **Scope** | Rental licenses (`Active`/`Expired`) + Β§9-3902 violations, **citywide** |
| **Volume** | 99,348 licenses Β· 26,817 violations |
| **Schedule** | Daily, 08:15 UTC (**~4:15 AM ET**) |
| **Storage** | Changelog-style β only deltas are written |
| **Load** | A handful of paginated API calls per day |
---
## β οΈ Scope
> [!IMPORTANT]
> The **violations archive is complete history** β every Β§9-3902 citation issued since 2010.
> The **license log is forward-capturing**: it records status changes from `2026-08-21` onward and cannot reconstruct a license's status before that date.
> [!NOTE]
> Independent project. **Not affiliated with, endorsed by, or operated by the City of Philadelphia.** All data is the City's own public open data.
---
### π¬ Questions or feedback?
**[onlinemartialartist@pm.me](mailto:onlinemartialartist@pm.me)**
Built with public data Β· Because the record should outlive the refresh.