HomeGuidesAPI ReferenceRelease Notes
Guides

Request Reach Estimate V2

Use this API to request a reach estimate or impressions opportunity forecast for a given ad group.
Users can simulate changes by overriding ad group-level settings in the request payload. The API does not modify any stored data.
Note: Currently, simulation is only supported for ad group-level attributes. Campaign-level schedules that cascade to ad groups cannot yet be simulated in this API. If budget, schedule and deliverySpeed are set at the campaign level, the API will disregard these values if passed, and the forecast provided will use the original campaign values instead.

👉

What It Does:

  • Computes potential reach ( impressions) based on the targeting and schedule settings of a given ad group.
    Allows developers to simulate changes to ad group configuration by overriding certain fields in the request payload.
  • Does not persist or modify ad group data — it is strictly a forecasting tool
  • To return a valid reach estimate, the following ad group-level attributes must be available either in the stored ad group OR passed in the request : schedule and targeting.

👉

Simulation (“What-If” analysis) support:

  • You can override ad group-level startDate, endDate and targeting in the request body to simulate changes without modifying the actual ad group.
  • Campaign-level schedules that cascade to ad groups cannot yet be simulated in this API. If budget, schedule and deliverySpeed are set at the campaign level, the API will disregard these values if passed, and the forecast provided will use the original campaign values instead.
  • All overrides are non-persistent. This API does not modify stored campaign or ad group data.

📘

URL:POST/api/v2/reachEstimate

Request Parameters

ParametersNotesTypeRequiredPossible Values
advertiserIdID of advertiser integerYUnique numeric identifier
campaignIdID of the campaignintegerYUnique numeric identifier
adGroupIdID the ad groupintegerYUnique numeric identifier
metricThe list of metrics you are requesting an estimate for.

Note: “impressions” is currently the only supported metric.		arrayYValue:
impressions
startDateSimulated start date for ad group scheduling

Note:
  • If startDate has been set at the campaign level for the specified ad group:
    the startDate value passed in the API request is ignored, and the forecast in the response is based on the startDate of the campaign
  • If startDate has been set at the ad group level for the specified ad group:
    the forecast is based on the startDate value in the request, not the original value set at the ad group level
datetimeNDate must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Note: All date and time values are internally converted to Eastern Time (ET) for processing.

All timestamps must be provided in ISO 8601 format. Timestamps are normalized to the start of the hour in Eastern Time (ET)—this means any minutes and seconds will be truncated

Please account for this when requesting for forecasts.
endDateSimulated end date for ad group scheduling.
For ad groups that run indefinitely, use the value:
endDate = ‘9999-12-30T00:00:00Z’
Note:
  • If endDate has been set at the campaign level for the specified ad group:
    the endDate value passed in the API request is ignored. Instead, the forecast returned in the response is based on the endDate of the campaign
  • If endDate has been set at the ad group level for the specified ad group:
    the forecast is based on the endDate value in the request, not the original value set at the ad group level.
datetimeNDate must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Note: All date and time values are internally converted to Eastern Time (ET) for processing.

All timestamps must be provided in ISO 8601 format. Timestamps are normalized to the start of the hour in Eastern Time (ET)—this means any minutes and seconds will be truncated.
Additionally, the end date must be set to a time after 12:00 PM ET

Please account for this when requesting for forecasts.
targetingA nested array element with following elements:
  • keywords: ONLY APPLICABLE FOR KEYWORD TARGETING
    • keywordText: string data type
    • matchType: string data type Values: broad, exact

    • Note: only Exact match type is allowed for negative keywords

    • contexual: ONLY APPLICABLE FOR CONTEXTUAL TARGETING
      • id: integer data type
      • reach: string data type
        Values: "tier_1", "tier_2", "tier_3", "tier_4", "tier_5", "tier_6", "tier_7"

    Note: This is how tiers in API call map to the representation on ad center UI:
    Tier mapping: low = [tier_1, tier_2], mid = [tier_3, tier_4], high = [tier_5, tier_6, tier_7]

    • behavioral: ONLY APPLICABLE FOR BEHAVIORAL TARGETING
      • audienceType: string data type Values:
        • retail
        • brand
        • persona
        • custom
      • attribute: string data type Values:
        • For category:
          • historical
          • predictive
        • For brand:
          • historical
          • predictive
          • lapsedbuyers
        • For persona:
          • lifestyle
          • lifestage
      • id:integer data type
    • runOfSite ONLY APPLICABLE FOR ROS TARGETING:
      string data type, Value: true
    • geoTargets
      • id: integer data type

        Note:
        1. If Geo targeting is not specified, the default Country (US) level targeting will be applied
        2. IDs with isDisabled = true from POST/api/v1/targeting/list cannot be used for targeting
Note:
If the targeting values have been set at the ad group level for the specified ad group, the forecast is based on the targeting value in the request, not the original value set at the ad group level.		The values:
• keywords
• contextual
• behavioral
• runOfSite
• geoTargets
timeframesSpecifies the timeframes for which forecasts should be returned. If not provided, forecasts for all available timeframes will be returned.arrayNThe values:
• daily
• 30days
• lifetime

Headers


Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the APIYPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide. This key can be repurposed for SP API access as well.
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.YPlease use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATUREAuth signature as an API keyYUse the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestampYUse the signature generator code (Getting Started Guide) to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the APIY1

Sample Request

curl --location --request POST 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v2/reachEstimate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_CONSUMER.ID: abcde-v123-fa2r-a1fs-asd45f6qef' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": 1627, "campaignId": 9279, "adGroupId": 2198, "metric": ["impressions"], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 24779 } ] } ] } }'

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure
string
forecastIdforecastId for every successful responsestring
estimatesContains forecasted metrics over various time ranges. It is a nested json object that contains forecast data for impressions
The estimates objects are detailed below in a separate table following this one.		json
detailsDetails of the response.
Values:
  • REACH_ESTIMATE_SUCCESS
  • REACH_ESTIMATE_FAILURE
stri

estimates Objects:

impression metric is structured as follows:

ElementsDescriptionType
dailyEstimated metric values per dayjson
30daysEstimated metric values for 30 daysjson
lifetimeEstimated metric values for the ad group's full lifetimejson

each sub-object (daily, 30days, lifetime) contains:

ElementsDescriptionType
minValueLower bound of the estimated metric rangeint
maxValueUpper bound of the estimated metric range
Note:This field is omitted when there is no defined upper bound for the estimate		int
scaleThe relative scale of the forecast
Values:
  • LOW
  • MODERATE
  • HIGH
string

Reach Estimate Success Response

{ "code": "success", "forecastId": "145", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15 ,"scale": "LOW"}, "30days": { "minValue": 5, "maxValue": 75 ,"scale": "MODERATE"}, "lifetime": { "minValue": 1, "maxValue": 15 ,"scale": "HIGH"} } }, "details": [ "REACH_ESTIMATE_SUCCESS" ]
}

Reach Estimate Failure Response

{ "code": "failure", "details": [ "FAILURE_FETCHING_REACH_ESTIMATE" ]
}

Updated 1 day ago