Booker

Book the acts your room's crowd already loves: Booker uses Qloo's taste graph to find acts that fit a venue's crowd and size, score the pitches in its inbox, and route tours to the rooms that fit.

Comment

Inspiration

An independent venue lives or dies by its calendar, and its talent buyer decides week after week which acts will fill the room. Bookers describe the match in two words, style and size: First Avenue's booker places a band "if we think it fits better style-wise or size-wise", and a new band's first time through plays the small room. Today that judgment runs on streaming counts and instinct; venue software manages holds and settlements, not taste, and the emerging acts a small room books most have the least data. Last year's Qloo hackathon had 343 entries and none for venue booking. I wanted an agent that answers the booker's real question with evidence: who does the crowd of my best shows also love, at my size, in my city?

What it does

For a venue. Name your venue with its city and the acts that did well there, and optionally paste the acts pitching you.

  • Finds the room and the acts in Qloo. The venue is a Qloo place filed as a music venue, a theater, or a bar or club where shows happen (a record store, a cinema or a golf club with the same name doesn't count); the typed city, or its metro area, decides between rooms that share a name. Each act is resolved the way Qloo's harness does: an exact name first, a near-miss only if it resembles what you typed, and "Not it?" lets you pick another candidate by its Qloo ID.
  • Measures your room's size from your own history. The acts you named have a Qloo popularity; that range is your size. Qloo's popularity bunches up near 1 (in the rooms I checked, small-club acts sat around 0.35 to 0.55, 300-800 capacity clubs 0.90 to 0.97, theaters 0.98 to 0.99), so Booker compares sizes on a log scale. It's Qloo's own measure, not ticket sales (a stadium act, Morgan Wallen, scores 0.968), so size verdicts are a guide and taste is judged separately.
  • Ranks acts that fit: artists your acts' fans love (Qloo affinity), at your size, with your city as a signal. Openers and next-up acts come from the same crowd below your range, optionally favoring rising acts (Qloo trends).
  • Explains each pick: the act of yours whose fans like it most.
  • Suggests bills you could announce: each top act with the opener whose fans overlap most.
  • Scores your inbox: each pitch fits your room, fits as an opener, is bigger than your room, or is off your crowd's taste, with the numbers behind it.
  • Shows the competition: the rooms in your city whose visitors fit the top act best, and where yours ranks.

For an artist or agent. Name the act and up to five cities: each city is scored by Qloo's affinity for the act there, and in each city Qloo ranks the live music venues and concert halls whose visitors' taste fits the act's fans. The rooms go on a map.

Shows its work. A "How we know" panel lists every Qloo call with its parameters, status, result count and time, then Booker's own rules (labeled apart from Qloo's numbers), then the limits of the answer. Works for agents too: the same pipelines are two MCP tools; when a name is uncertain, the answer says which Qloo entry was used, with its id, lists any alternatives, and the tool tells the agent to ask the person.

Example (a real run): Mohawk in Austin, with Black Pumas, Shakey Graves, The Black Angels and Parquet Courts as its good nights, gets Allah-Las, The Arcs, King Gizzard & The Lizard Wizard and Kevin Morby, with Austin's own White Denim further down; a bill of Allah-Las with Kikagaku Moyo opening; Khruangbin and Wet Leg from the inbox fit, Morgan Wallen doesn't; and Qloo's top room in Austin for Allah-Las's fans is Mohawk itself. For the indie band Wednesday, the route Chicago, Austin, Asheville and London ranks Asheville first (0.996, their hometown) and finds Schubas and The Empty Bottle in Chicago, Hotel Vegas and Mohawk in Austin, The Shacklewell Arms and The Lexington in London.

How I built it

  • Cloudflare Worker (TypeScript) serving the page, a JSON API and an MCP server (@modelcontextprotocol/server, Streamable HTTP). No language model: every step is a Qloo call or a labeled rule.
  • Qloo calls: /search for the venue (places) and the acts (artists); /entities for an ID the person picked; /v2/insights for artists with signal.interests.entities (your acts, one act, or the venue itself), signal.location.query (the venue's city), filter.popularity.min/max (your size), filter.exclude.entities, filter.results.entities (to score a given list: closest act, bill overlap, the inbox) and bias.trends; /v2/insights for places with the live-music-venue and concert-hall tags and filter.location.query (rooms that fit an act); and the city as the only signal with filter.results.entities (a city's taste for an act); when Qloo reads a route city as somewhere else or as a part of it, or gives the act no score by its name, both are asked again with signal.location / filter.location as a point and a radius sized by the city's population (3 to 25 km) around its centre, never keeping a room in another country (Qloo's geocode country, territories counted as their country's) and giving no score when the circle is mostly abroad.
  • Grounded geography: a venue's city comes from Qloo's own geocode; route cities are located with Open-Meteo and checked against the locality Qloo matched.
  • Built for the free plan: every fetch and cache call is counted against Cloudflare's 50-subrequests-per-request limit, Qloo calls are paced one every 340 ms with one bounded retry, results are cached for a day, and each address gets 20 new searches an hour (answers from the cache don't count).
  • Tests: 95 automated tests against a mock shaped like the live API (one runs 472 realistic venue, artist and list inputs through the name matching, another 349 names, most with a note in brackets, on Qloo's recorded live answers, another 457 ways people type tour cities through the city lookup, on recorded geocoder answers), each rule checked by deliberately breaking it (replacing the log size scale with a linear one breaks at least 5 of them); the inbox threshold was set from 10 live pitches at 4 rooms.

Challenges I ran into

I measured the hackathon API before designing, and several answers shaped the product:

  • Artists accept the city as a signal although the parameter guide doesn't list it: it works for cities and comes back empty for neighborhoods; an unknown city is a 400, so Booker asks again without it and says so.
  • With the city as a signal, scoring a given list leaves some off-taste artists out entirely, so the inbox is scored by taste alone, next to three of Qloo's own picks as a yardstick.
  • Popularity is a percentile that bunches near 1: a fixed margin made theater acts look like a club's fit, so sizes are compared on a log scale.
  • Demographics came back for only some artists and looked noisy for small acts, so Booker leaves them out.

Accomplishments that I'm proud of

  • It serves both sides of a booking: the venue looking for acts, and the act looking for rooms.
  • Every number traces to a specific Qloo call, and Booker's own rules are labeled as such.
  • The results read like a booker's notes: a shortlist, a bill, an inbox verdict, the competition in town.

What I learned

The hard part of booking isn't finding names, it's knowing which names fit this room. Qloo's cross-domain graph answers both halves: which artists a crowd loves, and which rooms that crowd visits.

What's next

  • Import a venue's past calendar instead of typing the acts.
  • Pair the route with dates: which rooms fit, on which nights.
  • Add each room's capacity from open data, so the artist view sizes rooms as well as matching taste.

Built With

Share this project:

Updates

Submission history