Showtimes Finder Widget
The Showtimes Finder Widget is an embeddable iframe that displays cinema showtimes for a specific movie. It provides an interactive map and list view of nearby cinemas, allowing users to search for showtimes by location and date.
Quick Start
Add the following iframe to your HTML:
Code
Important: The allow="geolocation" attribute is required for the location-based search feature to work in the embedded widget.
Replace:
enwith your desired language code (enorde) in the URL pathYOUR_TOKENwith your authentication tokenMOVIE_IDwith the Cineamo movie ID (e.g.,699236)- All color values to match your website's branding
Live Example
Configuration
Required Parameters
| Parameter | Type | Description |
|---|---|---|
locale (in URL path) | string | Language code in URL path: /en/embedded or /de/embedded |
token | string | Authentication token for API access |
movie | string | Movie ID from Cineamo (e.g., 699236) |
Legacy Alphanumeric Movie ID deprecation
The movie parameter now expects a numeric Movie id (e.g. 699236). For backwards compatibility, the legacy alphanumeric cineamoId (e.g. 967941m) is still accepted, but is considered deprecated, and will be phased out, removing support after a grace period. For more information, see the release notes.
Style Customization
Customize the widget's appearance to match your website's branding:
| Parameter | Type | Description |
|---|---|---|
backgroundColor | HEX color | Background color (e.g., #111111) |
onBackgroundColor | HEX color | Text color on background (e.g., #FFFFFF) |
surfaceColor | HEX color | Surface/card color (e.g., #FFFFFF33) |
onSurfaceColor | HEX color | Text color on surface (e.g., #F2F2F2) |
primaryColor | HEX color | Primary action color (e.g., #24B9DC) |
onPrimaryColor | HEX color | Text color on primary (e.g., #000023) |
Note: When passing HEX colors in URLs, encode the # symbol as %23.
Date filter customization
| Parameter | Type | Description |
|---|---|---|
initiallySelectedDate | String, one of ['all', 'today', 'previews'] | Date filter that should be active by default. Omit it to let the release date decide: all while the movie is unreleased, today once it has released. previews requires the movie to have preview showings (see showPreviews); otherwise the widget falls back to all. |
showPreviews | Boolean (false) | The PREVIEWS tab, listing showings that take place before the movie's release date, is shown by default — pass false to suppress it. The tab only appears while the release date still lies ahead and the movie has such showings. Implied when initiallySelectedDate=previews. While the tab is available, the day buttons next to it start at the release date instead of today. |
fontSize | Number, one of [10, 12, 14] | Font size for the date-selector buttons |
Examples
Basic Implementation
Code
Custom Styling
Code
Features
Interactive Search
- Location-based search: Find cinemas near the user's current location
- Manual search: Search by city name or postal code
- Auto-complete: Suggestions while typing location
Date Filtering
- View showtimes for today or up to 7 days in advance — for an unreleased movie the 7 days start at its release date
- Easy date selection with horizontal date picker
- "All dates" option to see all available showtimes
- "Previews" tab for advance screenings before the movie's release date, shown by default (suppress with
showPreviews=false)
Cinema Information
Each cinema card displays:
- Cinema name and address
- Distance from selected location
- Available showtimes with direct booking links
- Cinema amenities and features
Security
CORS and Embedding
The widget is configured to be embedded on any domain. However:
- Authentication tokens are required for API access
- Tokens should be specific to your domain/application
- Contact support to obtain production tokens
Content Security Policy
If your website uses CSP headers, add the following directives:
Code
Best Practices
Height Considerations
- Minimum height: 500px recommended
- Mobile: Consider full viewport height (
100vh) - Desktop: 600-800px works well for most layouts
Performance
- The widget loads asynchronously and won't block your page
- Initial load includes map tiles (if enabled), consider loading indicators
- Widget caches cinema data for better performance
User Experience
- Place widget prominently on movie detail pages
- Consider adding a heading or context above the widget
- Ensure sufficient space for the map view on desktop
- Test on various screen sizes
Accessibility
- Always include a descriptive
titleattribute on the iframe - Ensure parent page has proper heading structure
- Consider adding skip links for keyboard navigation
Customization
Color Scheme Examples
Dark Mode
Code
Light Mode
Code
Cinema Branding Example
Code
Browser Compatibility
The widget supports:
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest & iOS Safari)
- Mobile browsers (iOS, Android)
Required Features
- ES6+ JavaScript support
- CSS Grid and Flexbox
- Geolocation API (optional, for location features)
Troubleshooting
Widget not loading
- Check the iframe
srcURL is correct - Verify your authentication token is valid
- Check browser console for CORS errors
- Ensure the movie ID exists in Cineamo database
- Ensure you specified all style color values
- Verify the
localeparameter is included - this is a required parameter
Geolocation not working
The location-based search requires the allow="geolocation" attribute on the iframe:
Code
Common issues:
- Missing
allowattribute: The iframe must explicitly allow geolocation access - HTTPS required: Geolocation only works on secure (HTTPS) websites
- Browser permissions: Users must grant location permission when prompted
- Fallback behavior: If geolocation fails, the widget automatically falls back to IP-based location
Browser Support:
- Chrome/Edge: Full support with
allow="geolocation" - Firefox: Full support with
allow="geolocation" - Safari: Full support with
allow="geolocation" - Mobile browsers: May require additional user interaction due to privacy restrictions
Missing or incorrect locale
If translations are not working or the widget shows errors:
- Ensure the
localeparameter is present in the URL - Verify the locale value is one of:
en,de, orfr - The widget does not auto-detect browser language - you must specify it explicitly
Map not displaying
- Map requires sufficient height (minimum 400px)
- Map only displays on desktop (>1024px width)
- Check for JavaScript errors in console
Colors not applying
- Ensure HEX colors use
%23instead of#in URLs - Verify all 6 color parameters are provided
- Check for URL encoding issues
API Integration
The widget uses the following Cineamo APIs:
- Showings API: Fetch showtimes for cinemas
- Cities API: Search and geocode locations
- Movies API: Validate movie availability
For direct API integration instead of the widget, see the API Reference.
Support
Getting Started
- Request an authentication token: support@cineamo.com
- Check movie availability via API or admin panel
- Test with the demo token on staging environment
Technical Support
- Email: support@cineamo.com
- Include: token (redacted), movie ID, and browser info
- Attach screenshots if experiencing visual issues
Feature Requests
Contact us to discuss custom features or white-label options.
Changelog
2026-07-01
-
The
movieparameter now expects a numeric Movieid(e.g.699236). For backwards compatibility, the legacy alphanumericcineamoId(e.g.967941m) is still accepted, but is considered deprecated, and will be phased out, removing support after a grace period. For more information, see the release notes.❌ OLD (deprecated, still accepted)
Code✅ NEW
Code
2025-12-11
-
The Iframe URL changed its structure related to locale configuration:
❌ OLD
Code✅ NEW
Code
2025-11-27
- Initial widget release
- Support for location-based search
- Date filtering
- Dual view modes (list/map)
- Full color customization