Sign in

v1

latestOpenAPI 3.1.02026-07-241765501.1 MB
Display Ads

Retrieve Display Ads

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.

get/v2/display-ads

Query parameters

keystring required

The key of the index to use.

The key of the index to use.

querystring nullable

Search query for keyword targeting.

Example:apple

Search query for keyword targeting.

filter_namestring nullable

The name of the related browse filter.

Example:group_id

The name of the related browse filter.

filter_valuestring nullable

The value of the related browse filter.

Example:123

The value of the related browse filter.

num_resultsobject

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.

placementsstring[] required

Placement customer IDs to fetch ads for.

Placement customer IDs to fetch ads for.

[
  "home_page",
  "carousel"
]

Response

Successful Response.

display_adsobject required

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.

Example response

{
  "display_ads": {
    "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"
    }
  }
}