Get List of Experiences

This endpoint returns list of experiences and it also includes cinema movies. You'll notice that they type differentiates normal events from cinema movies as cinema movies have 'cinema' as the type.

GET /api/v1/merpi/experience

This endpoint returns a paginated list of experiences available on the platform. Experiences include both regular events (concerts, parties, shows, etc.) and cinema movies. The cinema field differentiates between these two types:

• Regular experiences: One-time or limited-duration events with specific start and end dates

• Cinema experiences: Recurring movie showings that repeat over extended periods

Retrieve Available Experiences

get

Fetch a list of available experiences with optional filtering, searching, and sorting parameters.

Query parameters

business_idintegerOptional

Filter experiences by a specific business ID.

searchstringOptional

Search for experiences by keywords in title, description, etc.

category_idstringOptional

Filter by a specific category ID.

sorted_bystring · enumOptional

Sort experiences based on different criteria. Allowed values include:

• just_added: Sort by experiences recently added.
• upcoming: Sort by experiences with future dates.
• randomly: Sort experiences in a random order.

Possible values:

featuredbooleanOptional

Filter by experiences flagged as featured.

cinemabooleanOptional

Filter by experience type:

• true: Returns only cinema experiences (movies)
• false: Returns only regular experiences (events)
• Not provided: Returns all experiences (default behavior)

pageinteger · min: 1Optional

Page number for pagination. Starts at 1.

Default: 1

Responses

200

Successfully retrieved experiences

application/json

successbooleanOptional

Indicates whether the request was successful.

statusintegerOptional

HTTP status code representing the response status.

messagestringOptional

Human-readable description of the response.

400

Bad Request - Invalid query parameters

application/json

404

Not Found - Specified resource doesn't exist

application/json

500

Internal Server Error

application/json

get

/api/v1/merpi/experience

HTTPcURLJavaScriptPython

