Ad campaigns and impression/click tracking.
Campaign breakdown by platform, device and placement
Returns one advertisement's impressions, clicks and purchase intents split three ways: by platform (client), by device type, and by placement. The totals come from the exact counters on the advertisement; the platform and device splits are grouped from the ad event tables and include an unknown bucket so they always add up to the total. Purchase intents are grouped from the ad clicks they are attributed to (ADR 0012), which is also the placement card's only source for that one column. These are ad-counter events, not Pulse interest events — the figures are not comparable with a tracked-visitor count.
query Parameters
advertisementIdCampaign breakdown by platform, device and placement › Responses
The campaign breakdown. Zeroed with empty splits when the advertisement does not exist.
totalsThe campaign's exact lifetime impressions and clicks, read from the counters on the advertisement itself rather than recomputed from the event rows. No purchase-intent figure: the campaign's own is carried by the advertisement list's metricPurchaseIntentCount embed, and two independently cached answers to one question end up disagreeing on screen.
Impressions, clicks and purchase intents per platform (client). Every known platform is present even at zero, plus an unknown bucket for rows that carry no platform, so the split always adds up to the total.
Impressions, clicks and purchase intents per device type, same shape and same unknown bucket as platform.
Per placement. The impressions and clicks come from the exact per-placement counters on the advertisement; the purchase intents have no counter and are grouped from the ad clicks they are attributed to (ADR 0016). An unsplit row appears only when the campaign has a remainder from before placements were counted separately — including a remainder of intents alone.
Campaign performance per cinema
Returns the impressions, clicks, click rate and device shares of one or more advertisements, grouped by cinema. One row per cinema regardless of how many advertisements are asked for: a cinema that ran two of them appears once, carrying both, and the click rate and device shares are recomputed from the summed counts rather than averaged across advertisements. Paginated, because a chain campaign books hundreds of houses. A cinema with clicks but no impressions is included (with a null rate), and events that are not attributed to any cinema are returned as a single row with a null cinemaId, so the rows always add up to the requested total.
query Parameters
advertisementIdsThe advertisements to report on, summed into one row per cinema. Required: a single advertisement is the one-element case.
pageperPageCapped at 100.
sortorderCampaign performance per cinema › Responses
One page of per-cinema rows plus the unpaginated total.
Advertisement campaigns rolled up per film
Returns one row per film, aggregating that film's advertisement campaigns: how many campaigns, how many distinct cinemas accepted them, total impressions and clicks, the resulting click rate, and every campaign status present. Cinemas are counted once across the film rather than summed per campaign. External advertisements have no film and are therefore absent.
query Parameters
pageperPageCapped at 100.
sortorderqueryFree-text search over the film title and its content title.
movieIdsNumeric Movie Ids — restricts the roll-up to those films.
Advertisement campaigns rolled up per film › Responses
One page of per-film rows plus the unpaginated total.
Create an ad click
Creates an AdClick. It returns the AdClick object.
Create an ad click › Request Body
variantAdVariant id this click is attributed to (A/B testing). Must belong to the addressed advertisement.
idreferrerPageclientipAddressdeviceTypeuidCreate an ad click › Responses
AdClick creation was scheduled
Create an ad impression
Creates an AdImpression. It returns the AdImpression object.
Create an ad impression › Request Body
variantAdVariant id this impression is attributed to (A/B testing). Must belong to the addressed advertisement.
idreferrerPageclientipAddressdeviceTypeuidCreate an ad impression › Responses
AdImpression creation was scheduled
List advertisements
Returns a list of Advertisement objects.
query Parameters
pageperPagesortorderquerycinemaIdsdistributorIdsmovieIdsNumeric Movie Ids — returns only the advertisements booked for those films.
startDatetimeendDatetimeplacementstatusesadCategoriesembedList advertisements › Responses
Advertisement list
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountCreate an advertisement
Creates an Advertisement. It returns the Advertisement object. tenantIds is required and must contain at least one tenant id -- every advertisement must be reachable by at least one tenant (the main Cineamo platform is itself a tenant).
Create an advertisement › Request Body
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountCreate an advertisement › Responses
Advertisement was created
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountGet an advertisement
Returns an Advertisement object by its Id.
path Parameters
advertisementIdGet an advertisement › Responses
Advertisement details
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountUpdate an advertisement
Updates an Advertisement. It returns the updated Advertisement object.
path Parameters
advertisementIdUpdate an advertisement › Request Body
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountUpdate an advertisement › Responses
Advertisement was updated
idadCategoryadvertiserNameadvertiserImageRefadvertiserImageUrltenantIdsstartDatetimeendDatetimecinemaIdsclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementimpressionCountimpressionCountTopBannerimpressionCountLayerimpressionThresholdclickCountclickCountTopBannerclickCountLayercostPer1kImpressionsmaxBudgetdailyMaxBudgetdailyImpressionThresholdimpressionCountTodaystatusdisplayLocationsmetricCinemasTotalCountmetricCinemasDeclinedCountmetricCinemasAcceptedCountmetricPurchaseIntentCountGet an advertisement to display
Suggests an Advertisement to display.
query Parameters
placementsPlacements the caller can render (e.g. layer, top_banner).
displayLocationsChannels the caller renders in (e.g. web, cinema_website).
cinemaIdCinema to target; omit for platform/app ads not bound to a cinema.
visitorIdStable per-visitor id (first-party, persisted client-side). Drives deterministic A/B variant assignment; omitted -> random variant.
tenantIdRequesting tenant (white-label platform); omitted -> the main Cineamo platform, which is resolved to its own tenant.
embedGet an advertisement to display › Responses
Advertisement details
idadCategoryadvertiserNameadvertiserImageUrlvariantIdstartDatetimeendDatetimeclickThroughUrltopBannerImageReftopBannerImageUrltopBannerDesktopImageReftopBannerDesktopImageUrllayerImageReflayerImageUrlplacementstatusdisplayLocations