> For the complete documentation index, see [llms.txt](https://syticks.gitbook.io/merpi-by-syticks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://syticks.gitbook.io/merpi-by-syticks/api-reference/cinema-ticketing-cinema-movies-available-days-purchase-etc/get-list-of-cinema-movies.md). # Get List of Cinema Movies Fetch a paginated list of cinema experiences (movies) with optional filtering and sorting. ``` GET /api/v1/merpi/experience?cinema=true ``` This page provides cinema-specific guidance for retrieving movie listings. For comprehensive documentation including all parameters, response fields, pagination, and examples, see the [**Get List of Experiences**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-list-of-experiences) page. **Important:** Cinema movies use the same endpoint as regular experiences. This page focuses on cinema-specific usage. The complete API reference is in the [**Get List of Experiences**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-list-of-experiences) documentation. #### Cinema-Specific Usage To retrieve only cinema experiences, add `cinema=true` to the experiences endpoint: ```http GET /api/v1/merpi/experience?cinema=true HTTP/1.1 Accept: application/json ``` ### Common Cinema Queries **Get all cinema movies** ```http GET /api/v1/merpi/experience?cinema=true ``` **Get featured movies** ```http GET /api/v1/merpi/experience?cinema=true&featured=true ``` **Search for a specific movie** ```http GET /api/v1/merpi/experience?cinema=true&search=breath+of+life ``` **Get movies by cinema business** ```http GET /api/v1/merpi/experience?cinema=true&business_id=764c6a94-7bda-448e-a8af-35a5bb536d4 ``` **Get recently added movies** ```http GET /api/v1/merpi/experience?cinema=true&sorted_by=just_added ``` **Combine filters** ```http GET /api/v1/merpi/experience?cinema=true&featured=true&sorted_by=just_added&search=lagos ``` ### Understanding Cinema Response Cinema experiences in the list response have `cinema: true` and always include a `cinema_info` object. The `cinema_info` object now includes three additional fields: `per_day_times`, `specific_dates`, and `days_with_times`. **Cinema Info Object** **Only present when `cinema` is `true`** | Field | Type | Description | | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `showing` | string | Frequency of movie showings: `"weekly"`, `"monthly"`, or `"daily"`. | | `shared_times` | boolean | `true` if showtimes are shared across all locations, `false` if each location has its own. | | `shared_tickets` | boolean | `true` if ticket types are shared across all locations, `false` if location-specific. | | `per_day_times` | boolean | `true` if the cinema has configured different showtimes per day. When `true`, `days_with_times` will be populated. | | `specific_dates` | array of strings | Only present for `showing: "daily"` cinemas. Lists exact screening dates in `"YYYY-MM-DD"` format. Empty for weekly and monthly. | | `times` | array | Showtime objects. Always populated for backward compatibility. | | `days_with_times` | array | Per-day showtime breakdown. Populated when `per_day_times` is `true`. Empty otherwise. | | `locations` | array | Array of cinema location objects. | **Note:** The list endpoint returns summary information. To get complete showtime details, use the movie's `id` with the [**Get Cinema Experience Details**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/cinema-ticketing-cinema-movies-available-days-purchase-etc/get-cinema-experience-details) endpoint. ### Building a Cinema Listings Page **JavaScript Example** ```javascript async function loadCinemaMovies() { const response = await fetch('/api/v1/merpi/experience?cinema=true&sorted_by=just_added'); const data = await response.json(); if (data.success) { const movies = data.data.experiences; movies.forEach(movie => { const info = movie.cinema_info; console.log(`${movie.title} - ${info.showing} showings`); if (info.per_day_times) { // days_with_times is populated - use it for per-day display const dayTimes = info.shared_times ? info.days_with_times : info.locations[0].days_with_times; console.log('Per-day schedule:', dayTimes); } if (info.showing === 'daily' && info.specific_dates.length) { console.log('Screening dates:', info.specific_dates); } }); } } ``` **Python Example** ```python import requests response = requests.get( 'https://api.syticks.com/api/v1/merpi/experience', params={'cinema': 'true', 'featured': 'true'} ) data = response.json() if data['success']: movies = data['data']['experiences'] for movie in movies: info = movie['cinema_info'] print(f"{movie['title']} at {movie['business']['name']}") print(f"Showing: {info['showing']}, Per-day times: {info['per_day_times']}") if info['showing'] == 'daily': print(f"Screening dates: {info['specific_dates']}") ``` ### Key Differences from Regular Experiences | Aspect | Cinema Experience | Regular Experience | | ---------------- | ----------------------------- | --------------------------- | | `cinema` value | `true` | `false` | | `cinema_info` | Present | Not present | | Duration | Recurring (days/weeks/months) | Fixed dates | | Detail needed | Showtimes via detail endpoint | Complete info in list | | Typical category | "Cinema" | "Parties", "Concerts", etc. | #### Next Steps After fetching the cinema list: 1. **Display movie cards** - Show title, poster, cinema name, and showing frequency 2. **Get showtimes** - Use the `id` from each movie to fetch complete showtime details via **Get Cinema Experience Details** 3. **Enable booking** - Direct users to select a showtime before booking tickets 4. **Filter by location** - Use `business` and `address` data to show nearby cinemas. You can pass the city or state in the `search` query parameter. ### Complete Documentation For comprehensive information including all available query parameters, complete response field descriptions, pagination details, and more examples, see the [**Get List of Experiences documentation.**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-list-of-experiences) #### Related Endpoints * [**Get List of Experiences**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-list-of-experiences) - Complete API reference covering both cinema and regular experiences * [**Get Cinema Experience Details**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/cinema-ticketing-cinema-movies-available-days-purchase-etc/get-cinema-experience-details) - Fetch complete movie details with showtimes * [**Get Regular Experience Details**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-experience-details) - For non-cinema events * [**Get Ticket Types**](https://sytickss-organization.gitbook.io/merpi-by-syticks/api-reference/experience-ticketing-events-parties-conference-comedy-and-more/get-ticket-categories-and-pricing) - Fetch ticket options for an experience