ComingSoon APIcomingsoon.it ↗
Access Italian movie showtimes, theater locations, box office rankings, and film metadata across Italy via the ComingSoon.it API. 8 endpoints.
What is the ComingSoon API?
The ComingSoon.it API provides 8 endpoints covering Italian cinema listings, including now-playing films by city, per-theater showtimes, box office rankings, and full movie metadata. The get_showtimes_for_movie_in_city endpoint returns screening schedules and hall details for a specific film across multiple theaters in one request, and get_box_office_italy surfaces weekend gross, total gross, screen count, and weeks in release for current chart entries.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/bcb56aee-e6e5-4a60-9815-1f4e7fb5eb8e/get_cities_list' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace comingsoon-it-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: ComingSoon.it Cinema API — browse Italian cinema listings, showtimes, and box office."""
from parse_apis.ComingSoon_it_Cinema_API import ComingSoon, Sort, CitySlug, MovieNotFound
client = ComingSoon()
# Browse current box office rankings
for ranking in client.rankings.list(limit=5):
print(ranking.rank, ranking.movie.title, ranking.weekend_gross)
# List movies now playing sorted by theater count, drill into details
movie_summary = client.movie_summaries.list(sort=Sort.THEATERS, limit=1).first()
if movie_summary:
detail = movie_summary.details()
print(detail.name, detail.genre, detail.date_published)
# Construct a city and list its movies + theaters
roma = client.city(slug="roma")
for city_movie in roma.movies.list(limit=3):
print(city_movie.title, city_movie.id)
# Get theater details
theater = roma.theaters.list(limit=1).first()
if theater:
try:
full = theater.details(city_slug=CitySlug.ROMA)
print(full.name, full.geo.latitude, full.geo.longitude)
except MovieNotFound as exc:
print(f"Theater not found: {exc}")
# Get showtimes for the first movie in Roma
first_movie = roma.movies.list(limit=1).first()
if first_movie:
for showtime in first_movie.showtimes(city_slug=CitySlug.ROMA, limit=2):
print(showtime.theater_name, showtime.address)
print("exercised: rankings.list / movie_summaries.list / details / city.movies.list / city.theaters.list / theater.details / showtimes")
Returns all Italian cities and provinces that have cinemas listed on ComingSoon.it. Each city includes its slug for use in other endpoints. Movie counts may be null.
No input parameters required.
{
"type": "object",
"fields": {
"cities": "array of city objects with name, slug, url, and movie_count"
},
"sample": {
"data": {
"cities": [
{
"url": "https://www.comingsoon.it/cinema/roma/",
"name": "Roma",
"slug": "roma",
"movie_count": null
},
{
"url": "https://www.comingsoon.it/cinema/milano/",
"name": "Milano",
"slug": "milano",
"movie_count": null
}
]
},
"status": "success"
}
}About the ComingSoon API
Movie and Showtime Data
The API exposes Italian cinema listings through a city-first lookup pattern. Start with get_cities_list to retrieve every city and province slug (e.g. roma, milano, torino). Pass a city_slug to get_movies_in_city for all films currently screening there — each result includes a city-specific idf identifier. Feed that movie_id and city_slug into get_showtimes_for_movie_in_city to get an array of theaters, each with a screenings list containing hall names and schedule/price details.
Theater and Film Metadata
get_theaters_in_city returns all cinemas in a city with id, slug, name, address, and url. Pass all three identifiers (city_slug, theater_id, theater_slug) to get_theater_details for a complete profile: geo coordinates (latitude/longitude), a full PostalAddress, aggregateRating, and a films_now_showing array with per-film poster URLs and showtimes. For film-level detail, get_movie_details accepts a movie_id and movie_slug from get_movies_now_playing or get_box_office_italy and returns cast (actor array with sameAs URLs), director, description, genre, aggregateRating, a trailer VideoObject with embed URL, datePublished, and an extended_metadata object.
Now Playing and Box Office
get_movies_now_playing is paginated (1-based page parameter) and accepts a sort parameter to order by number of theaters or audience rating. It returns id, slug, title, genre, year, release_date, director, and poster per film. get_box_office_italy requires no parameters and returns the current Italian weekend chart ordered by performance, with weekend_gross, total_gross, screens, and weeks (weeks in release) per entry.
The ComingSoon API is a managed, monitored endpoint for comingsoon.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when comingsoon.it changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official comingsoon.it API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a cinema finder app that maps theaters in any Italian city using geo coordinates from
get_theater_details. - Aggregate weekend box office trends for Italian releases using
weekend_grossandtotal_grossfromget_box_office_italy. - Show a user every screening time and ticket-price tier for a chosen film in Rome or Milan via
get_showtimes_for_movie_in_city. - Populate a movie database with Italian release dates, cast lists, and trailer embed URLs from
get_movie_details. - Compare how many screens a film is playing across Italy by combining
get_box_office_italyscreen counts with city-level data. - Display theater ratings and currently showing films for any cinema using
aggregateRatingandfilms_now_showingfromget_theater_details. - Build a sorted now-playing index ranked by audience rating using the
sortparameter inget_movies_now_playing.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does ComingSoon.it offer an official developer API?+
What does `get_showtimes_for_movie_in_city` return, and how is `movie_id` obtained?+
theater_name, address, theater_url, and a screenings array containing hall names and schedule/price details. The required movie_id is the city-specific idf value returned by get_movies_in_city — it is not the same numeric ID used by get_movie_details, which comes from get_movies_now_playing or get_box_office_italy.Does `movie_count` always appear on cities returned by `get_cities_list`?+
movie_count field for a city may be null. The slug is always present and usable in downstream endpoints regardless.Does the API cover historical box office data or past showtimes?+
get_box_office_italy and films presently showing in cinemas via get_movies_now_playing and get_showtimes_for_movie_in_city. You can fork the API on Parse and revise it to add an endpoint targeting historical chart archives or past screening data.Are user reviews or written critic reviews available for movies or theaters?+
aggregateRating objects (numeric rating value and count) for both movies and theaters, but individual review text is not exposed. You can fork the API on Parse and revise it to add an endpoint that fetches the reviews listing for a movie or theater.