DEV Community: Elliot Marsh

Your AI agent can earn a commission on the travel it recommends

Elliot Marsh — Wed, 21 Oct 2026 01:18:19 +0000

Agents already recommend restaurants, food tours and hotels all day. When a person books one of those, someone usually earns a commission. It is almost never the agent, or the developer who built it.

We run TableJourney, a food travel guide with a public MCP server over 224 cities: verified places to eat, food festivals with resolved dates, and bookable food tours, classes and stays from GetYourGuide, Viator, Musement and hotel partners. This week we opened a partner program, and we built it for agents first.

The deal

50% of the commission we are paid on bookings made by the people you send. 60% in any month where your settled earnings pass $500.
Free to join. Payouts monthly by PayPal, crypto (USDC on Base or Solana, ETH, SOL or BTC) or bank transfer, from $10 ($25 in BTC, $50 by bank), 3 days after the booking partner pays us.
Our booking partners have approved sub-affiliates, so this is inside their terms, not around them.

Why half: the share is of our commission, not of the booking price, so a small percentage of it would be a few cents a booking. Half is enough to be worth an agent's while, and our pages still do part of the selling.

Joining without a browser

Everything is MCP tools on https://tablejourney.com/mcp (streamable HTTP, no key needed to read):

{"name": "partner_join", "arguments": {"accept_terms": true, "kind": "agent", "name": "My travel agent"}}

No email is needed: the answer holds an API key and a referral code at once. The key is the account, so keep it. Before the first payout, add the operator's email and confirm it:

{"name": "partner_add_email", "arguments": {"email": "<operator inbox>"}}
{"name": "partner_confirm", "arguments": {"email": "<operator inbox>", "code": "ABCD-2345"}}

The key stays the same. Payout details are confirmed by email, and a person or company behind the agent receives the payouts.

How a booking gets attributed

Send the key as Authorization: Bearer <key> on the MCP connection. From then on every booking link the read tools return (experiences, stays, tickets, car_hire and the rest) is a /go/ link signed for your key, and the link carries your code in the partner's own sub-id field: cmp for GetYourGuide, campaign for Viator, cid for Musement, clickref for Awin and sid for CJ. That sub-id is what each partner reports back with the commission, so attribution does not depend on a cookie surviving in somebody's browser.

If your agent sends people to pages instead, partner_link returns any tablejourney.com page with ?ref=<code>. The site holds the code for 30 days and stamps it into every partner link the visitor sees, including ones that appear after the page loads.

partner_stats shows visits, booking clicks, and earnings as pending, confirmed and paid. partner_payout_method sets where the money goes; it takes effect only after a code sent to the account's address, so a leaked key cannot redirect payouts.

For agents that prefer OAuth

The usual discovery documents are there:

/.well-known/oauth-authorization-server (RFC 8414), with dynamic client registration (RFC 7591) and PKCE S256
/.well-known/oauth-protected-resource (RFC 9728); a 401 from the partner API carries WWW-Authenticate pointing at it
/.well-known/agent-card.json, an A2A card whose food travel skill is answered by our own model from the same database

An MCP client that handles the OAuth flow can sign the person in through the browser instead of handling a key.

What we ask

Pass booking links on unchanged, tell people they are affiliate links, and point them at the page you got the facts from. The full terms are short: https://tablejourney.com/partners/terms/

Program page: https://tablejourney.com/partners/. Agent guide and the full tool list: https://tablejourney.com/agents/. Questions go to support@tablejourney.com, and we read them.

Stop storing event dates: store the rule and compute the next edition

Elliot Marsh — Fri, 16 Oct 2026 06:10:32 +0000

Most event listings go stale in a predictable way. Someone types "18 to 21 November 2026" into a database, the event happens, and the page keeps showing last year's dates until a person notices. For one-off events that is fine. For annual events it is a bug you ship every year.

At TableJourney we keep the next dates of about 1,400 food festivals. Typing dates by hand did not survive the first year, so we stopped storing dates and started storing the rule a festival follows. The site computes the next edition from the rule every day. This post shows the shapes of rule we needed, with working Python.

Three kinds of recurrence

After going through the whole dataset, almost every annual event fell into one of three groups:

Fixed day of the year. "Every 24 to 26 December." The easy case: store month and day, roll the year forward.
Nth weekday of a month. "The third Thursday of November, for four days." The weekday holds, the day number moves.
Anchored to a moveable feast. Easter, Lunar New Year, Mid-Autumn, Ramadan, Diwali. These move by weeks between years, so neither of the first two works.

A fourth shape, "the weekend after Lunar New Year", turned out to be common enough to need its own rule, and it is the one that catches people out.

The rule as data

Each event carries a small date_rule object instead of a date. These are real rules from our data:

{"nth_weekday": [3, "Thursday"], "length": 4}
{"nth_weekday": [-1, "Monday"], "offset": -1, "length": 2}
{"anchor": "easter", "end_offset": -47}
{"anchor": "chinese-new-year", "start_offset": 0, "end_offset": 14}
{"anchor": "chinese-new-year", "weekday_after": "Saturday", "length": 2}

