Export (0) Print
Expand All

GetEstimatedBidByKeywordsRequest Message

Defines the request message that the client passes to the GetEstimatedBidByKeywords operation.

<wsdl:message name="GetEstimatedBidByKeywordsRequest">
  <wsdl:part name="parameters" element="tns:GetEstimatedBidByKeywordsRequest" />
</wsdl:message>

Body Elements

Element

Description

Data Type

Required

AdGroupId

The identifier of the ad group whose performance data is used to help determine how well the keyword might perform in the context of the ad group. Specifying an ad group helps improve the accuracy of the suggested bid.

If you specify an ad group, you must specify the campaign that it belongs to.

string

No

CampaignId

The identifier of the campaign that owns the ad group specified in AdGroupId. If you do not specify an ad group, the campaign’s performance data is used to help determine how well the keyword might perform in the context of the campaign.

System_CLiX_noteNote

Specifying a campaign and ad group helps improve the accuracy of the suggested bid. If neither AdGroupId or CampaignId are specified, the operation uses the specified CustomerAccountId header element to help determine how well the keyword might perform in the context of the account.

string

No

Currency

The monetary unit to use to calculate the cost estimates and suggested bid value.

If not set, the service determines the currency from the account specified in the CustomerAccountId header element. If neither is set, the service uses USDollar.

Currency

No

GetBidsAtLevel

Determines whether to return estimates for keyword level bids, ad group level bids, or both.

  • Set GetBidsAtLevel to 0 to get an array of KeywordEstimatedBid.

  • Set GetBidsAtLevel to 2 to get one AdGroupEstimatedBid.

  • Set GetBidsAtLevel to 3 to get an array of KeywordEstimatedBid and one AdGroupEstimatedBid.

If you do not set GetBidsAtLevel, the default is to return only an array of KeywordEstimatedBid, or the equivalent of setting GetBidsAtLevel to 0.

If you set GetBidsAtLevel to any other value the service will return Code 3501 with ErrorCode CampaignServiceBidLevelInvalid.

int

No

GetIncreasedBidCoverage

Set to true if you want to get an estimated bid for all requested keywords. If true, some returned elements of the EstimatedBidAndTraffic Data Object may be NULL.

The default is false.

For more information, see Get Increased Bid Coverage.

boolean

No

Keywords

An array of keywords for which you want to get suggested bid values. You may specify a maximum of 1,000 keywords, and each keyword can contain a maximum of 100 characters.

string array

Yes

Language

The language used to help determine the country to use as the source of data for estimating the bids, if the PublisherCountries element is not specified.

System_CLiX_noteNote

The language must be supported in each of the countries in the PublisherCountries element.

For possible values and information about the relationship between languages and countries, see Publisher Country Values.

The default value is determined by the PublisherCountries element and the location targets associated with the specified AdGroupId and CampaignId. For more information, see the Remarks section below.

string

No

MatchTypes

An array of unique match types for which you want to get estimates.

You may not specify the Content match type.

MatchType array

Yes

PublisherCountries

The country codes of the countries to use as the source of data for estimating the bids.

System_CLiX_noteNote

All of the countries must support the language specified in the Language element.

You may specify one or more country codes. For possible values, see Country Codes.

The default value is determined by the Language element and the location targets associated with the specified AdGroupId and CampaignId. For more information, see the Remarks section below.

string array

No

TargetPositionForAds

The position where you want your ads to appear in the search results.

The default is MainLine1.

TargetAdPosition

No

Header Elements

For information about the values you set the DeveloperToken, Password, and UserName elements to, see Getting Started With the Bing Ads API.

Element

Description

Data Type

ApplicationToken

The application-access token. This header element is not used and should be null.

string

AuthenticationToken

The authentication token. This header element is not used and should be null.

string

CustomerAccountId

The identifier of the account that owns the entities in the request.

string

CustomerId

The identifier of the customer that owns the account. This header element is not used and should be null.

string

DeveloperToken

The caller's developer access token.

string

Password

The user's sign-in password.

string

UserName

The user's sign-in user name. You cannot set this element to a Microsoft account (formerly known as Windows Live ID).

string

SOAP

The following example shows the complete SOAP envelope for a GetEstimatedBidByKeywordsRequest request.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://adcenter.microsoft.com/v8">
    <Action mustUnderstand="1">GetEstimatedBidByKeywords</Action>
    <ApplicationToken i:nil="false"></ApplicationToken>
    <AuthenticationToken i:nil="false"></AuthenticationToken>
    <CustomerAccountId i:nil="false"></CustomerAccountId>
    <CustomerId i:nil="false"></CustomerId>
    <DeveloperToken i:nil="false"></DeveloperToken>
    <Password i:nil="false"></Password>
    <UserName i:nil="false"></UserName>
  </s:Header>
  <s:Body>
    <GetEstimatedBidByKeywordsRequest xmlns="https://adcenter.microsoft.com/v8">
      <Keywords i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string></a1:string>
      </Keywords>
      <TargetPositionForAds></TargetPositionForAds>
      <Language i:nil="false"></Language>
      <PublisherCountries i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string></a1:string>
      </PublisherCountries>
      <Currency i:nil="false"></Currency>
      <MatchTypes i:nil="false" xmlns:a1="http://schemas.datacontract.org/2004/07/Microsoft.AdCenter.Advertiser.CampaignManagement.Api.DataContracts">
        <a1:MatchType></a1:MatchType>
      </MatchTypes>
      <CampaignId i:nil="false"></CampaignId>
      <AdGroupId i:nil="false"></AdGroupId>
      <GetIncreasedBidCoverage i:nil=”false”></GetIncreasedBidCoverage>
      <GetBidsAtlevel i:nil=”false”></GetBidsAtLevel>
    </GetEstimatedBidByKeywordsRequest>
  </s:Body>
</s:Envelope>

Remarks

As a best practice for the most accurate bid estimates per country, you should specify only one country per service call. If no countries are specified or if multiple PublisherCountries are specified, then the service will use the first available set of the following properties to determine the country to use as the source of data for estimating the bids.

  • Multiple countries corresponding to this operation's specified PublisherCountries element.

  • The service will use the set of all supported countries for the specified Language, and join with common supported countries in the LocationTarget associated with the specified AdGroupId.

    System_CLiX_noteNote

    If the target countries conflict with the specified Language, then the service will disregard the target countries and only use the set of all supported countries for the specified Language.

  • The service will use the set of all supported countries for the specified Language, and join with common supported countries in the LocationTarget associated with the specified CampaignId.

    System_CLiX_noteNote

    If the target countries conflict with the specified Language, then the service will disregard the target countries and only use the set of all supported countries for the specified Language.

  • Language element of the AdGroup corresponding to this operation's specified AdGroupId element. The service will use the set of all supported countries for this language.

Given multiple countries from one of the property sets above, the service will then determine one country with the highest impression count to use as the source of data for estimating the bids. The response will not include details on the final filtered country.

Requirements

AdIntelligenceService.svc v8

Namespace: https://adcenter.microsoft.com/v8

Community Additions

Show:
© 2014 Microsoft