City permitted events (NYC & San Francisco), change detection

Upcoming permitted public events — block parties, street fairs, farmers markets, parades, races, film shoots, plaza events — straight from New York City's and San Francisco's own open-data APIs, normalised to one schema, with a change flag on every row: what is new since your last run, what moved, and what quietly disappeared.

Spec (10 lines)

1. What: upcoming permitted public events for NYC and San Francisco from each city's official open-data API, normalised to one schema, with per-run change flags.
2. Buyer: food trucks and vendors, local retailers, event-listing sites, logistics and rideshare planners, location scouts, local newsrooms — anyone who needs "which street is closed for what, and when" without polling two portals.
3. Input: cities, daysAhead (1–180), eventTypes, includeSportsPermits, onlyChanged, includeRemoved, snapshotStoreName, maxRowsPerCity.
4. Output: one row per event occurrence — city, eventKey, eventId, name, category, sourceType, startLocal, endLocal, startUtc, endUtc, timezone, area, locations[], streetClosure, permitStatus, permittingAgency, communityBoards[], datasetUrl, fetchedAt, change, changedFields[].
5. Pricing: pay-per-event event-record at $0.001 ($1 per 1,000 rows). onlyChanged charges only for rows that moved.
6. Legal floor: official open-data APIs only, under licences that permit reuse (below); robots.txt checked and its crawl delay obeyed; no event website is scraped.
7. How it works: query the city API for events overlapping your window → normalise → merge multi-street permits into one event → diff against your own snapshot → write rows with change flags.
8. Tests: golden normalisation per city, time-zone and DST handling, query building, paging and polite-delay behaviour, change detection, and a full run against a local stand-in server. No network needed.
9. Health: a small nightly run reads two weeks of San Francisco events and checks the row shape.
10. Not built: scraping of ticketing or meetup sites. Cities join only when their data licence permits reuse and their feed is actually kept current.

Sources and licences

City	Dataset	Published by	Licence	Refresh
New York City	NYC Permitted Event Information	Office of Citywide Event Coordination and Management	NYC Admin. Code §23-502(d): public data sets are made available "without any registration requirement, license requirement or restrictions on their use"	daily
San Francisco	Temporary Street Closures, special events only	SFMTA	Open Data Commons PDDL 1.0	daily

Each run stores an attribution line per city in the ATTRIBUTION record. Neither city endorses this actor or its output, and neither guarantees the completeness or accuracy of its data; nor does this actor.

What you get, and what you never get

• Events, not people. Rows carry the event name, when, where, what kind of closure, and the permitting agency. Contact details (phone numbers, email addresses) and the names of individual applicants are never emitted — the two sources used here do not publish them, and the parser drops any such field if one ever appears.
• Times you can trust. NYC publishes local wall-clock times; San Francisco publishes UTC. Every row carries both startLocal (city time) and startUtc, plus the timezone, correct across daylight-saving changes.
• One row per event. San Francisco lists one row per closed street segment and NYC sometimes one row per location; segments of the same permit at the same start time are merged, with every street in locations.
• Ongoing permits included. An event is in your window if it overlaps it, so a street closed since spring and still closed this weekend shows up.
• NYC sports field permits are off by default — tens of thousands of youth and adult field reservations a month. Turn on includeSportsPermits if you want them.

Categories

block-party, street-festival, farmers-market, parade, athletic-race, sidewalk-sale, plaza-event, open-street, religious-event, film-production, special-event, street-event, clean-up, press-conference, sports-permit, other. NYC's own event type maps directly (sourceType keeps the original). San Francisco labels everything "Special Event", so its category is inferred from the event name and falls back to special-event.

Change flags

change	Meaning
new	Not seen on your previous run (every row on your first run)
updated	Same permit and start time, but the name, end time, locations, closure type, status or category changed — changedFields names which
removed	Was upcoming on your previous run, is still inside this run's window, and is no longer in the city feed: cancelled, denied or rescheduled (the city does not say which)
unchanged	Nothing tracked moved

Honesty rules: a run that hit maxRowsPerCity never updates your snapshot and never reports removals — a partial read proves nothing about what is missing. A refused or unreadable feed produces one outcome: "problem" row for that city, is not charged, and leaves your snapshot untouched.

Example output row

{
  "city": "sf",
  "eventKey": "sf:1700002:2026-10-17T15:00:00.000Z",
  "name": "Bay Street Fair",
  "category": "street-festival",
  "startLocal": "2026-10-17T08:00:00",
  "startUtc": "2026-10-17T15:00:00.000Z",
  "timezone": "America/Los_Angeles",
  "locations": ["BAY ST between 01ST AVE and 02ND AVE", "BAY ST between 02ND AVE and 03RD AVE"],
  "streetClosure": "all-lanes-closed",
  "permitStatus": "Approved",
  "change": "new"
}

(Illustrative values.)

Lawful and responsible use

This actor reads public open data through the cities' published APIs, identifies itself with a named user agent and a contact address, checks robots.txt, and never requests faster than the host's crawl delay (one request per second on both hosts). It does not log in, does not work around a refusal, and does not collect personal data. If you add an optional SOCRATA_APP_TOKEN environment variable (a free token from the portal), requests are attributed to your token instead of sharing an anonymous pool.

---

Built and maintained with AI assistance under human review.