> 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

```
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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://syticks.gitbook.io/merpi-by-syticks/api-reference/cinema-ticketing-cinema-movies-available-days-purchase-etc/get-list-of-cinema-movies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.