k-cinema-bridge

A JSON API providing Korean multiplex (Lotte Cinema, CGV, Megabox) box office and upcoming movie data, enriched with detailed information such as genre, director, and cast from KOBIS (Korean Film Council). Data is automatically refreshed daily at 00:00 UTC.

API Reference

• Base URL: https://uyeong.github.io/k-cinema-bridge
• All endpoints are accessible via GET requests without authentication.
• The info field may be null, so always perform a null check before accessing it.

Endpoint	Description
GET /api/boxoffice.json	Combined box office from all sources ({lotte, cgv, megabox})
GET /api/boxoffice/{source}.json	Box office by source (BoxOfficeMovie[])
GET /api/upcoming.json	Combined upcoming movies from all sources ({lotte, cgv, megabox})
GET /api/upcoming/{source}.json	Upcoming movies by source (UpcomingMovie[])

Valid source values: lotte, cgv, megabox

Data Models

BoxOfficeMovie

source: "lotte" | "cgv" | "megabox"
rank: number          -- Box office rank (starting from 1)
title: string         -- Movie title
rating: string        -- Audience rating
posterUrl: string     -- Poster image URL
info?: MovieInfo      -- KOBIS detailed info (may be null)

UpcomingMovie

source: "lotte" | "cgv" | "megabox"
title: string         -- Movie title
rating: string        -- Audience rating
posterUrl: string     -- Poster image URL
releaseDate: string   -- Release date (YYYY-MM-DD, may be an empty string)
info?: MovieInfo      -- KOBIS detailed info (may be null)

MovieInfo

code, title, englishTitle, originalTitle: string
runtime: string (minutes)
productionYear, openDate (YYYYMMDD), productionStatus, type: string
nations: string[]     -- Production countries
genres: string[]
directors: {name, englishName}[]
actors: {name, englishName, role, roleEnglish}[]
showTypes: {group, name}[]
companies: {code, name, englishName, part}[]
audits: {number, grade}[]
staff: {name, englishName, role}[]

Instructions

Recommending Popular Movies

When the user asks for movie recommendations or what's popular:

1. Fetch GET {BASE_URL}/api/boxoffice.json to retrieve combined box office data from all sources.
2. Identify movies that appear across multiple sources with low rank values — lower rank means higher popularity.
3. Present the top-ranked movies with their title, rating, and genre from info.genres if available.

Announcing Upcoming Releases

When the user asks about upcoming or soon-to-be-released movies:

1. Fetch GET {BASE_URL}/api/upcoming.json to retrieve combined upcoming movie data.
2. Filter results by releaseDate (YYYY-MM-DD) to match the user's requested time range.
3. Provide details such as genre, directors, and actors from the info field if available.

Searching by Genre, Director, or Actor

When the user asks about a specific genre, director, or actor:

1. Fetch both GET {BASE_URL}/api/boxoffice.json and GET {BASE_URL}/api/upcoming.json.
2. Filter results using the info field:
   • Genre: match against info.genres
   • Director: match against info.directors[].name
   • Actor: match against info.actors[].name
3. Always null-check the info field before accessing nested properties.

Filtering by Audience Rating

When the user asks for age-appropriate movies:

1. Use the rating field to filter. This field is always present and does not require the info field.
2. Known rating values: "전체 관람가" (All ages), "12세 관람가" (12+), "15세 관람가" (15+), "청소년 관람불가" (Adults only).

Querying a Specific Multiplex

When the user asks about a specific cinema chain:

1. Fetch GET {BASE_URL}/api/boxoffice/{source}.json or GET {BASE_URL}/api/upcoming/{source}.json.
2. Valid source values: lotte, cgv, megabox.

Comparing Across Multiplexes

When the user asks to compare rankings between cinema chains:

1. Fetch GET {BASE_URL}/api/boxoffice.json to retrieve combined data.
2. Find movies with the same title across different sources and compare their rank values.

Response Guidelines

• Respond in the same language the user is using.
• When presenting movie lists, include title, rank or release date, rating, and genre when available.
• If info is null for a movie, present only the base fields (title, rank, rating, posterUrl) without guessing missing details.
• When comparing across multiplexes, use a table format for clarity.