Recommendation API for Cinemas, Venues and Event Listings
A listing changes daily, sells out and can only be enjoyed at one time on one night. TasteRay ranks this week's programme against what a couple or a group asks for. The calendar stays your job.
TasteRay is a recommendation API for cinemas, venues and event listings. You send what someone wants from their evening and up to ten screenings or events on sale, and one request returns them ranked with a written reason. It ranks single events, so your code must handle dates, seats and whether two picks can both be attended.
Cinema and event programmes have a problem that movie libraries do not: everything expires. A pick for Saturday at 18:30 is worthless on Sunday and useless if it has sold out, and a couple rarely want the same thing. This page shows how a real request handled that, including where it fell short.
A couple, a weekend, ten things on sale
We wrote a ten-item programme with times in the names: a blockbuster, a quiet drama, a jazz night, a horror marathon, children's shows and an opera broadcast. One person loves quiet drama, the other likes live things, and they want evenings only. The children's morning shows and the midnight marathon did not come back.
{
"vertical": "cinema and events",
"context": {
"profile": "Couple planning a weekend. One loves quiet drama, the other likes live things. Evenings only.",
"preferences": [
"weekend",
"date night"
]
},
"items": [
{"id": "e2", "name": "Past Lives — Sat 18:30", "description": "Quiet romantic drama, arthouse screen.", "metadata": {"type": "screening"}},
{"id": "e4", "name": "Jazz Quartet Night — Thu 21:00", "description": "Live jazz in the foyer bar.", "metadata": {"type": "live event"}},
// ...and 8 more: an IMAX screening, a children's matinee, a midnight marathon and others
],
"options": {"count": 3}
}meta.processing_time_ms 1,582. The model's sentences are verbatim.Past Lives — Sat 18:30
95 out of 100, taste_match_score
This is the perfect anchor for your weekend—it honors your love for quiet drama while offering a deeply intimate, human experience that serves as the ultimate date night.
- It’s an arthouse screening, which fits the 'sophisticated date' vibe you're likely looking for. It’s not a blockbuster; it’s a shared emotional experience designed for connection.
Stand-up: Local Comedians — Sat 20:00
85 out of 100, taste_match_score
This directly satisfies the need for 'live things' while keeping the vibe casual, short, and perfect for a social date night that flows into dinner or drinks.
- The 20:00 start is excellent for a date. It’s late enough to skip early dinners but early enough to stay out and keep the night going without being exhausted.
Jazz Quartet Night — Thu 21:00
80 out of 100, taste_match_score
This is the elegant compromise for your weekend. It’s a live event (satisfying the 'live things' lover) but in a quiet, intimate setting (honoring the 'quiet drama' lover’s need for calm).
- You mentioned 'evenings only,' and a 21:00 start in a bar is the perfect wind-down activity. It’s not a high-energy party; it’s a sophisticated, ambient experience.
Fields shown: item.name, metadata.taste_match_score, explanation.why_match, explanation.key_factors.
Where the ranking stops and your code starts
Read those three picks as a planner would. The first two are both on Saturday, at 18:30 and 20:00, and may overlap. The third is on a Thursday although the request said "weekend", and the model's reason calls that a pre-weekend warm-up. Each pick answers the request on its own, and together they do not make a plan.
So treat dates as your responsibility. Remove anything outside the requested window before you send, and if you want a whole evening, send a second request after the first choice, without the clashing items. context.constraints takes hard limits as key-value pairs, and we did not test it on this example, so filter first and treat it as a second line.
We also removed some sentences about things the model could not know, such as how good a local comedy night would be. Your listing is often the only information it has about a one-off event, so what you write in description matters, and invented detail needs catching in review.
What changes for a cinema or venue
- Build the list from what is on sale
- Take candidates from your ticketing system at request time: on sale, seats left, in the requested window and at the chosen venue. The API only returns items from the list you send.
- Short cache lifetimes
- A cached row of showtimes goes stale when a screening sells out. Cache the ranking of titles or acts for the week, and join live times and availability when you render the page.
- Ask about the group
- Our request described two people with different tastes, and the reasons addressed both. A date-night or family option in your finder gives the model what it needs from one tap.
- Rank the title or the screening
- One movie with twelve showtimes can take every slot. Send one item per title or act, rank those, then show the person the times that suit them.
- Names and times
- We put the day and time in the item name, and they came back in the result. You may prefer to keep those in
description, and match results to your own record byitem.id, which comes back with the exact name you sent. Fewer results than you asked for can come back.
For a cinema chain or a ticketing platform
A single venue can start on a free key, and a precomputed weekly ranking costs few requests. For a chain, 200 venues × 30 audience themes refreshed weekly is about 26,000 requests in a 30-day month, within Pro at $199 a month for 100,000. For your own brand, higher limits and an SLA, see Enterprise.
Sources and further reading
FAQs about Recommendation API for Cinemas, Venues and Event Listings
Can TasteRay recommend screenings and live events together?
Yes. An item is anything you can name and describe. In a capture on 5 November 2026 one request held screenings, stage shows and a jazz night, and returned a movie, a comedy night and the jazz night. Send only what is on sale, and join live times and seats when you render the result.
Does TasteRay check dates and whether events clash?
No, so handle that in your code. In our capture two picks fell on the same Saturday evening and a third fell on a Thursday although the request said weekend. Remove anything outside the requested window before you send, and treat each result as a ranked option rather than a finished plan.
How do we keep recommendations current when showtimes change?
Separate the ranking from the listing. Rank titles or acts for the week and cache that, then read showtimes and seats from your ticketing system when you render the page. The API stores nothing between requests, so a new request with a new list always reflects what you send it.