Export (0) Print
Expand All

GetEstimatedPositionByKeywordsRequest Message

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

<wsdl:message name="GetEstimatedPositionByKeywordsRequest">
  <wsdl:part name="parameters" element="tns:GetEstimatedPositionByKeywordsRequest" />
</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 position.

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 position. 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

Keywords

An array of keywords for which you want to get the estimated position in the search results, based on the specified bid value. You may specify a maximum of 1,000 keywords and each keyword can contains 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

MaxBid

The maximum bid value to use to determine the estimated position in the search results.

double

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

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 GetEstimatedPositionByKeywordsRequest 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">GetEstimatedPositionByKeywords</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>
    <GetEstimatedPositionByKeywordsRequest 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>
      <MaxBid></MaxBid>
      <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>
    </GetEstimatedPositionByKeywordsRequest>
  </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