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 page.

Important: Cinema movies use the same endpoint as regular experiences. This page focuses on cinema-specific usage, but the complete API reference is available in the Get List of Experiences documentation.

Cinema-Specific Usage

To retrieve only cinema experiences (movies), add the cinema=true parameter to the experiences endpoint:

GET /api/v1/merpi/experience?cinema=true HTTP/1.1
Accept: application/json

Common Cinema Queries

Get all cinema movies

GET /api/v1/merpi/experience?cinema=true

Get featured movies

GET /api/v1/merpi/experience?cinema=true&featured=true

Search for a specific movie

GET /api/v1/merpi/experience?cinema=true&search=batman

Get movies by cinema business

GET /api/v1/merpi/experience?cinema=true&business_id=764c6a94-7bda-448e-a8af-35a5bb536d4

Get recently added movies

GET /api/v1/merpi/experience?cinema=true&sorted_by=just_added

Combine filters

GET /api/v1/merpi/experience?cinema=true&featured=true&sorted_by=just_added&search=ikeja

Understanding Cinema Response

Cinema experiences in the list response include the cinema field set to true and must include a cinema_info object:

{
  "success": true,
  "status": 200,
  "message": "List of Experiences",
  "data": {
    "experiences": [
      {
        "id": "561e3a64-9e9e-47c0-bb6a-87e6ee6e2ead",
        "title": "Avatar: The Way of Water",
        "end_date": "2024-02-29T00:00:00Z",
        "description": "Experience the epic continuation...",
        "featured": true,
        "cinema": true,
        "cinema_info": {
          "showing": "weekly"
        },
        "address": {
          "street": "Admiralty Way",
          "town": "Lekki Phase 1",
          "city": "Lagos",
          "country": "Nigeria"
        },
        "business": {
          "id": "a91f8c3e-2b4d-4f9a-8c6e-1d5a7b9c3e2f",
          "name": "Silverbird Cinemas",
          "slug": "silverbird-cinemas",
          "type": "cinema"
        },
        "category": {
          "id": "56195f78-a14b-4dc2-b1b8-c3aa62a23f70",
          "slug": "cinema",
          "name": "Cinema"
        }
      }
    ],
    "next_page": "2",
    "count": 45,
    "per_page": 20
  }
}

Cinema-Specific Fields

When cinema: true, the response includes:

Field	Description
cinema	Always true for cinema experiences
cinema_info	Object containing showing frequency (e.g., "weekly", "monthly")
cinema_info.showing	How often the movie is shown

Note: The list endpoint returns summary information only. To get complete showtime details including specific screening times, use the movie's id with the Get Cinema Experience Details endpoint.

Building a Cinema Listings Page

JavaScript Example

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 => {
      // Each movie has cinema: true
      console.log(`${movie.title} - ${movie.cinema_info.showing} showings`);
      
      // To get full showtimes, fetch individual movie details
      fetchMovieShowtimes(movie.id);
    });
  }
}

Python Example

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:
        print(f"{movie['title']} at {movie['business']['name']}")
        print(f"Showing: {movie['cinema_info']['showing']}")

Key Differences from Regular Experiences

Aspect	Cinema Experience	Regular Experience
cinema value	true	false
cinema_info	Present	Not present
Duration	Recurring (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 showtimes 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

• Error handling

• More examples

See the Get List of Experiences documentation.

Related Endpoints

• Get List of Experiences - Complete API reference (covers both cinema and regular experiences)

• Get Cinema Experience Details - Fetch complete movie details with showtimes

• Get Regular Experience Details - For non-cinema events

• Get Ticket Types - Fetch ticket options for an experience