Building a self-updating .ics auction calendar from 150+ sources

#webdev #api #showdev #programming

HammerAlert tracks upcoming auctions from 150+ houses and exposes them as a single calendar feed you can subscribe to in Apple Calendar, Google Calendar, or Outlook. Here's how the calendar side of it actually works.

The hard part isn't the calendar — it's the sources

Every auction house publishes its schedule differently: different page structures, date formats, time zones, category names, and languages. Before anything can land in a calendar, all of it has to be pulled in and normalized into one shape.

One schema for every sale

Each upcoming sale becomes a record with the same fields, no matter where it came from:

house — Christie's, Phillips, Bukowskis…
title — the sale name
category — jewellery, watches, modern & contemporary art…
region — UK, Europe, US, Asia & Pacific
start — start date/time, stored in UTC
url — link back to the house's own listing

Normalizing region, category, and time zone up front is what makes filtering and a clean calendar possible later.

A personal, tokenized .ics feed

Calendar apps don't authenticate against an API — they fetch a plain .ics URL on a schedule. So every signed-in user gets their own tokenized feed:

hammeralert.com/api/calendar/your-personal-token.ics

The token identifies the user and their preferences without a login, so the URL is safe to paste into a calendar app but still personal. The endpoint renders the filtered set of sales as standard iCalendar VEVENTs on each request.

Filtering happens server-side

Because the feed is generated per token, the user's saved preferences — categories, regions, specific houses — are applied when the .ics is built. The calendar app only ever sees the sales that matter to that person, not all 2,000+ upcoming lots.

Staying fresh automatically

Calendar clients re-fetch the feed periodically. When a house adds, moves, or cancels a sale, the next fetch reflects it — no re-importing, no manual sync. Add the URL once and it keeps itself up to date.

Takeaways

Normalize messy sources into one schema before you think about output
A tokenized .ics URL gives you personalization without an auth flow in the calendar client
Let the calendar app's own refresh cycle do your syncing

You can see it in action at hammeralert.com.