Constructor Retail Media Display Ads API
Display-ads surface returning ads for each requested placement, with banner and multi-banner placement responses ordered by auction rank.
OpenAPI Specification
openapi: 3.1.0
info:
title: Retail Media - Display Ads
contact:
email: support@constructor.io
version: 1.0.0
servers:
- url: https://display.media-cnstrc.com
paths:
/v1/display-ads:
get:
tags:
- Display Ads
summary: Retrieve Display Ads (Deprecated)
description: Retrieves an ad for each of the given placement IDs. If no ad is available for a placement ID, the placement ID will be missing from the response.
operationId: v1-display-ads-retrieve-display-ads
deprecated: true
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: placement_ids
in: query
required: true
schema:
type: array
items:
type: string
maxItems: 20
title: Placement IDs
description: List of placement IDs.
examples:
- - home_page
- mobile_search_results
description: List of placement IDs.
- name: query
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search query for keyword targeting.
examples:
- apple
title: Query
description: Search query for keyword targeting.
- name: filter_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The name of the related browse filter.
examples:
- group_id
- collection_id
- color
title: Filter Name
description: The name of the related browse filter.
- name: filter_value
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The value of the related browse filter.
examples:
- '123'
title: Filter Value
description: The value of the related browse filter.
responses:
'200':
description: Successful Response.
content:
application/json:
schema:
$ref: '#/components/schemas/DisplayAdsResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicErrorResponse'
security: []
servers:
- url: https://display.media-cnstrc.com
/v2/display-ads:
get:
tags:
- Display Ads
summary: Retrieve Display Ads
description: Retrieves ads for each of the given placements. Each placement maps to a typed response object. Banner placements return a single flattened ad; multi-banner placements return an array of ads ordered by auction rank. If no ad is available for a placement, the placement will be missing from the response. Placements are specified as repeated `placements` query parameters. Optionally, `num_results[{id}]=N` can be used to request a specific number of ads for a placement. When omitted, the placement's configured maximum is used.
operationId: v2-display-ads-retrieve-display-ads
parameters:
- name: key
in: query
required: true
schema:
type: string
description: The key of the index to use.
title: Key
description: The key of the index to use.
- name: query
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Search query for keyword targeting.
examples:
- apple
title: Query
description: Search query for keyword targeting.
- name: filter_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The name of the related browse filter.
examples:
- group_id
- collection_id
- color
title: Filter Name
description: The name of the related browse filter.
- name: filter_value
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The value of the related browse filter.
examples:
- '123'
title: Filter Value
description: The value of the related browse filter.
- name: num_results
in: query
description: 'Optional deepObject parameter to request a specific number of ads for each placement. Example: num_results[home_page]=3&num_results[carousel]=1. When omitted, the placement''s configured maximum is used.'
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties:
type: integer
minimum: 1
maximum: 20
- name: placements
in: query
required: true
schema:
type: array
items:
type: string
minItems: 1
maxItems: 20
description: Placement customer IDs to fetch ads for.
examples:
- - home_page
- carousel
title: Placements
description: Placement customer IDs to fetch ads for.
responses:
'200':
description: Successful Response.
content:
application/json:
schema:
$ref: '#/components/schemas/DisplayAdsV2Response'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicErrorResponse'
security: []
servers:
- url: https://display.media-cnstrc.com
components:
schemas:
BannerPlacementResponse:
properties:
type:
type: string
const: image_banner
title: Type
description: Ad type discriminator.
banner_ad_id:
type: string
title: Banner Ad ID
description: Unique identifier of this ad instance for tracking purposes.
advertiser:
type: string
title: Advertiser
description: Name of the advertiser for compliance and disclosure purposes.
target_url:
type: string
title: Target URL
description: Target URL of the ad.
title:
type: string
title: Title
description: Plain text title of the ad.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Optional plain text description of the ad.
cta:
anyOf:
- type: string
- type: 'null'
title: CTA
description: Optional call-to-action for the ad.
cta_label:
anyOf:
- type: string
- type: 'null'
title: CTA Label
description: Optional aria-label for the call-to-action button.
srcset:
items:
$ref: '#/components/schemas/SrcWithPixelDensity'
type: array
title: Srcset
description: Main set of images for the ad with their corresponding pixel densities.
images:
items:
$ref: '#/components/schemas/ImageOverride'
type: array
title: Images
description: Optional list of alternative images for different media conditions.
custom_fields:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Custom Fields
description: Custom key-value fields associated with the creative.
type: object
required:
- type
- banner_ad_id
- advertiser
- target_url
- title
- description
- cta
- srcset
- images
title: BannerPlacementResponse
DisplayAd:
properties:
banner_ad_id:
type: string
title: Banner Ad ID
description: Unique identifier of this ad instance for tracking purposes.
advertiser:
type: string
title: Advertiser
description: Name of the advertiser for compliance and disclosure purposes.
image_banner:
anyOf:
- $ref: '#/components/schemas/ImageBanner'
- type: 'null'
description: Image banner to show on the ad - must be checked if it's present before rendering it.
custom_fields:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Custom Fields
description: Custom key-value fields associated with the creative.
type: object
required:
- banner_ad_id
- advertiser
- image_banner
title: DisplayAd
DisplayAdsResponse:
properties:
display_ads:
additionalProperties:
$ref: '#/components/schemas/DisplayAd'
type: object
title: Display Ads
description: Map of placement IDs to Display Ads. If a placement ID is missing it means that there are no available ads for that placement.
examples:
- home_page:
advertiser: Advertiser Name
banner_ad_id: AD_ID
image_banner:
cta: Ad CTA
cta_label: Call to action label
description: Ad Description
images:
- media: '(min-width: 1024px)'
srcset:
- alt_text: An example image
pixel_density: 1
src: https://example.com/image.jpg
srcset:
- pixel_density: 1
src: https://example.com/image.jpg
target_url: https://example.com
title: Ad Title
type: object
required:
- display_ads
title: DisplayAdsResponse
DisplayAdsV2Response:
properties:
display_ads:
additionalProperties:
oneOf:
- $ref: '#/components/schemas/BannerPlacementResponse'
- $ref: '#/components/schemas/MultiPlacementResponse'
discriminator:
propertyName: type
mapping:
image_banner: '#/components/schemas/BannerPlacementResponse'
multi: '#/components/schemas/MultiPlacementResponse'
type: object
title: Display Ads
description: Map of placement IDs to placement response objects. Banner placements return a single flattened ad object with type 'image_banner'. Multi-banner placements return an object with type 'multi' and an 'ads' array. If a placement ID is missing it means that there are no available ads for that placement.
examples:
- carousel:
ads:
- advertiser: Brand B
banner_ad_id: AD_ID_2
images: []
srcset:
- pixel_density: 1
src: https://example.com/image-b.jpg
target_url: https://example.com/brand-b
title: Ad Title B
type: image_banner
type: multi
home_page:
advertiser: Brand A
banner_ad_id: AD_ID_1
cta: Shop Now
cta_label: Shop the sale
description: Ad Description A
images: []
srcset:
- pixel_density: 1
src: https://example.com/image-a.jpg
target_url: https://example.com/brand-a
title: Ad Title A
type: image_banner
type: object
required:
- display_ads
title: DisplayAdsV2Response
FlatDisplayAd:
properties:
type:
type: string
const: image_banner
title: Type
description: Ad type discriminator.
banner_ad_id:
type: string
title: Banner Ad ID
description: Unique identifier of this ad instance for tracking purposes.
advertiser:
type: string
title: Advertiser
description: Name of the advertiser for compliance and disclosure purposes.
target_url:
type: string
title: Target URL
description: Target URL of the ad.
title:
type: string
title: Title
description: Plain text title of the ad.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Optional plain text description of the ad.
cta:
anyOf:
- type: string
- type: 'null'
title: CTA
description: Optional call-to-action for the ad.
cta_label:
anyOf:
- type: string
- type: 'null'
title: CTA Label
description: Optional aria-label for the call-to-action button.
srcset:
items:
$ref: '#/components/schemas/SrcWithPixelDensity'
type: array
title: Srcset
description: Main set of images for the ad with their corresponding pixel densities.
images:
items:
$ref: '#/components/schemas/ImageOverride'
type: array
title: Images
description: Optional list of alternative images for different media conditions.
custom_fields:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Custom Fields
description: Custom key-value fields associated with the creative.
type: object
required:
- type
- banner_ad_id
- advertiser
- target_url
- title
- description
- cta
- srcset
- images
title: FlatDisplayAd
ImageBanner:
properties:
target_url:
type: string
title: Target URL
description: Target URL of the ad.
srcset:
items:
$ref: '#/components/schemas/SrcWithPixelDensity'
type: array
title: Srcset
description: Main set of images for the ad with their corresponding pixel densities.
title:
type: string
title: Title
description: Plain text title of the ad.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Optional plain text description of the ad.
cta:
anyOf:
- type: string
- type: 'null'
title: CTA
description: Optional call-to-action for the ad.
cta_label:
anyOf:
- type: string
- type: 'null'
title: CTA Label
description: Optional aria-label for the call-to-action button.
images:
items:
$ref: '#/components/schemas/ImageOverride'
type: array
title: Images
description: Optional list of alternative images for different media conditions.
type: object
required:
- target_url
- srcset
- title
- description
- cta
- images
title: ImageBanner
ImageOverride:
properties:
media:
type: string
title: Media
description: A media query that must match for this image to be shown.
srcset:
items:
$ref: '#/components/schemas/SrcWithPixelDensity'
type: array
title: Srcset
description: Set of images with their corresponding pixel densities.
type: object
required:
- media
- srcset
title: ImageOverride
MultiPlacementResponse:
properties:
type:
type: string
const: multi
title: Type
description: Ad type discriminator.
ads:
items:
$ref: '#/components/schemas/FlatDisplayAd'
type: array
title: Ads
description: List of ads ordered by auction rank.
type: object
required:
- type
- ads
title: MultiPlacementResponse
PublicErrorDetails:
properties:
code:
type: string
title: Code
message:
type: string
title: Message
source:
anyOf:
- type: string
- type: 'null'
title: Source
type: object
required:
- code
- message
- source
title: PublicErrorDetails
PublicErrorResponse:
properties:
message:
type: string
title: Message
errors:
items:
$ref: '#/components/schemas/PublicErrorDetails'
type: array
title: Errors
trace_id:
anyOf:
- type: string
- type: 'null'
title: Trace ID
type: object
required:
- message
- errors
- trace_id
title: PublicErrorResponse
SrcWithPixelDensity:
properties:
src:
type: string
title: Src
description: URL of the image.
pixel_density:
type: number
title: Pixel Density
description: Pixel density at which this image should be used.
alt_text:
anyOf:
- type: string
- type: 'null'
title: Alt text
description: Optional alt text for the image.
type: object
required:
- src
- pixel_density
title: SrcWithPixelDensity
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: token
x-readme:
explorer-enabled: false