The second one reads "the Sunday before the last Monday of the month, for two days", which is how a lot of bank-holiday weekend events are actually defined. The month comes from the event's stored start_month; the rule never contains a year, so it keeps working.

Nth weekday

The helper is short. n is 1 to 5, or -1 for the last one:

import calendar
import datetime as dt

def nth_weekday(year, month, weekday, n):
    """n-th (1..5, or -1 for last) weekday (0=Monday) of the month."""
    days = [
        dt.date(year, month, d)
        for d in range(1, calendar.monthrange(year, month)[1] + 1)
        if dt.date(year, month, d).weekday() == weekday
    ]
    if n == -1:
        return days[-1]
    return days[n - 1] if 1 <= n <= len(days) else None

print(nth_weekday(2026, 11, 3, 3))   # third Thursday of November 2026
print(nth_weekday(2027, 5, 0, -1))   # last Monday of May 2027

2026-11-19
2027-05-31

Returning None for "the fifth Friday" in a month that has four is deliberate: the caller can then look at the next year instead of inventing a date.

Easter: compute it, do not table it

Easter is the one moveable feast you can compute exactly. This is the Anonymous Gregorian algorithm, as it sits in our code:

def easter(year):
    """Gregorian Easter Sunday (Anonymous Gregorian algorithm)."""
    a = year % 19
    b, c = divmod(year, 100)
    d, e = divmod(b, 4)
    f = (b + 8) // 25
    g = (b - f + 1) // 3
    h = (19 * a + b - d - g + 15) % 30
    i, k = divmod(c, 4)
    l = (32 + 2 * e + 2 * i - h - k) % 7
    m = (a + 11 * h + 22 * l) // 451
    month, day = divmod(h + l - 7 * m + 114, 31)
    return dt.date(year, month, day + 1)

print([str(easter(y)) for y in (2026, 2027, 2028)])

['2026-04-05', '2027-03-28', '2028-04-16']

Carnival, Lent markets and anything defined as "N days before Easter" become an offset from this date. The {"anchor": "easter", "end_offset": -47} rule above ends a season on Shrove Tuesday, 47 days before Easter Sunday.

Lunar and religious calendars: a small table, sourced

Lunar New Year, Mid-Autumn, Ramadan, Eid and Diwali cannot be computed reliably from a formula you want to maintain. We keep a small JSON table of anchor dates per year, each from a published source (an observatory's lunar tables, published religious calendars), and the code reads it:

{"chinese-new-year": {"2026": "2026-02-17", "2027": "2027-02-06", "2028": "2028-01-26"}}

The table has an end. When an anchor runs out of years, the resolver returns None and the event keeps its stored month and day, and the data validator flags every rule whose anchor table ends too soon, so the table gets extended before it matters. A table that silently ends is worse than no table.

The weekend-after rule

Here is the trap. London's Chinatown celebration happens on the first weekend on or after Lunar New Year. In 2026 the holiday is a Tuesday, so the event is the following Saturday. In 2027 the holiday is itself a Saturday. A fixed offset like "+4 days" lands on a Saturday one year and a Wednesday the next, so it cannot express this. Snap forward to a weekday instead:

WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]

def snap_forward(day, weekday_name):
    target = WEEKDAYS.index(weekday_name)
    return day + dt.timedelta(days=(target - day.weekday()) % 7)

lny_2027 = dt.date(2027, 2, 6)
start = snap_forward(lny_2027, "Saturday")
print(start, start + dt.timedelta(days=1))

2027-02-06 2027-02-07

We also support weekday_nearest (the closest named weekday in either direction) for events that celebrate a holiday on the weekend nearest to it.

Picking the next edition

With an occurrence function per rule, the next edition is the earliest occurrence that has not ended yet. Check a small window of years, because an event in early January belongs to next year when you ask in December, and a season that started last year may still be running:

def next_occurrence(rule_occurrence, today):
    best = None
    for year in (today.year - 1, today.year, today.year + 1, today.year + 2):
        occ = rule_occurrence(year)          # (start, end) or None
        if occ and occ[1] >= today:
            if best is None or occ[0] < best[0]:
                best = occ
            break
    return best

Comparing against the end date rather than the start keeps a running event on the page as "on now" until its last day. Some events run several editions a year (restaurant weeks in winter and summer), so the real code takes a list of rules and picks the soonest across all of them.

What this bought us

Titles, snippets and structured data always show the next real dates, with no yearly data entry.
One Hong Kong page had been advertising 17 February 2027 for Lunar New Year, when the holiday is on the 6th. A rule cannot make that mistake.
The same resolved dates feed everything downstream: the pages, the calendar feeds, the API and an open dataset. One computation, many outputs, no disagreements between them.

The rule format is deliberately boring JSON so that research agents and people can both write it. When a source states a pattern in prose ("the second weekend of September"), we encode the pattern, then check that the rule reproduces the date the organiser published for this year before trusting it.

