Request Reach Estimate V2

👉

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

*Conditional - required if not configured for the adGroupId

👉

Rules

• 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: startDate, endDate, and targeting
  If any of these are missing in the ad group and not provided in the request payload, the API returns an error.
• If the following request parameters are set at the campaign level: startDate, endDate, the values for these parameters in the request payload are disregarded and the forecast response uses the original campaign values instead.
• If the following request parameters are set at the ad group level: startDate, endDate, and targeting, the values provided for these parameters in the request payload override the original values set at ad group level and are used in the forecast response instead
• Users can simulate changes by overriding ad group-level settings in the request payload. The API does not modify any stored data.
  Note: Currently, the API supports simulation only for ad group-level attributes. Campaign-level budgets or schedules that apply to ad groups are not yet supported for simulation.
• Only daily forecasts are available for unique_users. If a 30days or lifetime forecast is requested, the API will return -1
• unique_users forecasts returns only two fields: minValue, maxValue. scale is not applicable for unique_users forecast

Headers

Sample Request - Get impressions & unique_users estimates for an ad group with updated values for schedule and targeting

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", "unique_users"], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 24779 } ] } ] } }' 

Sample Request - Get unique_users estimates estimates for an ad group with updated values for schedule and targeting

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": ["unique_users"], "timeframes":["30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 24779 } ] } ] } }' 

Response

estimates Objects:

The estimates object contains forecasted metrics across multiple time ranges. Each supported metric (for example, impressions, uniqueUsers) is represented as a nested object with estimated ranges. Each metric object may include one or more time-range sub-objects.

Object structure:

"estimates": { "<metric>": { "daily": { ... }, "30days": { ... }, "lifetime": { ... } }
}

Time-Range Sub-Objects: Each metric can contain the following optional sub-objects:

Estimate range Object: Each time-range object (daily, 30days, lifetime) contains the estimated range values described below ::

Success Sample Response - Get impressions & unique_users estimates for an ad group with updated values for schedule and targeting

{ "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" } }, "uniqueUsers": { "daily": { "minValue": 1, "maxValue": 15 }, "30days": { "minValue": -1, "maxValue": -1 }, "lifetime": { "minValue": -1, "maxValue": -1 } } }, "details": [ "30DAYS_UNIQUE_USERS_FORECAST_UNAVAILABLE", "LIFETIME_UNIQUE_USERS_FORECAST_UNAVAILABLE" ]
} 

Failure Sample Response - Get impressions & unique_users estimates for an ad group with updated values for schedule and targeting

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

Failure Sample Response - Get unique_users estimates estimates for an ad group with updated values for schedule and targeting

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