Publish Your Events
Standard, documented ways to make your events easy for our scraper to find and ingest. Pick whichever fits your site — we are not inventing formats; where a standard already exists, we use it as-is.
What we need
However you publish, we ultimately need each event's title, description, start/end
date-time, location, cost, a link back to your page, and (ideally) an image. That's the
same event schema documented in full on How to Consume Our
Data — see that page for the exact field-by-field reference
(export.writer.SITE_SCHEMA_FIELDS). This page doesn't restate that list; it
explains which of the methods below gets your data into it.
Every method here maps onto our existing Adapter framework
(partner_scrape/adapters/), dispatched by an adapter_type —
registering a new type is a one-line addition to the ADAPTERS table in
adapters/__init__.py. Nothing below is a bespoke, one-off pipeline.
Choose a publishing method
Ordered easiest-adoption-first. Each method is labeled Works today if it already runs against real partner data with no new code, or Proposed — not yet built if it's part of the multi-pronged strategy but doesn't exist yet. Picking a proposed method today gives you nothing to act on immediately — see the "what you can do now" note in each of those entries.
C. iCalendar feed
Works todayHarmonizes with: the registered ical adapter (partner_scrape/adapters/ical.py).
If you already publish an .ics calendar feed (RFC 5545 — many calendar
plugins, including The Events Calendar, expose one at a URL like ?ical=1),
give us the feed URL and we can start ingesting it unchanged. This costs us nothing new
to build — it's the lowest-friction option on this page. Recurring events (an
RRULE) are expanded into individual occurrences automatically, bounded to
180 days or 52 instances so an unbounded rule can't produce unbounded output.
What you can do now: send us your .ics URL via the contact form.
B. Sitemap + schema.org Event JSON-LD
Works today Recommended Harmonizes with: the generic_html / listing_html
adapters' extraction ladder (partner_scrape/extract/ladder.py). This is the
single highest-value thing you can do — JSON-LD is rung 1 of that
ladder, read at confidence 1.0, the highest trust tier we have, ahead of every fallback
(<time> tags, OpenGraph tags, title/URL guessing, body-text regex).
It requires no new adapter work from us: this rung has been live since sprint 002 and
already runs on every event page fetched through a registered generic_html
or listing_html source.
The standard way to make an event page machine-readable: embed
schema.org Event structured data as JSON-LD
(<script type="application/ld+json">) on each event page, one event
per page, and list those pages in your sitemap.xml — we already discover
candidate event URLs from a sitemap. Many CMSes and event plugins emit this
automatically, and it's the same markup Google's event rich results (and increasingly
AI answer engines) already consume, so you may get it "for free."
Fields our ladder reads directly from your JSON-LD, today:
| Your JSON-LD property | Becomes |
|---|---|
name | title |
description | description |
startDate | start date/time |
endDate | end date/time |
location (a string, or a Place with a nested address) | location |
offers (single Offer or list — first one's price) | cost |
image (a URL string, list, or ImageObject) | event image |
That covers the factual core of an event. Controlled-vocabulary categorization on the full schema — age/grade level, cost bucket, time-of-day, opportunity type, subject-area tags — is still applied by our own pipeline afterward; your markup doesn't need to (and can't) supply those.
What you can do now: add Event JSON-LD to your event pages and make sure they're in your sitemap. If your site isn't registered as a source with us yet, that's a one-time step on our side — reach out via the contact form and we'll get it set up.
A. .well-known discovery pointer
Proposed — not yet built Would join: a new discovery step reading a small pointer file at a
.well-known path (the same pattern as security.txt or
llms.txt) that names the URL of your real feed — your .ics,
your JSON-LD sitemap, or a schema-E JSON file below — and hands it to whichever existing
adapter matches. Not a new event format; a discovery pointer to one of the formats above.
No code reads a .well-known pointer today. This method is not yet available
to act on — it's listed here so you know it's part of the plan.
D. OpenActive feed
Proposed — not yet built Would join: a new openactive adapter type (not yet
registered).
OpenActive is a real, purpose-built open-data standard for "opportunity data" — the same term we use — built on schema.org with the RPDE (Realtime Paged Data Exchange) feed format. It's the most domain-appropriate standard here, but the heaviest to adopt, and no adapter reads it yet. Flagged as a stretch goal for a partner who already publishes an OpenActive feed elsewhere.
E. Our own JSON in our schema (universal fallback)
Proposed — not yet builtWould join: a new, small adapter type reading a partner-hosted JSON file directly (not yet registered).
For an organization with no calendar feed and no CMS plugin: host a JSON file at a
documented path in the same schema documented on
/data-access, and reference it from the .well-known
pointer above (A) once that exists. This guarantees every partner has at least one
option, even with the simplest possible site. No adapter reads this today.
Not sure which to pick?
If you want something we can start using immediately: already have a calendar feed? Send
us the .ics URL (C). Building or updating event pages? Add
Event JSON-LD and list those pages in your sitemap (B) — the same extraction
we already run today, at our highest trust tier. Everything else on this page (A, D, E) is
part of the roadmap, not something to build against yet. Questions, or ready to get
started? Reach out via the contact form.