HK Cinema Now Playing

APIs

TMDB (Movie List)

GET https://api.themoviedb.org/3/movie/now-playing?region=HK&language=zh-HK

• Authorization: Bearer ${TMDB_API_KEY}

• accept: application/json

International Showtimes (Direct API - Recommended)

GET https://api.internationalshowtimes.com/v5/showtimes?movie_id={tmdb_id}&countries=HK

• X-API-Key: ${IS_API_KEY}

• OR

  Authorization: Token token=${IS_API_KEY}

countries=HK

RapidAPI Wrapper (Legacy - often broken)

GET https://international-showtimes.p.rapidapi.com/v5/movies/{tmdb_id}/showtimes?countries=HK

• X-RapidAPI-Key: ${RAPIDAPI_KEY}

• X-RapidAPI-Host: international-showtimes.p.rapidapi.com

Cinema Chain Booking URLs (fallback when API doesn't provide booking_link)

Display Rules

Step 1: List Movies

• Call TMDB:

  GET /movie/now-playing?region=HK&language=zh-HK

• Cache movie list with TMDB IDs
• Show numbered list (Chinese title + English title from

  title

  and

  original_title

  fields)

香港上映中:

1. [電影中文名] ([英文名])
2. [電影中文名] ([英文名])
3. [電影中文名] ([英文名])
...

Step 2: Movie Details (Brief)

1. Get TMDB movie ID from cached list
2. Call TMDB:

   GET /movie/{id}?language=zh-HK

   for title + overview
3. Call IS:

   GET /v5/showtimes?movie_id={tmdb_id}&countries=HK

4. Extract unique cinemas (from

   showtimes[].cinema.name

   )
5. Extract unique dates (from

   showtimes[].start_at

   , format as "3月14日")

[TITLE]

簡介: [overview]

上映戲院:
- [Cinema 1]
- [Cinema 2]
- ...

上映日期:
- [Date 1]
- [Date 2]
- ...

Step 3: Filtered Showtimes

1. Parse user input to identify:
   • Cinema name (match against available cinemas)
   • Date (parse relative dates: "今日", "聽日", "後日", or specific date)
2. Filter showtimes:
   • If cinema specified: show only that cinema's showtimes
   • If date specified: show only that date's showtimes
   • If both: apply both filters
3. For each date, list all available times

[Cinema Name] - [Movie Title]

[Date 1]: [Time 1] | [Time 2] | [Time 3]
[Date 2]: [Time 1] | [Time 2]
...

購票: [booking_link]

Step 4: Book Tickets

1. Extract cinema + date + time from user message
2. Find matching showtime from cached data
3. Use

   booking_link

   from API response
4. Open booking URL in browser

🎫 [Cinema Name] - [Date] [Time]

[booking_link]

[Open in browser]

Response Parsing

/movie/now-playing

• results[]

  : Array of movies

  • id

    : TMDB movie ID

  • title

    : Chinese title (zh-HK)

  • original_title

    : Original/English title

/movie/{id}

• title

  : Chinese title

• overview

  : Chinese synopsis

/movies/{tmdb_id}/showtimes

• showtimes[]

  : Array of showtimes

  • cinema.id

    : Cinema ID

  • cinema.name

    : Cinema name (e.g., "MCL Cinemas", "百老匯")

  • start_at

    : ISO datetime (e.g., "2024-03-15T19:30:00+08:00")

  • booking_link

    : Direct ticket URL

  • movie_id

    : TMDB movie ID

Date Parsing (Cantonese/Chinese)

• "今日" = today
• "聽日" = tomorrow
• "後日" = day after tomorrow
• "尋日" = yesterday
• Or parse "3月15日" format

Cinema Name Matching

• "MCL" → "MCL Cinemas"
• "百老匯" → "Broadway Circuit"
• " Cinema City" → "Cinema City"

Error Handling

• If TMDB fails: "無法取得電影資料，請再試一次。"
• If no showtimes: "暫時未有呢套戲既場次資料。"
• If API errors: Show available data, note "部分場次資料可能不完整。"