GET /api/v1/merpi/experience HTTP/1.1
Accept: */*

{
  "success": true,
  "status": 200,
  "message": "List of Experiences",
  "data": {
    "experiences": [
      {
        "id": "223f279b-28b2-4b72-8020-cfc2c02b95cb",
        "title": "Easter In Sana Forex",
        "end_date": "2023-01-29T04:41:00Z",
        "description": "Join us for an unforgettable Easter celebration...",
        "featured": false,
        "cinema": false,
        "address": {
          "street": "12 Main Street",
          "town": "Victoria Island",
          "city": "Lagos",
          "country": "Nigeria"
        },
        "image": [
          {
            "image": "https://syticks.com/storage/experiences/easter-event.jpg"
          }
        ],
        "business": {
          "id": "764c6a94-7bda-448e-a8af-35a5bb536d4",
          "name": "Party Hard Entertainment",
          "photo": "https://syticks.com/storage/businesses/PXpF7oIUjV1waH0rLUXFU4ssWg4NYzq1vT6GqHn7.jpg",
          "slug": "party-hard-entertainment",
          "type": "entertainment"
        },
        "category": {
          "id": "5d4ccb2c-09ff-43a4-b96e-a2a035b4226b",
          "slug": "parties",
          "name": "Parties"
        },
        "created_on": "2023-01-28T15:42:11Z"
      },
      {
        "id": "561e3a64-9e9e-47c0-bb6a-87e6ee6e2ead",
        "title": "Avatar: The Way of Water",
        "end_date": "2024-02-29T00:00:00Z",
        "description": "Experience the epic continuation of the Avatar saga...",
        "featured": false,
        "cinema": true,
        "cinema_info": {
          "showing": "weekly"
        },
        "address": {
          "street": "Admiralty Way",
          "town": "Lekki Phase 1",
          "city": "Lagos",
          "country": "Nigeria"
        },
        "image": [
          {
            "image": "https://syticks.com/storage/cinema/avatar-poster.png"
          }
        ],
        "business": {
          "id": "764c6a94-7bda-448e-a8af-35a5bb536d4",
          "name": "Silverbird Cinemas",
          "photo": "https://syticks.com/storage/businesses/silverbird-logo.jpg",
          "slug": "silverbird-cinemas",
          "type": "cinema"
        },
        "category": {
          "id": "56195f78-a14b-4dc2-b1b8-c3aa62a23f70",
          "slug": "cinema",
          "name": "Cinema"
        },
        "created_on": "2024-02-28T01:16:34Z"
      }
    ],
    "next_page": "2",
    "count": 45,
    "per_page": 20
  }
}

Make sure that you use the end_date to prevent your customers from purchasing tickets that have ended.

Query Parameters

Parameter	Type	Required	Description
business_id	integer	No	Filter experiences by a specific business ID. Returns only experiences created by the specified business.
search	string	No	Search for experiences by keywords in title, description, or other text fields.
category_id	string	No	Filter experiences by a specific category ID (e.g., parties, cinema, concerts).
sorted_by	string (enum)	No	Sort experiences based on different criteria: • just_added - Recently added experiences • upcoming - Experiences with future dates • randomly - Random order Possible values: just_added, upcoming, randomly
featured	boolean	No	Filter by featured status. When true, returns only experiences flagged as featured.
cinema	boolean	No	Filter by experience type: • true - Returns only cinema experiences (movies) • false - Returns only regular experiences (events) • Not provided - Returns all experiences (default behavior)

Response Fields

Root Response Object

Field	Type	Description
success	boolean	Indicates whether the request was successful.
status	integer	HTTP status code (200 for successful requests).
message	string	Human-readable description of the response.
data	object	Container object holding the response data.

Data Object

Field	Type	Description
experiences	array	Array of experience objects matching the query criteria.
next_page	string	The page number for the next set of results. null if on the last page.
count	integer	Total number of experiences matching the query.
per_page	integer	Number of experiences returned per page (default: 20).

Experience Object

Field	Type	Description
id	string (UUID)	Unique identifier for the experience.
title	string	Name/title of the experience.
end_date	string (ISO 8601)	End date and time of the experience in UTC format.
description	string	Detailed description of the experience.
featured	boolean	Indicates if the experience is featured on the platform.
cinema	boolean	Differentiates experience types: • true - Cinema experience (recurring movie) • false - Regular experience (one-time or limited event)
cinema_info	object	Only present when cinema is true. Contains cinema-specific information.
address	object	Location details for the experience.
image	array	Array of image objects associated with the experience.
business	object	Information about the business hosting the experience.
category	object	Category classification of the experience.
created_on	string (ISO 8601)	Timestamp when the experience was created.

Cinema Info Object

Only present when cinema is true

Field	Type	Description
showing	string	Frequency of movie showings (e.g., "weekly", "monthly").

Address Object

Field	Type	Description
street	string	Street address of the venue.
town	string	Town or locality.
city	string	City where the experience takes place.
country	string	Country (typically "Nigeria").

Image Object

Field	Type	Description
image	string (URL)	Full URL to the experience image.

Business Object

Field	Type	Description
id	string (UUID)	Unique identifier for the business.
name	string	Business name.
photo	string (URL)	URL to the business profile photo.
slug	string	URL-friendly identifier for the business.
type	string	Type of business (e.g., "entertainment", "cinema").

Category Object

Field	Type	Description
id	string (UUID)	Unique identifier for the category.
slug	string	URL-friendly identifier for the category.
name	string	Display name of the category (e.g., "Parties", "Cinema").

Example Requests

Get all experiences

GET /api/v1/merpi/experience HTTP/1.1
Accept: application/json

Get only cinema experiences

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

Get only regular experiences

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

Get featured cinema experiences

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

Search cinema experiences

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

Understanding Experience Types

Experiences on the Merpi platform fall into two categories:

Regular Experiences (cinema: false)

• One-time or limited-duration events

• Have specific start and end dates

• Examples: concerts, parties, festivals, shows

• Event concludes after the end date

Cinema Experiences (cinema: true)

• Recurring movie showings

• Repeat over extended periods (weeks or months)

• Include cinema_info object with showing frequency

• Examples: weekly movie screenings, daily showings

• Continue showing until the cinema removes them

The cinema boolean field is the definitive indicator of experience type. Use this field to differentiate between regular events and cinema movies in your application logic.

NOTE: Experiences are of two types. Normal experiences that start on a particular date and ends. It could last for just 1 day, or 2 or more. Point is that for normal experiences, it ends and is not recurring. The other kind of experience is the Cinema Experience which is recurring(this means that it repeats over a period of time).

For example, a movie can show on Thursday, Saturday and Sunday every week for the next 4 months or more depending on how long the cinema wants to keep showing it.

The 'cinema' field is what differentiates these experiences. When false, it is a normal experience but if true, it is a cinema experience. So, it is important that you use this field to differentiate them.