If you want to see the result, the dates of all of these events are in an open dataset (CC BY 4.0) you can query or download: https://tablejourney.com/festivals/statistics/ has the summary and the links. How do you handle recurring dates in your own projects? I would like to hear about rule shapes we have not needed yet.

Food festival dates as open data: a free API, an MCP server and SQL

Elliot Marsh — Mon, 05 Oct 2026 15:20:46 +0000

Every year I hit the same problem planning food trips: festival listings tell you a festival exists, but not when the next one is. Pages still show last year's dates, or say "every autumn".

So at TableJourney we keep the next dates of more than 1,500 food festivals in 55 countries, and we have opened the data up four ways: a REST API, an MCP server for AI assistants, a SQL copy on DoltHub and a plain CSV. All free, no sign-up.

How the dates stay current

A date like "the second weekend of October" goes stale every year. So we store each festival's recurrence rule rather than a date: nth weekday of a month, a fixed day, or an anchor such as Easter or the lunar calendar for Lunar New Year and Mid-Autumn markets. The next edition is computed from the rule, and each festival page carries the source we checked and the date we checked it.

REST: festivals between two dates

curl "https://tablejourney.com/api/v1/festivals?country=italy&from=2026-10-10&to=2026-11-30&limit=3"

Each result has a name, city, starts_on, ends_on, month, whether it is annual, a short summary and a link to the page with the sources. The same API answers other trip questions, for example the signature dishes of a city and where to eat them:

curl "https://tablejourney.com/api/v1/dishes?country=japan&city=osaka&limit=2"

[{"name": "Omurice", "city": "osaka", "country": "japan",
  "summary": "Ketchup-seasoned chicken rice wrapped in a soft folded omelette...",
  "where_to_eat": [{"name": "Hokkyokusei Shinsaibashi", "page": "https://tablejourney.com/japan/osaka/casual-dining/hokkyokusei-shinsaibashi/"}]}]

The full list of endpoints (places, a composed food day, experiences, things to do) is in the OpenAPI docs at https://tablejourney.com/api/v1/docs.

MCP: ask an assistant

The same data is a remote MCP server (streamable HTTP) at https://tablejourney.com/mcp. In Claude Code:

claude mcp add --transport http tablejourney https://tablejourney.com/mcp

Or in any MCP client config:

{ "mcpServers": { "tablejourney": { "type": "streamable-http", "url": "https://tablejourney.com/mcp" } } }

Then ask things like "which food festivals are on in Spain the week I am there" or "plan a vegetarian food day in Lisbon on Sunday". Tools include festivals, search_places, plan_day, things_to_do and experiences. Setup notes for other clients are at https://tablejourney.com/agents/.

SQL: query it on DoltHub

The dataset is mirrored weekly to DoltHub, so you can query it without downloading anything:

SELECT month, COUNT(*) AS festivals
FROM festivals
GROUP BY month
ORDER BY festivals DESC
LIMIT 3;

Today that returns October (197), September (190) and November (161). Run it at https://www.dolthub.com/repositories/tablejourney/food-festivals or through DoltHub's SQL API.

Or embed it: free widgets

If you would rather show the dates than query them, the widget builder at https://tablejourney.com/widgets/ makes an embed in three steps: choose a widget, search a city or country, pick the colours, then copy one line of code. There are six widgets:

Festival calendar: the next food festivals in a city, a country or the whole world
Christmas markets: this season's markets and the dates each opens
Where to eat: our top places in a city, for any topic we cover
Signature dishes: what to eat in a city, with photos
City rank: the city's place in our food festival index
Statistics: charts of the world's festivals (busiest month, weekday, length, share free to enter)

The preview shows each widget on a light and a dark site, and the colours can be light, dark or automatic, which follows each reader's own setting. Every widget is a small static page in an iframe: no cookies, no scripts, and it updates itself daily. Every place we cover has every widget, so a city with nothing dated yet shows an empty state instead of breaking your page.

This is what the builder gives you for Chicago:

<iframe src="https://tablejourney.com/embed/festivals/united-states/chicago/" title="Food festivals in Chicago" width="100%" height="570" style="border:0;border-radius:14px;max-width:420px" loading="lazy"></iframe>
<p style="font-size:13px;margin:6px 0 0"><a href="https://tablejourney.com/united-states/chicago/festivals/">Food festivals in Chicago</a> by TableJourney</p>

Prefer a calendar app? Every city, country and kind of festival is also an .ics feed you can subscribe to in Google, Apple or Outlook, or import into an events calendar by URL, for example https://tablejourney.com/calendar/united-states/chicago.ics. The full list is at https://tablejourney.com/calendar/.

Download it

CSV and JSON on GitHub: https://github.com/lewismvaughan/tablejourney-food-festivals
A citable record on Zenodo: DOI 10.5281/zenodo.23142697
Charts and findings (busiest month, weekday, length, share free to enter): https://tablejourney.com/festivals/statistics/

The licence is CC BY 4.0: use it for anything, with a credit link.

If a date is wrong or a festival is missing, tell me in the comments or through the contact page; corrections from organisers are locked in so later updates cannot overwrite them.