Microsoft Advertising Connection Details¶
Introduction¶
Connector Version
This documentation is based on version 23.0.8803 of the connector.
Get Started¶
Microsoft Ads Version Support
The connector models reports and other entities in the Microsoft Ads API as relational views.
Establish a Connection¶
Connect to Microsoft Ads¶
You need to register a Microsoft Ads account, get a developer token, and authenticate using OAuth to connect to the Microsoft Ads APIs.
Register a Bing Ads Account¶
Complete the following steps to sign up for a Microsoft Ads account and obtain the CustomerId
and (optional) AccountId
:
- Sign up for a Microsoft Ads account in the Bing Ads Web application or at the Sandbox Site for a sandbox account.
- Select
Settings > Accounts and Billing
and select a single account. TheAccountId
andCustomerId
(cid) are displayed on the account's page and in the page's URL.
Get a Developer Token¶
To use the Microsoft Ads APIs, you must have a DeveloperToken
in addition to the CustomerId
. You must have the Super Admin role in Microsoft Ads to create a developer token, though you do not need special permissions to use the token.
- Log in at the Bing Ads Developer Portal as a Microsoft Account user with the Microsoft Ads Super Admin role.
- Click
Request Token
and take note of your developer token. You will set it in theDeveloperToken
connection property.
Authenticate to Microsoft Ads¶
OAuth¶
AuthScheme
must be set to OAuth
in all user account flows.
Desktop Applications¶
An embedded OAuth application is provided that simplifies OAuth desktop Authentication. Alternatively, you can create a custom application. See Creating a Custom OAuth App for information on creating custom applications and reasons for doing so.
For authentication, the only difference between the two methods is that you must set two additional connection properties when using custom OAuth applications.
After setting the following connection properties, you are ready to connect:
InitiateOAuth
: Set this toGETANDREFRESH
. You can useInitiateOAuth
to avoid repeating the OAuth exchange and manually setting theOAuthAccessToken
.OAuthClientId
: (custom applications only) Set to the Client ID in your application settings.OAuthClientSecret
: (custom applications only) Set to the Client Secret in your application settings.
When you connect, the connector opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The connector then completes the OAuth process as follows:
- Extracts the access token from the callback URL.
- Obtains a new access token when the old one expires.
- Saves OAuth values in
OAuthSettingsLocation
so that they persist across connections.
Create a Custom OAuth App¶
When to Create a Custom OAuth App¶
embeds OAuth Application Credentials with branding that can be used when connecting via either a Desktop Application or from a Headless Machine. Creating a custom OAuth application is, however, required when using a web application. You may choose to create your own OAuth Application Credentials when you want to
- control branding of the Authentication Dialog
- control the redirect URI that the application redirects the user to after the user authenticates
- customize the permissions that you are requesting from the user
Follow the steps below to create a custom OAuth app and obtain the connection properties in a specific OAuth authentication flow.
Create a Custom OAuth App¶
You can create a custom OAuth application for desktop applications, web applications, and headless machines. The steps are identical except for how the Redirect URI is defined.
Desktop Applications¶
Follow these steps:
- If you have not done so already, sign up for a Bing Ads account in the Bing Ads Web application or at the Sandbox Site for a sandbox account.
- Go to the Azure portal (Azure test portal for sandbox accounts), and login with your Microsoft Account credentials when prompted.
- Under
Azure Active Directory > App registrations
, clickNew registration
. - Provide the application name and select an appropriate Supported account type. If you do not choose to allow personal Microsoft accounts, users with personal accounts are prevented from authenticating.
- How Re In the Redirect URI section, you must set an appropriate URL. For desktop applications a value such as
http://localhost:33333
or another port of your choice may be set. - Register your application and take note of your Application (client) Id. You will use it as the
OAuthClientId
value in the OAuth grant flow. - In the Certificates & secrets section, click New client secret to generate a client secret and take note of the resulting value. You will use it as the
OAuthClientSecret
value.
Important Notes¶
Configuration Files and Their Paths¶
- All references to adding configuration files and their paths refer to files and locations on the Jitterbit agent where the connector is installed. These paths are to be adjusted as appropriate depending on the agent and the operating system. If multiple agents are used in an agent group, identical files will be required on each agent.
Advanced Features¶
This section details a selection of advanced features of the Microsoft Ads connector.
User Defined Views
The connector allows you to define virtual tables, called user defined views, whose contents are decided by a pre-configured query. These views are useful when you cannot directly control queries being issued to the drivers. See User Defined Views for an overview of creating and configuring custom views.
SSL Configuration
Use SSL Configuration to adjust how connector handles TLS/SSL certificate negotiations. You can choose from various certificate formats; see the SSLServerCert
property under "Connection String Options" for more information.
Proxy
To configure the connector using private agent proxy settings, select the Use Proxy Settings
checkbox on the connection configuration screen.
Query Processing
The connector offloads as much of the SELECT statement processing as possible to Microsoft Ads and then processes the rest of the query in memory (client-side).
User Defined Views¶
The Jitterbit Connector for Microsoft Ads allows you to define a virtual table whose contents are decided by a pre-configured query. These are called User Defined Views, which are useful in situations where you cannot directly control the query being issued to the driver, e.g. when using the driver from Jitterbit. The User Defined Views can be used to define predicates that are always applied. If you specify additional predicates in the query to the view, they are combined with the query already defined as part of the view.
There are two ways to create user defined views:
- Create a JSON-formatted configuration file defining the views you want.
- DDL statements.
Define Views Using a Configuration File¶
User Defined Views are defined in a JSON-formatted configuration file called UserDefinedViews.json
. The connector automatically detects the views specified in this file.
You can also have multiple view definitions and control them using the UserDefinedViews
connection property. When you use this property, only the specified views are seen by the connector.
This User Defined View configuration file is formatted as follows:
- Each root element defines the name of a view.
- Each root element contains a child element, called
query
, which contains the custom SQL query for the view.
For example:
{
"MyView": {
"query": "SELECT * FROM AdGroups WHERE MyColumn = 'value'"
},
"MyView2": {
"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
}
}
Use the UserDefinedViews
connection property to specify the location of your JSON configuration file. For example:
"UserDefinedViews", "C:\Users\yourusername\Desktop\tmp\UserDefinedViews.json"
Define Views Using DDL Statements¶
The connector is also capable of creating and altering the schema via DDL Statements such as CREATE LOCAL VIEW, ALTER LOCAL VIEW, and DROP LOCAL VIEW.
Create a View¶
To create a new view using DDL statements, provide the view name and query as follows:
CREATE LOCAL VIEW [MyViewName] AS SELECT * FROM Customers LIMIT 20;
If no JSON file exists, the above code creates one. The view is then created in the JSON configuration file and is now discoverable. The JSON file location is specified by the UserDefinedViews
connection property.
Alter a View¶
To alter an existing view, provide the name of an existing view alongside the new query you would like to use instead:
ALTER LOCAL VIEW [MyViewName] AS SELECT * FROM Customers WHERE TimeModified > '3/1/2020';
The view is then updated in the JSON configuration file.
Drop a View¶
To drop an existing view, provide the name of an existing schema alongside the new query you would like to use instead.
DROP LOCAL VIEW [MyViewName]
This removes the view from the JSON configuration file. It can no longer be queried.
Schema for User Defined Views¶
User Defined Views are exposed in the UserViews
schema by default. This is done to avoid the view's name clashing with an actual entity in the data model. You can change the name of the schema used for UserViews by setting the UserViewsSchemaName
property.
Work with User Defined Views¶
For example, a SQL statement with a User Defined View called UserViews.RCustomers
only lists customers in Raleigh:
SELECT * FROM Customers WHERE City = 'Raleigh';
An example of a query to the driver:
SELECT * FROM UserViews.RCustomers WHERE Status = 'Active';
Resulting in the effective query to the source:
SELECT * FROM Customers WHERE City = 'Raleigh' AND Status = 'Active';
That is a very simple example of a query to a User Defined View that is effectively a combination of the view query and the view definition. It is possible to compose these queries in much more complex patterns. All SQL operations are allowed in both queries and are combined when appropriate.
SSL Configuration¶
Customize the SSL Configuration¶
By default, the connector attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store.
To specify another certificate, see the SSLServerCert
property for the available formats to do so.
Data Model¶
The Jitterbit Connector for Microsoft Ads models entities in the Microsoft Ads API as database views and stored procedures. These are defined in schema files, which are simple, text-based configuration files.
The following sections provide information on executing SQL to the available API objects. The connector offloads as much of the SELECT statement processing as possible to Microsoft Ads and then processes the rest of the query in memory; API limitations and requirements are documented in this section.
Views
The connector Microsoft Ads objects as Views, including reports.
You can query Reports based on an aggregation and time period. The default time period is this year; to change the time period, see the following Time Filter section.
When retrieving only some report columns, you should select all columns marked as 'Select Requirement' and at least one of the columns marked as 'Metric' to issue a valid report request. On the other hand, if you are retrieving all columns, then the driver defaults to including the minimally required columns in the request.
Specifying a Time Filter¶
Date Ranges
You can specify date ranges in the WHERE clause using the "Date" field with these operators: =, <,>
These predefined date fields are supported:
- Today
- Yesterday
- LastSevenDays
- ThisWeek
- LastWeek
- LastFourWeeks
- ThisMonth
- LastMonth
- LastThreeMonths
- LastSixMonths
- ThisYear
- LastYear
The default DatePreset value is "ThisYear".
To search on a predefined date range, set the DatePreset pseudo column in the WHERE clause to one of the predefined date fields.
SELECT Monthly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ] WHERE DatePreset = 'LastYear'
To specify a custom date range, specify the StartDate and EndDate pseudo columns in the WHERE clause.
SELECT Monthly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ] WHERE StartDate = '2014-01-01' AND EndDate = '2017-09-19'
Aggregation
Aggregation is the process of reducing and summarizing data. You can aggregate the report data by selecting one of the following aggregation columns:
-
Daily
: Each row of the report identifies the month, day, and year when the transaction occurred. The report data is aggregated by each day. The report includes a column named Daily that contains the day formatted as yyyy-mm-dd.SELECT Daily, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
DayOfWeek
: Each row of the report identifies the day of the week when the transaction occurred. The report data is aggregated by each of the seven days in a week. The report includes a column named DayOfWeek, and the possible values are 1 - 7 where 1 represents Sunday and 7 represents Saturday.If the report time spans multiple weeks, then the performance data across all weeks for a given day of the week is aggregated in one row. For example, if Campaign A has 5 impressions every Monday (day 2) throughout each of the 3 weeks included in the report time range, then the report includes one row with DayOfWeek set to 2 and impressions in that row totaling 15.
SELECT DayOfWeek, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
Hourly
: Each row of the report identifies the hour when the transaction occurred. The report data is aggregated by each hour of the day. The report includes a column named Hourly, and the possible values are 0 - 23.SELECT Hourly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
HourOfDay
: Each row of the report identifies the hour of the day when the transaction occurred. The report data is aggregated by each of the 24 hours across all days. The report includes a column named HourOfDay, and the possible values are 0 - 23.If the report time spans multiple days, then the performance data across all days for a given hour is aggregated in one row. For example, if Campaign A has 5 impressions during hour 7 on each of the 3 days included in the report time range, then the report includes one row with impressions for HourOfDay totaling 15.
SELECT HourOfDay, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
Monthly
: Each row of the report identifies the month when the transaction occurred. The report data is aggregated by each month. The report includes a column named Monthly that contains the first day of the month formatted as yyyy-mm-dd.SELECT Monthly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
Weekly
: Each row of the report identifies the week when the transaction occurred. The report data is aggregated by each week. The report includes a column named Weekly that contains the date of the Sunday for each week formatted as yyyy-mm-dd.SELECT Weekly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
-
Yearly
: Each row of the report identifies the year when the transaction occurred. The report data is aggregated by each year. The report includes a column named Yearly that contains the year formatted as yyyy.SELECT Yearly, AccountName, AccountStatus, Impressions, Clicks, ConversionRate FROM [ AccountPerformanceReport ]
Stored Procedures
Stored Procedures are function-like interfaces to the data source. They can be used to search, update, and modify information in the data source.
Views¶
Views are similar to tables in the way that data is represented; however, views are read-only.
Queries can be executed against a view as if it were a normal table.
Jitterbit Connector for Microsoft Ads Views¶
Name | Description |
---|---|
AccountPerformanceReport | Use this report to observe long-term account performance and trends. |
Accounts | Query the available Accounts in Bing Ads. |
AdDynamicTextPerformanceReport | Use this report to identify which dynamic text strings are performing well and which strings you should consider changing. |
AdExtensionByAdReport | Use this report to compare how well different versions of your ad extensions are performing with each ad. |
AdExtensionByKeywordReport | Use this report to compare how well different versions of your ad extensions are performing for each keyword. |
AdExtensionDetailReport | Use this report to discover the effectiveness of individual ad extension items, for example, each link of a sitelink extension. |
AdGroupPerformanceReport | Use this report to more broadly compare delivery performance statistics by ad group, campaign, or account attributes rather than at the keyword level. |
AdGroups | Query the available AdGroups in Bing Ads. |
AdPerformanceReport | Use this report to help you determine which ads lead to clicks and conversions, and which are not performing. Having underperforming ads in your account can pull down the quality of your campaigns. |
Ads | Query the available Ads in Bing Ads. |
AgeGenderAudienceReport | Use this report to discover how your campaigns and ad groups are resonating with audiences of diverse age and gender. |
AudiencePerformanceReport | Use this report to compare delivery performance statistics by audience, ad group, campaign, or account attributes. |
Audiences | Query the available Audiences in Bing Ads. |
BidOpportunities | Query the available Bid Opportunities in Bing Ads. |
BudgetOpportunities | Query the available Budget Opportunities in Bing Ads. |
Budgets | Query the available Budgets in Bing Ads. |
BudgetSummaryReport | Use this report to discover how your campaign's budget is performing for the month. For example, the report shows your monthly budget, how much you have spent to date, and whether you are on target to spend your monthly budget. |
CampaignPerformanceReport | Use this report to view high-level performance statistics and quality attributes for each campaign or account. This is also a quick way to flag any major campaign or account problems. |
Campaigns | Query the available Campaigns in Bing Ads. |
ConversionPerformanceReport | Use this report to understand which campaigns and keywords are leading an audience to complete a purchase or other conversion action. |
DestinationUrlPerformanceReport | Use this report to identify landing pages that met audience expectations and potentially resulted in high click-through or conversion rates. |
DSAAutoTargetPerformanceReport | Use this report to find out which DSA auto targets are performing well and those that are not. |
DSACategoryPerformanceReport | Use this report to find out which DSA categories are performing well and those that are not. |
DSASearchQueryPerformanceReport | Use this report to find out which search terms are in demand for your DSA campaign and the performance of dynamic headlines that are being displayed. |
GeographicPerformanceReport | Use this report to see which locations your traffic is coming from. You can then validate whether your location targeting strategy is successful, and identify opportunities to improve. The report also identifies either the physical location of the search user or the geographical location interest based on the user's search query. |
GoalsAndFunnelsReport | Use this report to discover whether your audience completes each step through the land, browse, prospect, and conversion pages of your website. For example, you can use this report to determine the step that users leave the conversion funnel, so that you can improve or remove that step to increase the chance that the user will continue to the next step. |
KeywordDemographics | Query the available Keyword Demographics in Bing Ads. |
KeywordEstimatedBid | Query the available Keyword Estimated Bid in Bing Ads. |
KeywordEstimatedPosition | Query the available EstimatedPosition in Bing Ads. |
KeywordHistoricalSearch | Query the available Keyword Historical Search in Bing Ads. |
KeywordLocations | Query the available Keyword Locations in Bing Ads. |
KeywordPerformance | Query the available Keyword Performance in Bing Ads. |
KeywordPerformanceReport | Use this report to find out which keywords are performing well and those that are not. |
Keywords | Query the available Keywords in Bing Ads. |
NegativeKeywordConflictReport | Use this report to discover which keywords and negative keywords are in conflict, and whether the conflict is at the campaign or ad group level. Use this list to figure out which negative keywords to delete. |
ProductDimensionPerformanceReport | Use this report to find out which product dimensions are performing well and those that are not. |
ProductNegativeKeywordConflictReport | Use this report to discover which keywords and negative keywords are in conflict, and whether the conflict is at the campaign or ad group level. Use this list to figure out which negative keywords to delete. |
ProductPartitionPerformanceReport | You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the product partitions are performing well. |
ProductPartitionUnitPerformanceReport | Use this report to find out which product partition units are performing well and those that are not. |
ProductSearchQueryPerformanceReport | Use this report to get insight into what your audience is searching for when your ads are shown as well as ensure that your product titles are relevant to search queries. |
PublisherUsagePerformanceReport | Use this report to see if any website URLs aren't performing well enough for your campaign or ad group target settings. For example, if ad impressions at those URLs yield a low click-through rate, then you might decide to exclude those websites from your campaign. |
SearchCampaignChangeHistoryReport | Use this report to discover when changes to an account were made, as well as which user made the changes. |
SearchQueryPerformanceReport | Use this report to see what your audience is searching for when your ads are shown. You can use this information to make informed additions, removals, or edits to both your keyword and negative keyword lists. |
ShareOfVoiceReport | Use this report to view impression share (%) of successful bids for each keyword, and identify opportunities to increase impression share. |
Tags | Query the available Tags in Bing Ads. |
UserLocationPerformanceReport | Use this report to see which locations your traffic is coming from. You can then validate whether your location targeting strategy is successful, and identify opportunities to improve. The report also identifies the physical location of the user and the intended geographical location of the user's search query, for example a user in Seattle searching for services in Portland. |
AccountPerformanceReport¶
Use this report to observe long-term account performance and trends.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | |
AbsoluteTopImpressionSharePercent | Double | True | The number of times your ad is shown in the top position as a percentage of the total available impressions in the market you were targeting. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads. It is the share of the prospective customer's mindshare and buying intent you captured. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
LowQualityClicks | Integer | True | Clicks that exhibit a low likelihood of commercial intent. You are not billed for these clicks. | ||
LowQualityClicksPercent | Double | True | The low-quality clicks as a percentage. | ||
LowQualityImpressions | Integer | True | The number of impressions that result from low-quality keyword searches. | ||
LowQualityImpressionsPercent | Double | True | The low-quality impressions as a percentage. | ||
LowQualityConversions | Integer | True | The number of conversions that originate from low-quality clicks. | ||
LowQualityConversionRate | Double | True | The low-quality conversion rate as a percentage. | ||
ExactMatchImpressionSharePercent | Double | True | The estimated percentage of impressions that your account received for searches that exactly matched your keyword, out of the total available exact match impressions you were eligible to receive. | ||
ImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | ||
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankAggPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
PhoneImpressions | Integer | True | The number of times your tracked number was shown on all devices. | ||
PhoneCalls | Integer | True | The number of total calls to the tracked phone number that showed with your ad. | ||
Ptr | Double | True | The phone-through rate (Ptr). The formula for calculating the Ptr is (PhoneCalls / PhoneImpressions) x 100. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). | ||
LowQualityGeneralClicks | Integer | True | Clicks that are filtered by general methods, such as blacklists and activity-based detection, and that exhibit a low likelihood of commercial intent. You are not billed for these clicks. | ||
LowQualitySophisticatedClicks | Integer | True | Invalid clicks that use sophisticated means to appear valid. You are not billed for these clicks. | ||
AudienceImpressionLostToBudgetPercent | Double | True | The percentage of impression share you lost due to insufficient budget on the Microsoft Audience Network. | ||
AudienceImpressionLostToRankPercent | Double | True | The percentage of impression share you lost due to low rank on the Microsoft Audience Network. | ||
AudienceImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions you could have received on the Microsoft Audience Network. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Accounts¶
Query the available Accounts in Bing Ads.
Table Specific Information¶
Select¶
Searches on this table are processed client-side by the connector; the following query is processed server-side.
SELECT * FROM [ Accounts ]
The client-side execution of the query can be turned off by setting SupportEnhancedSQL
to false in which case any query other than SELECT *
will return an error.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The system generated identifier of the account. | |||
Name | String | The name of the account. | |||
Number | String | The account number. | |||
AccountLifeCycleStatus | String | The status of the account. The allowed values are Draft, Active, Inactive, Pause, Pending, Suspended. | |||
PauseReason | Integer | A flag value that indicates who paused the account. The following are the possible values: 1-The user paused the account. 2-The billing service paused the account. 4-The user and billing service paused the account. |
AdDynamicTextPerformanceReport¶
Use this report to identify which dynamic text strings are performing well and which strings you should consider changing.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
Keyword | String | The keyword text. | |||
AdId | Long | Ad Id | |||
AdTitle | String | True | The ad title. | ||
AdType | String | The ad type. | |||
AdLabels | String | The labels applied to the ad. | |||
DestinationUrl | String | True | The destination URL attribute of the ad, keyword, or ad group criterion. | ||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
Param1 | String | True | The first dynamic substitution parameter (Param1) of a keyword or biddable ad group criterion. | ||
Param2 | String | True | The second dynamic substitution parameter (Param2) of a keyword or biddable ad group criterion. | ||
Param3 | String | True | The third dynamic substitution parameter (Param3) of a keyword or biddable ad group criterion. | ||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
KeywordStatus | String | The keyword status. | |||
TitlePart1 | String | The title part 1 attribute of an ad. | |||
TitlePart2 | String | The title part 2 attribute of an ad. | |||
TitlePart3 | String | The title part 3 attribute of an ad. | |||
Path1 | String | The path 1 attribute of an ad. | |||
Path2 | String | The path 2 attribute of an ad. | |||
FinalUrl | String | The Final URL of the ad, keyword, or criterion. | |||
FinalMobileUrl | String | The Final Mobile URL of the ad, keyword, or criterion. | |||
FinalAppUrl | String | Reserved for future use. | |||
AdDescription | String | The text attribute of an ad. | |||
AdDescription2 | String | The second ad description that appears below the path in your ad. Ad description 2 might not appear in your ad. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AdExtensionByAdReport¶
Use this report to compare how well different versions of your ad extensions are performing with each ad.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | True | The Bing Ads assigned identifier of an ad group. | ||
AdTitle | String | True | The ad title. | ||
AdExtensionType | String | True | The type name that corresponds to the AdExtensionTypeId column. | ||
AdExtensionVersion | String | The version attribute of an ad extension. | |||
AdExtensionId | Long | The identifier of the ad extension. | |||
AdId | Long | Ad Id | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
CampaignStatus | String | The campaign status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
ClickType | String | Click type refers to each component of an ad that a customer can click. | |||
TitlePart1 | String | The title part 1 attribute of an ad. | |||
TitlePart2 | String | The title part 2 attribute of an ad. | |||
TitlePart3 | String | The title part 3 attribute of an ad. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
TotalClicks | Integer | True | The number of billable and non-billable times that the ad extension was clicked. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AdExtensionByKeywordReport¶
Use this report to compare how well different versions of your ad extensions are performing for each keyword.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdExtensionType | String | True | The Bing Ads assigned identifier of an ad extension. | ||
AdExtensionId | Long | The version attribute of an ad extension. | |||
AdExtensionVersion | String | The version attribute of an ad extension. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignStatus | String | The campaign status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
ClickType | String | Click type refers to each component of an ad that a customer can click. | |||
Keyword | String | True | The keyword text. | ||
KeywordId | String | The Bing Ads assigned identifier of a keyword. | |||
KeywordStatus | String | The keyword status. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
TotalClicks | Integer | True | The number of billable and non-billable times that the ad extension was clicked. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AdExtensionDetailReport¶
Use this report to discover the effectiveness of individual ad extension items, for example, each link of a sitelink extension.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdTitle | String | The ad title. | |||
AdId | String | The Bing Ads assigned identifier of an ad. | |||
AdExtensionType | String | True | The Bing Ads assigned identifier of an ad extension. | ||
AdExtensionTypeId | String | True | The system identifier that corresponds to the AdExtensionType column. The supported identifiers are 10, 11, and 12. | ||
AdExtensionId | Long | True | The version attribute of an ad extension. | ||
AdExtensionVersion | String | The version attribute of an ad extension. | |||
AdExtensionPropertyValue | String | True | The human readable ad extension property value. For this report only one property is available for each type of ad extension. | ||
AdStatus | String | The ad status. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignStatus | String | The campaign status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | |
Clicks | Integer | True | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | |
Ctr | Double | True | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | |
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AdGroupPerformanceReport¶
Use this report to more broadly compare delivery performance statistics by ad group, campaign, or account attributes rather than at the keyword level.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
Status | String | The ad distribution attribute of an ad group. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
AdGroupName | String | The ad group name. | |||
AdGroupLabels | String | The labels applied to the ad group. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
TrackingTemplate | String | The current tracking template for the ad group. | |||
CustomParameters | String | The current custom parameters set for the ad group. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
AbsoluteTopImpressionSharePercent | Double | True | The number of times your ad is shown in the top position as a percentage of the total available impressions in the market you were targeting. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads. It is the share of the prospective customer's mindshare and buying intent you captured. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
ExactMatchImpressionSharePercent | Double | True | The estimated percentage of impressions that your account received for searches that exactly matched your keyword, out of the total available exact match impressions you were eligible to receive. | ||
ImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | ||
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankAggPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
QualityScore | Integer | True | The numeric score shows you how competitive your ads are in the marketplace by measuring how relevant your keywords and landing pages are to customers' search terms. | ||
ExpectedCtr | Integer | True | How well your keyword competes against other keywords targeting the same traffic. Ads that are relevant to searchers' queries or other input are more likely to have a higher click-through rate. This metric tells you if a keyword is underperforming and causing a loss in impression share, so you can make keyword changes or remove ads altogether. | ||
AdRelevance | Integer | True | How closely related your ads is to the customer's search query or other input. It tells you how relevant your ad and landing page are to potential customers. | ||
LandingPageExperience | Integer | True | An aggregate quality assessment of all landing pages on your site. The landing page experience score measures whether your landing page is likely to provide a good experience to customers who click your ad and land on your website. | ||
HistoricalQualityScore | Integer | True | The historic quality score of the keyword. The historic quality score for each row is the value that was calculated for quality score on that date. | ||
HistoricalExpectedCtr | Integer | True | Historical average of expected click-through rate scores going back as far as 18 months from the current date. This score may vary from the score in the ExpectedCtr column, which is the current score and same value for each day in the time period. | ||
HistoricalAdRelevance | Integer | True | Historical average of ad relevance scores back as far as 18 months from the current date. | ||
HistoricalLandingPageExperience | Integer | True | Historical average of landing page experience scores back as far as 18 months from the current date. | ||
PhoneImpressions | Integer | True | The number of times your tracked number was shown on all devices. | ||
PhoneCalls | Integer | True | The number of total calls to the tracked phone number that showed with your ad. The formula for calculating the phone calls is ManualCalls + ClickCalls. | ||
Ptr | Double | True | The phone-through rate (Ptr). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). | ||
AudienceImpressionLostToBudgetPercent | Double | True | The percentage of impression share you lost due to insufficient budget on the Microsoft Audience Network. | ||
AudienceImpressionLostToRankPercent | Double | True | The percentage of impression share you lost due to low rank on the Microsoft Audience Network. | ||
AudienceImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions you could have received on the Microsoft Audience Network. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AdGroups¶
Query the available AdGroups in Bing Ads.
Table Specific Information¶
Select¶
You must specify the CampaignId column in the WHERE clause to query this table. The connector will use the Microsoft Ads API to filter the results by CampaignId while the rest of the filter is executed client side within the connector.
For example, the following query is processed server side:
SELECT * FROM [AdGroups] WHERE CampaignId = '234505536'
The client-side execution of the query can be turned off by setting SupportEnhancedSQL
to false in which case any search criteria with columns in the WHERE clause other than CampaignId will cause an error.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The system generated identifier of the ad group. | |||
CampaignId | Long | The system generated identifier of the campaign. | |||
Name | String | The name of the ad group. | |||
AdRotationType | String | Determines how often you'd like the ads in your ad group to show in relation to one another. If you have multiple ads within an ad group, your ads will rotate because no more than one ad from your account can show at a time. | |||
StartDate | Date | The date that the ads in the ad group can begin serving; otherwise, the service can begin serving the ads in the ad group the day that the ad group becomes active. | |||
EndDate | Date | The date that the ads in the ad group will expire. | |||
Language | String | The language of the ads and keywords in the ad group. | |||
CpcBidAmount | Double | The default bid to use when the user's query and the ad group's keywords match by using either a broad, exact, or phrase match comparison.. | |||
AudienceAdsBidAdjustment | String | The percent amount by which to adjust your bid for native ads above or below the base ad group or keyword bid. | |||
BiddingSchemeType | String | The bid strategy type for how you want to manage your bids. | |||
ForwardCompatibilityMap | String | The list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases. | |||
Network | String | The search networks where you want your ads to display. | |||
Status | String | The status of the ad group. | |||
TrackingUrlTemplate | String | The tracking template to use as a default for all URLs in your ad group. | |||
UrlCustomParameters | String | Your custom collection of key and value parameters for URL tracking. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
AdPerformanceReport¶
Use this report to help you determine which ads lead to clicks and conversions, and which are not performing. Having underperforming ads in your account can pull down the quality of your campaigns.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdLabels | String | The labels applied to the ad. | |||
AdGroupName | String | The ad group name. | |||
AdId | Long | The Bing Ads Ad identifier | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdTitle | String | The ad title. | |||
AdDescription | String | The text attribute of an ad. | |||
AdDescription2 | String | The second ad description that appears below the path in your ad. Ad description 2 might not appear in your ad. | |||
AdType | String | The ad type. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
TrackingTemplate | String | The current tracking template of the ad, keyword, or criterion. | |||
CustomParameters | String | The current custom parameters set of the ad, keyword, or criterion. | |||
FinalUrl | String | The Final URL of the ad, keyword, or criterion. | |||
FinalMobileUrl | String | The Final Mobile URL of the ad, keyword, or criterion. | |||
FinalAppUrl | String | Reserved for future use. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
Headline | String | The shorter of two possible responsive ad headlines for Audience campaigns. | |||
LongHeadline | String | The longer of two possible responsive ad headlines for Audience campaigns. | |||
TitlePart1 | String | The title part 1 attribute of an ad. | |||
TitlePart2 | String | The title part 2 attribute of an ad. | |||
TitlePart3 | String | The title part 3 attribute of an ad. | |||
Path1 | String | The path 1 attribute of an ad. | |||
Path2 | String | The path 2 attribute of an ad. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
DisplayUrl | String | The ad display URL. | |||
BusinessName | String | Depending on your responsive ad's placement, your business's name may appear in your ad. This column only applies to Audience campaigns. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. The possible values include Android, Blackberry, iOS, Other, Unknown, and Windows. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. If the destination URL contains dynamic text substitution parameters (for example, {param1}), the report will contain the URL after substitution occurs. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. The possible values are Broad, Exact, Phrase, and Unknown. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Ads¶
Query the available Ads in Bing Ads.
Table Specific Information¶
Select¶
You must specify the AdGroupId
and Type
columns in the WHERE clause to query this table. The connector uses the Microsoft Ads API to filter the results by AdGroup
and Type
, while the rest of the filter is executed client side within the connector.
For example, the following query is processed server side:
SELECT * FROM [Ads] WHERE AdGroupId = '5179946006' AND Type = 'Text'
SELECT * FROM Ads WHERE AdGroupId = '1297424037031698' AND Type = 'DynamicSearch' AND AccountId = '135093022'
SELECT * FROM Ads WHERE AdGroupId = '1302921473177959' AND Type = 'Text' AND AccountId IN ('2562405', '141163457', '180394748')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The unique Bing Ads identifier for the ad. | |||
AdGroupId | Long | The system generated identifier of the ad group. | |||
Type | String | The ad type. One of Text, Image, Product, AppInstall, ExpandedText, DynamicSearch | |||
Title | String | The title of the ad. The title must contain at least one word. The ad's copy and title combined must total at least three words. | |||
TitlePart1 | String | The first title part of the ad. | |||
TitlePart2 | String | The second title part of the ad. | |||
Text | String | The ad copy. The copy must contain at least one word. The ad's copy and title combined must total at least three words. | |||
Domain | String | The URL to display in the ad. | |||
DestinationUrl | String | The URL of the webpage to take the user to when they click the ad. | |||
UrlCustomParameters | String | Your custom collection of key and value parameters for URL tracking. | |||
TrackingUrlTemplate | String | The tracking template to use as a default for all landing page URLs. | |||
Status | String | The status of the ad. | |||
ForwardCompatibilityMap | String | The list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases. | |||
FinalUrls | String | The last or final URL where a user is ultimately taken, whether or not the click to final URL path included any redirects. | |||
FinalMobileUrls | String | The mobile landing page URL. | |||
FinalAppUrls | String | Reserved for future use. | |||
EditorialStatus | String | The editorial review status of the ad, which indicates whether the ad is pending review, has been approved, or has been disapproved. | |||
DevicePreference | Integer | Determines the device preference for showing the ad. | |||
AdFormatPreference | String | The Ad Format Preference is used to indicate whether or not you prefer the ad copy to be shown to users as a search or native ad. Search ads tend to be written as a call to action, whereas native ads should be written in more of an informational style. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
AgeGenderAudienceReport¶
Use this report to discover how your campaigns and ad groups are resonating with audiences of diverse age and gender.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Microsoft Advertising assigned number of an account. | |||
AccountId | Long | The Microsoft Advertising assigned identifier of an account. | |||
AdGroupId | Long | The Microsoft Advertising assigned identifier of an ad group. | |||
CampaignId | Long | The Microsoft Advertising assigned identifier of a campaign. | |||
AdGroupName | String | True | The ad group name. | ||
CampaignName | String | The campaign name. | |||
AdDistribution | String | The network where you want your ads to show. | |||
Gender | String | True | The gender (male or female) of the search users to whom the ad was delivered.. | ||
AgeGroup | String | True | The age group of the audience who viewed the ad. The possible values are 13-17, 18-24, 25-34, 35-49, 50-64, and 65+. | ||
Language | String | This is the language of the country the ad is served in. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
AllConversions | Double | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. | |||
AllRevenue | Decimal | The revenue optionally reported by the advertiser as a result of conversions. | |||
Assists | Integer | The number of times an entity (an account, campaign, ad group, or keyword, for example) contributed to a conversion that is associated with a different entity. | |||
BaseCampaignId | Long | The Microsoft Advertising assigned identifier of an experiment campaign. This will be the same value as the CampaignId if the campaign is not an experiment. | |||
Impressions | Long | True | The number of times an ad has been displayed on search results pages or other sites on the Audience Network. | ||
Clicks | Integer | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. | |||
Conversions | Integer | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. | |||
ExtendedCost | Decimal | Cost information that is optionally provided by advertisers, including non-advertising costs, taxes, and shipping. | |||
Revenue | Decimal | The revenue optionally reported by the advertiser as a result of conversions. | |||
Spend | Decimal | The sum of your cost-per-click (CPC) charges for your ads and keywords. Spend helps you keep track of your budget. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
AudiencePerformanceReport¶
Use this report to compare delivery performance statistics by audience, ad group, campaign, or account attributes.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | True | The Bing Ads assigned identifier of an account. | ||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AudienceId | Long | True | The Bing Ads assigned identifier of the audience, for example the remarketing list ID. | ||
AudienceName | String | The audienc name. | |||
AudienceType | String | The audience type. | |||
AssociationStatus | String | The status of the association between the ad group and remarketing list, which indicates whether ads are eligible to display. The possible values are Active, Paused, and Deleted. | |||
BidAdjustment | String | This attribute reflects the current value of your ad group's audience bid adjustment, even if a different bid adjustment value was used when the ad was shown. This value is the requested percentage to increase or decrease the bid amount for the remarketing list. | |||
TargetingSetting | String | This attribute reflects the current value of your ad group's audience targeting setting. The possible values are Target and bid or Bid only. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Audiences¶
Query the available Audiences in Bing Ads.
Table Specific Information¶
Select¶
Searches on this table are processed client-side by the connector; the following query is executed server-side.
SELECT * FROM [Audiences]
SELECT * FROM Audiences WHERE AccountId = '65098547' AND Type = 'RemarketingList'
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The Bing Ads identifier of the audience. | |||
ParentId | Long | The Bing Ads identifier of the account or customer. | |||
Name | String | The name of the audience. The name can contain a maximum of 128 characters. | |||
Type | String | The type of the audience. The allowed values are RemarketingList, Custom, InMarket. | |||
Description | String | The description of the audience. Use a description to help you remember what audience you are targeting. | |||
MembershipDuration | Integer | When you create an audience, you can specify how far back in time Bing Ads should look for actions that match your audience definition. | |||
ForwardCompatibilityMap | String | The list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases. | |||
Scope | String | Scope defines what accounts can use this audience. The allowed values are Account, Customer. | |||
TagId | Long | The unique Bing Ads identifier of the tag. | |||
AudienceNetworkSize | Long | The total number of people who are active members of this audience in the Audience network. | |||
SearchSize | Long | The total number of people who are active members of this audience in the Search network. | |||
SupportedCampaignTypes | String | The list of campaign types that support this audience. | |||
CustomerShareAggregate | String | True | Contains information about CustomerAccountShares and OwnerCustomerId. | ||
AccountId | Long | The Bing Ads assigned identifier of an account. |
BidOpportunities¶
Query the available Bid Opportunities in Bing Ads.
Table Specific Information¶
Select¶
You must specify the OpportunityType column in the WHERE clause to query this table. You can specify the following values for OpportunityType: FirstPage, MainLine, and MainLine1.
The connector will use the Microsoft Ads API to filter the results by OpportunityType while the rest of the filter is executed client side within the connector. For example, the following query is processed server side.
SELECT * FROM [ BidOpportunities ] WHERE OpportunityType = 'FirstPage'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than OpportunityType will cause an error.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
OpportunityKey | String | An identifier that uniquely identifies the opportunity. | |||
AdGroupId | Long | The identifier of the ad group that owns the keyword. | |||
CampaignId | Long | The identifier of the campaign for the ad group that owns the keyword. | |||
OpportunityType | String | Defines the possible bid opportunity types you can request when calling GetBidOpportunities. Avaiable values are: FirstPage, MainLine and MainLine1. The default value is FirstPage. | |||
CurrentBid | Double | The current keyword bid amount specified for the match type in the MatchType element. | |||
EstimatedIncreaseInClicks | Double | The estimated clicks opportunities corresponding to the suggested bid. | |||
EstimatedIncreaseInCost | Double | The estimated increase in spend corresponding to the suggested bid. | |||
EstimatedIncreaseInImpressions | Long | The estimated impressions opportunities corresponding to the suggested bid. | |||
KeywordId | Long | The identifier of the keyword to which the bid opportunity applies. | |||
MatchType | String | The match type to which the suggested bid value applies. The possible values are BroadMatch, ExactMatch, and PhraseMatch. | |||
SuggestedBid | Double | The suggested bid based on the last 7 days of performance history for the corresponding ad group. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
BudgetOpportunities¶
Query the available Budget Opportunities in Bing Ads.
Table Specific Information¶
Select¶
You must specify the CampaignId column in the WHERE clause to query this table. The connector will use the Microsoft Ads API to filter the results by CampaignId while the rest of the filter is executed client side within the connector.
For example, the following query is processed server side:
SELECT * FROM [ BudgetOpportunities ] WHERE CampaignId = '234505536'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria in the WHERE clause that refers to columns other than CampaignId will cause an error.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
OpportunityKey | String | An identifier that uniquely identifies the opportunity. | |||
BudgetAmount | Double | A potential new budget. | |||
BudgetPointType | String | The type of budget relative to a list of budget points. For example, if the budget point type is Current then this object's BudgetAmount element would be equal to the corresponding campaign's daily budget. | |||
EstimatedWeeklyClicks | Double | The estimated weekly clicks for the given budget amount. | |||
EstimatedWeeklyCost | Double | The estimated weekly cost for the given budget amount. | |||
EstimatedWeeklyImpressions | Double | The estimated weekly impressions for the given budget amount. | |||
BudgetType | String | The type of budget that the campaign uses. | |||
CampaignId | Long | The identifier of the campaign to which the suggested budget applies | |||
CurrentBudget | Double | The campaign's current budget. | |||
IncreaseInClicks | Double | The estimated clicks opportunities corresponding to the suggested budget. | |||
IncreaseInImpressions | Double | The estimated impressions opportunities corresponding to the suggested budget. | |||
PercentageIncreaseInClicks | Integer | The estimated percentage increase in clicks corresponding to the suggested budget. | |||
PercentageIncreaseInImpressions | Integer | The estimated percentage increase in impressions corresponding to the suggested budget. | |||
RecommendedBudget | Double | The suggested budget based on the last 15 days of performance history for the corresponding campaign. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
Budgets¶
Query the available Budgets in Bing Ads.
Table Specific Information¶
Select¶
Searches on this table are processed client-side by the connector; the following query is processed server-side:
SELECT * FROM [Budgets]
SELECT * FROM Budgets WHERE CampaignId = '431046229' AND AccountId = '65098547'
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The unique Bing Ads identifier of the budget. | |||
CampaignId | Long | The system generated identifier of the campaign. | |||
Name | String | The name of the budget. The name must be unique among all budgets within the account. The name can contain a maximum of 255 characters. | |||
Amount | Double | The amount to spend daily across all campaigns that share the budget. | |||
AssociationCount | Integer | The number of Campaign objects that currently share this budget. | |||
BudgetType | String | The budget type determines the pace at which the budget is spent throughout the day. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
BudgetSummaryReport¶
Use this report to discover how your campaign's budget is performing for the month. For example, the report shows your monthly budget, how much you have spent to date, and whether you are on target to spend your monthly budget.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
AccountName | String | True | The account name. | ||
AccountNumber | String | True | The Bing Ads assigned number of an account. | ||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | True | The campaign name. | ||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
Date | String | True | The date for the downloaded report records. The date will be in the time zone of the campaign. | ||
CurrencyCode | String | True | The account currency type. | ||
MonthlyBudget | String | The average amount of campaign budget spent during a calendar month. | |||
DailySpend | String | True | The average amount of campaign budget spent per day. | ||
MonthToDateSpend | String | The amount of money spent to date for the month. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisMonth, LastMonth. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
CampaignPerformanceReport¶
Use this report to view high-level performance statistics and quality attributes for each campaign or account. This is also a quick way to flag any major campaign or account problems.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AccountStatus | String | The account status. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
CampaignLabels | String | The labels applied to the campaign. | |||
CampaignStatus | String | The campaign status. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
BudgetName | String | The name of the budget. | |||
BudgetStatus | String | The budget status. The possible values are Active and Deleted. | |||
BudgetAssociationStatus | String | Indicates whether or not the campaign is currently spending from the budget mentioned in the BudgetName column. The possible values are Current and Ended. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
TrackingTemplate | String | The current tracking template for the ad group. | |||
CustomParameters | String | The current set of custom parameters for the campaign. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
AbsoluteTopImpressionSharePercent | Double | True | The number of times your ad is shown in the top position as a percentage of the total available impressions in the market you were targeting. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads.It is the share of the prospective customer's mindshare and buying intent you captured. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
LowQualityClicks | Integer | True | Clicks that exhibit a low likelihood of commercial intent. You are not billed for these clicks. | ||
LowQualityClicksPercent | Double | True | The low-quality clicks as a percentage. | ||
LowQualityImpressions | Integer | True | The number of impressions that result from low-quality keyword searches. | ||
LowQualityImpressionsPercent | Double | True | The low-quality impressions as a percentage. | ||
LowQualityConversions | Integer | True | The number of conversions that originate from low-quality clicks. | ||
LowQualityConversionRate | Double | True | The low-quality conversion rate as a percentage. | ||
ExactMatchImpressionSharePercent | Double | True | The estimated percentage of impressions that your account received for searches that exactly matched your keyword, out of the total available exact match impressions you were eligible to receive. | ||
ImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | ||
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankAggPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
QualityScore | Integer | True | The numeric score shows you how competitive your ads are in the marketplace by measuring how relevant your keywords and landing pages are to customers' search terms. | ||
ExpectedCtr | Integer | True | How well your keyword competes against other keywords targeting the same traffic. Ads that are relevant to searchers' queries or other input are more likely to have a higher click-through rate. This metric tells you if a keyword is underperforming and causing a loss in impression share, so you can make keyword changes or remove ads altogether. | ||
AdRelevance | Integer | True | How closely related your ads is to the customer's search query or other input. It tells you how relevant your ad and landing page are to potential customers. | ||
LandingPageExperience | Integer | True | An aggregate quality assessment of all landing pages on your site. The landing page experience score measures whether your landing page is likely to provide a good experience to customers who click your ad and land on your website. | ||
HistoricalQualityScore | Integer | True | The historic quality score of the keyword. The historic quality score for each row is the value that was calculated for quality score on that date. | ||
HistoricalExpectedCtr | Integer | True | Historical average of expected click-through rate scores going back as far as 18 months from the current date. This score may vary from the score in the ExpectedCtr column, which is the current score and same value for each day in the time period. | ||
HistoricalAdRelevance | Integer | True | Historical average of ad relevance scores back as far as 18 months from the current date. | ||
HistoricalLandingPageExperience | Integer | True | Historical average of landing page experience scores back as far as 18 months from the current date. | ||
PhoneImpressions | Integer | True | The number of times your tracked number was shown on all devices. | ||
PhoneCalls | Integer | True | The number of total calls to the tracked phone number that showed with your ad. The formula for calculating the phone calls is ManualCalls + ClickCalls. | ||
Ptr | Double | True | The phone-through rate (Ptr). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). | ||
LowQualityGeneralClicks | Double | True | Clicks that are filtered by general methods, such as blacklists and activity-based detection, and that exhibit a low likelihood of commercial intent. You are not billed for these clicks. | ||
LowQualitySophisticatedClicks | Double | True | Invalid clicks that use sophisticated means to appear valid. You are not billed for these clicks. For more information, see Bing Ads click measurement: description of methodology. | ||
AudienceImpressionLostToBudgetPercent | Double | True | The percentage of impression share you lost due to insufficient budget on the Microsoft Audience Network. | ||
AudienceImpressionLostToRankPercent | Double | True | The percentage of impression share you lost due to low rank on the Microsoft Audience Network. | ||
AudienceImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions you could have received on the Microsoft Audience Network. | ||
TopImpressionSharePercent | Double | True | The percentage of impressions for your ad in the mainline, the top ad placements above the search results, out of the estimated number of mainline impressions you were eligible to receive. | ||
TopImpressionRatePercent | Double | True | The percentage of times your ad showed in the mainline, the top placement where ads appear above the search results, out of your total impressions. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Campaigns¶
Query the available Campaigns in Bing Ads.
Table Specific Information¶
Select¶
Searches on this table are processed client-side by the connector; the following query is processed server-side:
SELECT * FROM [ Campaigns ]
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The unique Bing Ads identifier of the campaign. | |||
AccountId | String | The unique Bing Ads identifier of the account associated with this campaign. | |||
CampaignType | String | The campaign type determines whether the campaign is an Audience, Dynamic Search Ads, Search, Shopping or Search & Content campaign. The allowed values are Search, Shopping, DynamicSearchAds, Audience. | |||
Name | String | The name of the campaign. The name must be unique among all active or paused campaigns within the account. | |||
Status | String | The status of the campaign. The allowed values are Active, Paused. | |||
SubType | String | The campaign sub type. This element is only applicable for campaigns of type Shopping, and will be nil for all other campaign types. | |||
BiddingSchemeType | String | The bid strategy type for how you want to manage your bids. The allowed values are EnhancedCpc, InheritFromParent, ManualCpc, MaxClicks, MaxConversions, TargetCpa. | |||
BudgetType | String | The budget type determines how the budget is spent. The allowed values are DailyBudgetAccelerated, DailyBudgetStandard. | |||
DailyBudget | Double | The amount to spend daily on the campaign. You must set the daily budget amount if BudgetId is not set. | |||
ExperimentId | Long | The system generated identifier of the Experiment. | |||
TimeZone | String | The time zone where the campaign operates. | |||
TrackingUrlTemplate | String | The tracking template to use as a default for all URLs in your campaign. | |||
UrlCustomParameters | String | Your custom collection of key and value parameters for URL tracking. | |||
BudgetId | Long | The unique Bing Ads identifier of the Budget that this campaign shares with other campaigns in the account. | |||
AudienceAdsBidAdjustment | Integer | The percent amount by which to adjust your bid for audience ads above or below the base ad group or keyword bid. | |||
Languages | String | The languages of the ads and keywords in the campaign. |
ConversionPerformanceReport¶
Use this report to understand which campaigns and keywords are leading an audience to complete a purchase or other conversion action.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdGroupName | String | The ad group name. | |||
CampaignName | String | The campaign name. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
KeywordStatus | String | The keyword status. | |||
KeywordId | Long | The Bing Ads assigned identifier of a keyword. | |||
Keyword | String | The keyword text. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
DestinationUrlPerformanceReport¶
Use this report to identify landing pages that met audience expectations and potentially resulted in high click-through or conversion rates.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | True | The campaign name. | ||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdId | Long | Ad Id | |||
DestinationUrl | String | True | The destination URL attribute of the ad, keyword, or ad group criterion. | ||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
FinalUrl | String | The Final URL of the ad, keyword, or criterion. | |||
FinalMobileUrl | String | The Final Mobile URL of the ad, keyword, or criterion. | |||
FinalAppUrl | String | Reserved for future use. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
CampaignStatus | String | The campaign status. | |||
TrackingTemplate | String | The current tracking template for the ad group. | |||
CustomParameters | String | The current set of custom parameters for the campaign. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
DSAAutoTargetPerformanceReport¶
Use this report to find out which DSA auto targets are performing well and those that are not.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
CampaignStatus | String | The campaign status. | |||
DynamicAdTarget | String | True | The dynamic ad target or webpage condition that Bing matched to your website. For example the condition could be returned in the report as URL contains xyz. | ||
DynamicAdTargetStatus | String | The current status of the dynamic ad target. | |||
DynamicAdTargetId | Long | The Bing Ads assigned identifier of the dynamic ad target, also known in Campaign Management and Bulk API as the ad group criterion ID. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
AdGroupName | String | The ad group name. | |||
AdGroupStatus | String | The ad group status. | |||
Language | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidStrategyType | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
TrackingTemplate | String | The current tracking template of the ad. | |||
CustomParameters | String | The current custom parameters of the ad. | |||
WebsiteCoverage | String | A score from 0.0 to 1.0 that indicates the percentage of pages in the requested language that belong to a particular domain out of all the pages that Bing has indexed for the same language your website's domain. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
DSACategoryPerformanceReport¶
Use this report to find out which DSA categories are performing well and those that are not.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdId | Long | The Bing Ads assigned identifier of an ad. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupName | String | The ad group name. | |||
Language | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
Category0 | String | True | The top level category that Bing matched to your website. For example if the category is US/CA/SFO, the Category0 value will be US. | ||
Category1 | String | True | The mid level category that Bing matched to your website. For example if the category is US/CA/SFO, the Category0 value will be US. | ||
Category2 | String | True | The low level category that Bing matched to your website. For example if the category is US/CA/SFO, the Category0 value will be US. | ||
CampaignName | String | The campaign name. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
DSASearchQueryPerformanceReport¶
Use this report to find out which search terms are in demand for your DSA campaign and the performance of dynamic headlines that are being displayed.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdId | Long | The Bing Ads assigned identifier of an ad. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupName | String | The ad group name. | |||
Language | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
CampaignName | String | The campaign name. | |||
AdGroupStatus | String | The ad group status. | |||
AdStatus | String | The ad status. | |||
SearchQuery | String | True | The search term used by your potential audience. | ||
Headline | String | The Dynamic Search Ad headline that was dynamically generated by Bing Ads. | |||
CategoryList | String | The list of categories that Bing matched to your website. Up to three category levels can be returned per category list item. | |||
LandingPageTitle | String | The title of your webpage where the search user landed. | |||
FeedUrl | String | The feed URL will appear either as | |||
FinalUrl | String | The URL address of the page on your website that people reach when they click your ad from a desktop or laptop. | |||
DynamicAdTarget | String | The dynamic ad target or webpage condition that Bing matched to your website. For example the condition could be returned in the report as URL contains xyz. | |||
DynamicAdTargetId | String | The Bing Ads assigned identifier of the dynamic ad target, also known in Campaign Management and Bulk API as the ad group criterion ID. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
GeographicPerformanceReport¶
Use this report to see which locations your traffic is coming from. You can then validate whether your location targeting strategy is successful, and identify opportunities to improve. The report also identifies either the physical location of the search user or the geographical location interest based on the user's search query.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdGroupName | String | The ad group name. | |||
CampaignName | String | The campaign name. | |||
Language | String | The ad group language. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
Country | String | The country where the user was physically located when they clicked the ad. | |||
State | String | The state where the user was physically located when they clicked the ad. | |||
MetroArea | String | The metro area where the user was physically located when they clicked the ad. | |||
City | String | The city where the user was physically located when they clicked the ad. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
ProximityTargetLocation | String | The radius target bid name. The name of the geographic radius where the user was physically located when they clicked the ad. | |||
Radius | String | The radius of a radius target bid. The geographic radius where the user was physically located when they clicked the ad. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. For more information, see Budget and Bid Strategies. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. For more information, see Budget and Bid Strategies. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
LocationType | String | The location type used to deliver ads. For example to distinguish between people in versus searching for or viewing pages about the corresponding location of interest. | |||
MostSpecificLocation | String | The most specific location used to deliver ads. For example if the city and country are both identified, this column will include the same value as the City column. If postal code information is available, then it will be included in the report instead of city or country. | |||
County | String | The county where the user was physically located when they clicked the ad. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
LocationId | Long | The Bing Ads identifier of the location where the user was physically located when they clicked the ad. For geographical location identifiers, see Geographical Location Codes. | |||
PostalCode | String | The postal code where the user was physically located when they clicked the ad. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
GoalsAndFunnelsReport¶
Use this report to discover whether your audience completes each step through the land, browse, prospect, and conversion pages of your website. For example, you can use this report to determine the step that users leave the conversion funnel, so that you can improve or remove that step to increase the chance that the user will continue to the next step.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdGroupName | String | The ad group name. | |||
CampaignName | String | The campaign name. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
Keyword | String | The keyword text. | |||
KeywordStatus | String | The keyword status. | |||
KeywordId | String | The Bing Ads assigned identifier of a keyword. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
Goal | String | True | The name of your event tracking or campaign analytics goal. | ||
GoalId | String | The Bing Ads assigned identifier of a goal. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
AllConversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
AllRevenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
KeywordDemographics¶
Query the available Keyword Demographics in Bing Ads.
Table Specific Information¶
Select¶
You must specify the Keywords, Language, and PublisherCountry columns in the WHERE clause to query this table. You can search on multiple keywords by setting the Keywords column value to a comma-separated list in the WHERE clause.
The connector will use the Microsoft Ads API to filter the results by Keywords, Language, and PublisherCountry while the rest of the filter is executed client side within the connector. For example, the following query is processed server side.
SELECT * FROM [ KeywordDemographics ] WHERE Keywords = 'Gmail Excel,PowerShell Excel' AND Language = 'English' AND PublisherCountry = 'US'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than Keywords, Language, and PublisherCountry will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Keywords | String | List of Keywords. Use to filter the table. | |||
Language | String | The language in which the keywords are written. | |||
PublisherCountry | String | The country code of the country/region to use as the source of the demographics data. The country/region that you specify must support the language specified in the Language element. | |||
Device | String | The device of the user who entered the search query. Default value is 'Computers'. The allowed values are Computers, NonSmartphones, Smartphones, Tablets. | |||
Keyword | String | The keyword. | |||
Age18to24 | Double | The percentage of time that users 18 through 24 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
Age25to34 | Double | The percentage of time that users 25 through 34 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
Age35to49 | Double | The percentage of time that users 35 through 49 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
Age50to64 | Double | The percentage of time that users 50 through 64 years of age searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
Age65Plus | Double | The percentage of time that users 65 years of age or older searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
AgeUnknown | Double | Not used. | |||
Female | Double | The percentage of time that female users searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
Male | Double | The percentage of time that male users searched for the keyword. The value is specified in the range 0.0 through 1.0. | |||
GenderUnknown | Double | Not Used. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordEstimatedBid¶
Query the available Keyword Estimated Bid in Bing Ads.
Table Specific Information¶
Select¶
You must set the KeywordText and MatchType columns in the WHERE clause to query this table. Set the MatchType column to one of the following values in the WHERE clause: Exact, Phrase, Broad, Content, or Aggregate.
The connector will use the Microsoft Ads API to filter the results by KeywordText and MatchType while the rest of the filter is executed client side within the connector.
For example, the following query is processed server side.
SELECT * FROM [ KeywordEstimatedBid ] WHERE KeywordText = 'SAP R/3 Developers' AND MatchType = 'Exact'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than KeywordText and MatchType will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
KeywordText | String | The keyword text. | |||
MatchType | String | The keyword match type used to determine the estimates. Can be one of Exact, Phrase, Broad, Aggregate. | |||
CurrencyCode | String | The monetary unit of the cost values, such as AverageCPC. | |||
CampaignId | Long | The system generated identifier of the campaign. | |||
AdGroupId | Long | The system generated identifier of the ad group. | |||
MinClicksPerWeek | Double | The estimated minimum number of clicks per week. | |||
MaxClicksPerWeek | Double | The estimated maximum number of clicks per week. | |||
AverageCPC | Double | The estimated average CPC. | |||
MinImpressionsPerWeek | Long | The estimated minimum number of impressions per week. | |||
MaxImpressionsPerWeek | Long | The estimated maximum number of impressions per week. | |||
ClickThroughRate | Double | The estimated CTR. | |||
MinTotalCostPerWeek | Double | The estimated minimum cost per week. | |||
MaxTotalCostPerWeek | Double | The estimated maximum cost per week. | |||
EstimatedMinBid | Double | The position in the search results given the specified bid. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordEstimatedPosition¶
Query the available EstimatedPosition in Bing Ads.
Table Specific Information¶
Select¶
You must specify the Keywords and MatchType columns in the WHERE clause to query this table. Set MatchType to one of the following values: Exact, Phrase, Broad, Content and Aggregate. You can search on multiple keywords by setting the Keywords column value to a comma-separated list in the WHERE clause.
The connector will use the Microsoft Ads API to filter the results by KeywordText and MatchType while the rest of the filter is executed client side within the connector. For example, the following query is processed server side.
SELECT * FROM [KeywordEstimatedPosition] WHERE Keywords = 'SAP development,PowerShell Excel' AND MatchType = 'Exact'
SELECT * FROM KeywordEstimatedPosition WHERE Keywords = 'ssh transfer' AND MatchType = 'Exact' AND AccountId = '135093022' AND MaxBid = 50
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than Keywords and MatchType will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Keywords | String | List of Keywords. Use to filter the table. | |||
MaxBid | Long | The maximum bid value to use to determine the estimated position in the search results. | |||
MatchType | String | The keyword match type used to determine the estimates. Can be one of Exact, Phrase, Broad, Aggregate. | |||
CurrencyCode | String | The monetary unit of the cost values, such as AverageCPC. | |||
CampaignId | Long | The system generated identifier of the campaign. | |||
AdGroupId | Long | The system generated identifier of the ad group. | |||
Keyword | String | The keyword. | |||
MinClicksPerWeek | Double | The estimated minimum number of clicks per week. | |||
MaxClicksPerWeek | Double | The estimated maximum number of clicks per week. | |||
AverageCPC | Double | The estimated average CPC. | |||
MinImpressionsPerWeek | Long | The estimated minimum number of impressions per week. | |||
MaxImpressionsPerWeek | Long | The estimated maximum number of impressions per week. | |||
ClickThroughRate | Double | The estimated CTR. | |||
MinTotalCostPerWeek | Double | The estimated minimum cost per week. | |||
MaxTotalCostPerWeek | Double | The estimated maximum cost per week. | |||
EstimatedAdPosition | Double | The position in the search results given the specified bid. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordHistoricalSearch¶
Query the available Keyword Historical Search in Bing Ads.
Table Specific Information¶
Select¶
You must specify the Keywords, Language, StartDate, and EndDate columns to query this table. You can search on multiple keywords by setting the Keywords column value to a comma-separated list in the WHERE clause.
The connector will use the Microsoft Ads API to filter the results by Keywords, Language, StartDate, and EndDate while the rest of the filter is executed client side within the connector. For example,
SELECT * FROM [ KeywordHistoricalSearch ] WHERE Keywords = 'SAP development' AND Language = 'English' AND StartDate = '2014-01-01' AND EndDate = '2017-01-01'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than Keywords, Language, StartDate, and EndDate will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Keywords | String | List of Keywords. Use to filter the table. | |||
Language | String | The language in which the keywords are written. | |||
StartDate | Date | The start date of the date range that identifies the data that you want to use to determine the historical search count. | |||
EndDate | Date | The end date of the date range that identifies the data that you want to use to determine the historical search count. | |||
Keyword | String | The keyword. | |||
SearchCount | Long | The number of times that the keyword was used in a search query on the specified device type during the time period. The count aggregates data from all specified countries. | |||
SearchDate | Date | The time period in which the count was captured. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordLocations¶
Query the available Keyword Locations in Bing Ads.
Table Specific Information¶
Select¶
You must specify the Keywords and Language columns in the WHERE clause to query this table. You can search on multiple keywords by setting the Keywords column value to a comma-separated list.
The connector will use the Microsoft Ads API to filter the results by Keywords and Language while the rest of the filter is executed client side within the connector. For example, the following query is processed server side.
SELECT * FROM [ KeywordLocations ] WHERE Keywords = 'SAP development,PowerShell Excel' AND Language = 'English'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than Keywords and Language will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Keywords | String | List of Keywords. Use to filter the table. | |||
Language | String | The language in which the keywords are written. | |||
Device | String | The device of the user who entered the search query. | |||
Keyword | String | The keyword. | |||
Location | String | The country, state, metropolitan area, or city where users entered the search query. | |||
Percentage | Double | The percentage of time that users searched for the keyword from the location. The value is specified in the range 0.0 through 100.0 | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordPerformance¶
Query the available Keyword Performance in Bing Ads.
Table Specific Information¶
Select¶
You must specify the Keywords, MatchType, Language, and PublisherCountry columns in the WHERE clause to query this table. Set the MatchType column to one of the following in the WHERE clause: Exact, Phrase, Broad, Content, or Aggregate.
The connector will use the Microsoft Ads API to filter the results by Keywords, MatchType, Language, and PublisherCountry while the rest of the filter is executed client side within the connector. For example, the preceding query is processed on the server.
SELECT * FROM [ KeywordPerformance ] WHERE Keywords = 'SAP development,PowerShell Excel' AND Language = 'English' AND PublisherCountry = 'US' AND MatchType = 'Exact'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false in which case any search criteria that refers to columns other than Keywords, Language, PublisherCountry, and MatchType will cause an error.
Filtering by accountid
You can filter by accountid using the IN condition. For example,
SELECT * FROM KeywordEstimatedBid
WHERE KeywordText IN ('Text', 'Gmail')
AND MatchType = 'Exact'
AND AccountId IN ('141163452', '2562405', '141163453', '141163454', '141163455', '141163456', '141163457')
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Keywords | String | List of Keywords. Use to filter the table. | |||
AdPosition | String | The position in the search results in which the ad appeared. | |||
MatchType | String | The match type that you specified in the request. | |||
Language | String | The language in which the keywords are written. | |||
PublisherCountry | String | The country code of the country/region to use as the source of the demographics data. The country/region that you specify must support the language specified in the Language element. | |||
Device | String | The device of the user who entered the search query. Default value is 'Computers'. The allowed values are Computers, NonSmartphones, Smartphones, Tablets. | |||
Keyword | String | The keyword. | |||
Clicks | Integer | The number of clicks that the keyword and match type generated during the specified time interval. | |||
Impressions | Long | The number of impressions that the keyword and match type generated during the specified time interval. | |||
AverageCPC | Double | The average cost per click (CPC). The average CPC is calculated by dividing the cost of all clicks by the number of clicks. | |||
ClickThroughRate | Double | The click-through rate (CTR) as a percentage. The CTR is calculated by dividing the number of clicks by the number of impressions and multiplying the result by 100. | |||
TotalCost | Double | The cost of using the specified keyword and match type during the specified time interval. | |||
AverageBid | Double | The average bid of the keyword. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
KeywordPerformanceReport¶
Use this report to find out which keywords are performing well and those that are not.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
Keyword | String | The keyword text. | |||
KeywordId | Long | The Bing Ads assigned identifier of a keyword. | |||
KeywordLabels | String | The labels applied to the keyword. | |||
AdId | Long | Ad Id | |||
AdType | String | The ad type. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. | |||
CurrentMaxCpc | String | The maximum cost per click bid that was in effect at the time the report was generated. It is not a moving historical bid throughout the report time period. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
FinalUrl | String | The Final URL of the ad, keyword, or criterion. | |||
FinalMobileUrl | String | The Final Mobile URL of the ad, keyword, or criterion. | |||
FinalAppUrl | String | Reserved for future use. | |||
FirstPageBid | Decimal | Based on your campaign performance and marketplace dynamics, this estimate is the bid amount that Bing Ads calculates for your ad to be placed on the first page in the search results. | |||
Mainline1Bid | Decimal | Based on your campaign performance and marketplace dynamics, this estimate is the bid amount that Bing Ads calculates will place your ad at the top of search results. | |||
MainlineBid | Decimal | Based on your campaign performance and marketplace dynamics, this estimate is the bid amount that Bing Ads calculates for your ad to be placed on the first page in the search results. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
BidStrategyType | String | The bid strategy type. Possible values include EnhancedCpc, ManualCpc, MaxClicks, MaxConversions, and TargetCpa. If the InheritFromParent strategy type is used, the report will include the inherited bid strategy type e.g., one of the supported values listed above. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignStatus | String | The campaign status. | |||
TrackingTemplate | String | The current tracking template for the ad group. | |||
CustomParameters | String | The current set of custom parameters for the campaign. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
KeywordStatus | String | The keyword status. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). | ||
QualityScore | Integer | True | The numeric score shows you how competitive your ads are in the marketplace by measuring how relevant your keywords and landing pages are to customers' search terms. If available, the quality score can range from a low of 1 to a high of 10. | ||
ExpectedCtr | Integer | True | How well your keyword competes against other keywords targeting the same traffic. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. | ||
AdRelevance | Integer | True | How closely related your ads is to the search query or other input. It tells you how relevant your ad and landing page are to potential customers. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. | ||
LandingPageExperience | Integer | True | An aggregate quality assessment of all landing pages on your site. The landing page experience score measures whether your landing page is likely to provide a good experience to customers who click your ad and land on your website. A score of 3 is Above Average; a score of 2 is Average; and a score of 1 is considered Below Average. | ||
QualityImpact | Double | True | The numeric score that indicates the possible increase in the number of impressions that the keyword could receive if the corresponding QualityScore column would rise above underperforming: 0 (not available), 1 (low impact), 2 (medium impact), or 3 (high impact). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Keywords¶
Query the available Keywords in Bing Ads.
Table Specific Information¶
Select¶
You must specify the AdGroupId
column in the WHERE clause to query this table.
The connector uses the Microsoft Ads API to filter the results by AdGroupId
while the rest of the filter is executed client side within the connector.
For example, the following query is processed on the server.
SELECT * FROM [Keywords] WHERE AdGroupId = '5179946000'
SELECT * FROM Keywords WHERE AdGroupId = '1311717627185807' AND AccountId = '135096904'
You can turn off the client-side execution of the query by setting SupportEnhancedSQL
to false, in which case any search criteria that refers to columns other than AdGroupId
in the WHERE clause causes an error.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The system-generated identifier of the keyword. | |||
AdGroupId | Long | The system generated identifier of the ad group. | |||
Text | String | The keyword text. The text can contain a maximum of 100 characters. You should specify the keyword in the locale of the Language value that you specified for the ad group to which the keyword belongs. | |||
Status | String | The keyword's status. By default, the status is set to Active. | |||
BidAmount | Double | The bid to use when the user's search term and the keyword match. | |||
DestinationUrl | String | The URL of the webpage to take the user to when they click the ad. The keyword's destination URL is used if specified; otherwise, the ad's destination URL is used. | |||
BiddingSchemeType | String | The bid strategy type for how you want to manage your bids. | |||
MatchType | String | The type of match to compare the keyword and the user's search term. | |||
TrackingUrlTemplate | String | The tracking template to use as a default for all FinalUrls and FinalMobileUrls. | |||
UrlCustomParameters | String | Your custom collection of key and value parameters for URL tracking. | |||
ForwardCompatibilityMap | String | The list of key and value strings for forward compatibility. This element can be used to avoid otherwise breaking changes when new elements are added in future releases. | |||
FinalUrls | String | The landing page URL. The keyword's final URL is used if specified; otherwise, the ad's final URL is used. | |||
FinalMobileUrls | String | The mobile landing page URL. The keyword's final mobile URL is used if specified; otherwise, the ad's final mobile URL is used. | |||
FinalAppUrls | String | Reserved for future use. | |||
EditorialStatus | String | The editorial review status of the keyword, which indicates whether the keyword is pending review, has been approved, or has been disapproved. | |||
Param1 | String | The string to use as the substitution value in an ad if the ad's title, text, display URL, or destination URL contains the {Param1} dynamic substitution string | |||
Param2 | String | The string to use as the substitution value in an ad if the ad's title, text, display URL, or destination URL contains the {Param2} dynamic substitution string | |||
Param3 | String | The string to use as the substitution value in an ad if the ad's title, text, display URL, or destination URL contains the {Param3} dynamic substitution string | |||
AccountId | Long | The Bing Ads assigned identifier of an account. |
NegativeKeywordConflictReport¶
Use this report to discover which keywords and negative keywords are in conflict, and whether the conflict is at the campaign or ad group level. Use this list to figure out which negative keywords to delete.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountStatus | String | The account status. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdGroupName | String | The ad group name. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
CampaignName | String | The campaign name. | |||
CampaignStatus | String | The campaign status. | |||
Keyword | String | True | The keyword text. | ||
KeywordId | Long | The Bing Ads assigned identifier of a keyword. | |||
KeywordStatus | String | The keyword status. | |||
NegativeKeyword | String | True | The negative keyword text. | ||
ConflictLevel | String | The entity level where the keyword and negative keyword conflict occurs. The possible values are AdGroup and Campaign. | |||
ConflictType | String | The type of negative keyword conflict encountered.The possible values are Possibly intentional conflict and True conflict. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. For more information, see Budget and Bid Strategies. | |||
NegativeKeywordListId | Long | The Bing Ads assigned identifier of a negative keyword list. | |||
NegativeKeywordList | String | The name of the negative keyword list. | |||
NegativeKeywordId | Long | The Bing Ads assigned identifier of a negative keyword. | |||
NegativeKeywordMatchType | String | The type of match to compare the negative keyword and the user's search term. The possible values for a negative keyword are Exact and Phrase. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ProductDimensionPerformanceReport¶
Use this report to find out which product dimensions are performing well and those that are not.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | String | The Bing Ads assigned identifier of an ad group. | |||
AdId | String | The Bing Ads assigned identifier of an ad. | |||
CampaignName | String | The campaign name. | |||
CurrencyCode | String | The account currency type. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
MerchantProductId | String | True | The report will include a column that contains the unique identifier provided by a merchant for each product offer. | ||
Title | String | The product item name. For example the title of a book, DVD, or game. | |||
Condition | String | The condition of a product item. | |||
Brand | String | The product item's manufacturer, brand, or publisher. | |||
CustomLabel0 | String | The value of the Custom_label_0 field in your Bing Merchant Center catalog. | |||
CustomLabel1 | String | The value of the Custom_label_1 field in your Bing Merchant Center catalog. | |||
CustomLabel2 | String | The value of the Custom_label_2 field in your Bing Merchant Center catalog. | |||
CustomLabel3 | String | The value of the Custom_label_3 field in your Bing Merchant Center catalog. | |||
CustomLabel4 | String | The value of the Custom_label_4 field in your Bing Merchant Center catalog. | |||
ProductType1 | String | The first level value of the Product_type field in your Bing Merchant Center catalog. | |||
ProductType2 | String | The second level value of the Product_type field in your Bing Merchant Center catalog. | |||
ProductType3 | String | The third level value of the Product_type field in your Bing Merchant Center catalog. | |||
ProductType4 | String | The fourth level value of the Product_type field in your Bing Merchant Center catalog. | |||
ProductType5 | String | The fifth level value of the Product_type field in your Bing Merchant Center catalog. | |||
ProductCategory1 | String | The first level value of the Product_category field in your Bing Merchant Center catalog. | |||
ProductCategory2 | String | The second level value of the Product_category field in your Bing Merchant Center catalog. | |||
ProductCategory3 | String | The third level value of the Product_category field in your Bing Merchant Center catalog. | |||
ProductCategory4 | String | The fourth level value of the Product_category field in your Bing Merchant Center catalog. | |||
ProductCategory5 | String | The fifth level value of the Product_category field in your Bing Merchant Center catalog. | |||
AccountStatus | String | The account status. | |||
AssistedClicks | String | Clicks on your ads that have received co-bids from your manufacturer partners. Clicks are what you pay for. | |||
AssistedImpressions | String | The number of times an ad that is being co-bid by your manufacturer partners has been displayed on search results pages or other sites on the Bing Network. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignId | String | The Bing Ads assigned identifier of a campaign. | |||
Network | String | The current network setting of an ad group. | |||
Price | String | The different price for products in your catalog. | |||
SellerName | String | The report will include a column that contains the merchant or store name that offers the product. | |||
OfferLanguage | String | The report will include a column that contains the language for the product offer. | |||
CountryOfSale | String | The report will include a column that contains the country of sale for the product catalog. | |||
AdStatus | String | The ad status. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
ClickTypeId | Long | The click type ID. | |||
StoreId | Long | The unique identifier for the Bing Merchant Center store. | |||
BidStrategyType | String | The bid strategy type. Possible values include EnhancedCpc and ManualCpc. If the InheritFromParent strategy type is used, the report will include the inherited bid strategy type e.g. one of the supported values listed above. | |||
ClickType | String | Click type refers to each component of an ad that a customer can click. | |||
LocalStoreCode | String | An alphanumeric identifier defined by the merchant to uniquely identify each local store. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
AbsoluteTopImpressionSharePercent | Double | True | The number of times your ad is shown in the top position as a percentage of the total available impressions in the market you were targeting. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads. It is the share of the prospective customer's mindshare and buying intent you captured. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The cost per click (CPC) summed for each click. | ||
ConversionRate | Double | True | The cost per click (CPC) summed for each click. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
ImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | ||
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
BenchmarkBid | Double | True | Shows you how much other advertisers are bidding on average on similar products as your current target. | ||
BenchmarkCtr | Double | True | Shows you how other product ads for similar products are performing on average based on how often people who see the ad end up clicking on it. | ||
TotalClicksOnAdElements | Integer | True | The number of clicks when this ad element was present in the ad copy, whether this or another ad element was clicked on. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ProductNegativeKeywordConflictReport¶
Use this report to discover which keywords and negative keywords are in conflict, and whether the conflict is at the campaign or ad group level. Use this list to figure out which negative keywords to delete.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AccountStatus | String | The account status. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdGroupStatus | String | The ad group status. | |||
ConflictLevel | String | The entity level where the keyword and negative keyword conflict occurs. The possible values are AdGroup and Campaign. | |||
NegativeKeywordListId | Long | The Bing Ads assigned identifier of a negative keyword list. | |||
NegativeKeyword | String | True | The negative keyword text. | ||
NegativeKeywordId | Long | The Bing Ads assigned identifier of a negative keyword. | |||
NegativeKeywordMatchType | String | The type of match to compare the negative keyword and the user's search term. The possible values for a negative keyword are Exact and Phrase. | |||
Title | String | The type of match to compare the negative keyword and the user's search term. The possible values for a negative keyword are Exact and Phrase. | |||
MerchantProductId | String | True | The report will include a column that contains the unique identifier provided by a merchant for each product offer. | ||
AdGroupCriterionId | Long | The Bing Ads assigned identifier of an ad group criterion, or product group in the context of a Bing Shopping campaign. | |||
ProductGroup | String | True | The forward slash ('/') delimited list of product conditions, reported as Operand= |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ProductPartitionPerformanceReport¶
You can include details in the report such as impressions, clicks, and spend that you can use to identify whether or not the product partitions are performing well.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdId | Long | The Bing Ads assigned identifier of an ad. | |||
AssistedClicks | String | Clicks on your ads that have received co-bids from your manufacturer partners. Clicks are what you pay for. | |||
AssistedImpressions | String | The number of times an ad that is being co-bid by your manufacturer partners has been displayed on search results pages or other sites on the Bing Network. | |||
CampaignName | String | The campaign name. | |||
CurrencyCode | String | The account currency type. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
AccountStatus | String | The account status. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
Network | String | The current network setting of an ad group. | |||
OfferLanguage | String | The report will include a column that contains the language for the product offer. | |||
CountryOfSale | String | The report will include a column that contains the country of sale for the product catalog. | |||
AdStatus | String | The ad status. | |||
PartitionType | String | True | The product partition type. | ||
ProductGroup | String | True | The forward slash ('/') delimited list of product conditions, reported as Operand= | ||
AdGroupCriterionId | Long | The Bing Ads assigned identifier of an ad group criterion, or product group in the context of a Bing Shopping campaign. | |||
CurrentMaxCpc | String | The maximum cost per click bid that was in effect at the time the report was generated. It is not a moving historical bid throughout the report time period. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
TrackingTemplate | String | The current tracking template of the criterion. | |||
CustomParameters | String | The current custom parameter set of the criterion. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
ClickType | String | Click type refers to each component of an ad that a customer can click. | |||
BidStrategyType | String | The bid strategy type. Possible values include EnhancedCpc and ManualCpc. If the InheritFromParent strategy type is used, the report will include the inherited bid strategy type e.g. one of the supported values listed above. | |||
LocalStoreCode | String | An alphanumeric identifier defined by the merchant to uniquely identify each local store. | |||
ClickTypeId | Long | The click type ID. | |||
CostPerConversion | Double | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
AbsoluteTopImpressionSharePercent | Double | True | The number of times your ad is shown in the top position as a percentage of the total available impressions in the market you were targeting. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads. It is the share of the prospective customer's mindshare and buying intent you captured. | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The cost per click (CPC) summed for each click. | ||
ConversionRate | Double | True | The cost per click (CPC) summed for each click. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
ImpressionSharePercent | Double | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | ||
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
BenchmarkBid | Double | True | Shows you how much other advertisers are bidding on average on similar products as your current target. | ||
BenchmarkCtr | Double | True | Shows you how other product ads for similar products are performing on average based on how often people who see the ad end up clicking on it. | ||
TotalClicksOnAdElements | Integer | True | The number of clicks when this ad element was present in the ad copy, whether this or another ad element was clicked on. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerAssist | Double | True | The revenue per assist. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ProductPartitionUnitPerformanceReport¶
Use this report to find out which product partition units are performing well and those that are not.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdId | Long | The Bing Ads assigned identifier of an ad. | |||
CampaignName | String | The campaign name. | |||
CurrencyCode | String | The account currency type. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
AccountStatus | String | The account status. | |||
AssistedClicks | String | Clicks on your ads that have received co-bids from your manufacturer partners. Clicks are what you pay for. | |||
AssistedImpressions | String | The number of times an ad that is being co-bid by your manufacturer partners has been displayed on search results pages or other sites on the Bing Network. | |||
CampaignStatus | String | The campaign status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
Network | String | The current network setting of an ad group. | |||
AdStatus | String | The ad status. | |||
ProductGroup | String | True | The forward slash ('/') delimited list of product conditions, reported as Operand= | ||
AdGroupCriterionId | Long | True | The Bing Ads assigned identifier of an ad group criterion, or product group in the context of a Bing Shopping campaign. | ||
CurrentMaxCpc | String | The maximum cost per click bid that was in effect at the time the report was generated. It is not a moving historical bid throughout the report time period. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
TrackingTemplate | String | The current tracking template of the criterion. | |||
CustomParameters | String | The current custom parameter set of the criterion. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidStrategyType | String | The bid strategy type. Possible values include EnhancedCpc and ManualCpc. If the InheritFromParent strategy type is used, the report will include the inherited bid strategy type e.g. one of the supported values listed above. | |||
LocalStoreCode | String | An alphanumeric identifier defined by the merchant to uniquely identify each local store. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The cost per click (CPC) summed for each click. | ||
ConversionRate | Double | True | The cost per click (CPC) summed for each click. | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerAssist | Double | True | The revenue per assist. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ProductSearchQueryPerformanceReport¶
Use this report to get insight into what your audience is searching for when your ads are shown as well as ensure that your product titles are relevant to search queries.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdId | Long | The Bing Ads assigned identifier of an ad. | |||
AccountId | Long | The Bing Ads assigned identifier of an ad. | |||
AssistedClicks | String | Clicks on your ads that have received co-bids from your manufacturer partners. Clicks are what you pay for. | |||
AssistedImpressions | String | The number of times an ad that is being co-bid by your manufacturer partners has been displayed on search results pages or other sites on the Bing Network. | |||
CampaignName | String | True | The campaign name. | ||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
Language | String | The ad group language. | |||
CampaignId | Long | True | The Bing Ads assigned identifier of a campaign. | ||
Network | String | The current network setting of an ad group. | |||
PartitionType | String | The product partition type. | |||
ProductGroup | String | The forward slash ('/') delimited list of product conditions, reported as Operand= | |||
AdGroupCriterionId | Long | The Bing Ads assigned identifier of an ad group criterion, or product group in the context of a Bing Shopping campaign. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. | |||
ClickType | String | Click type refers to each component of an ad that a customer can click. | |||
ClickTypeId | Long | The click type ID. | |||
MerchantProductId | Long | True | The click type ID. | ||
SearchQuery | String | True | The click type ID. | ||
Title | String | The click type ID. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
Conversions | Integer | True | The cost per click (CPC) summed for each click. | ||
ConversionRate | Double | True | The cost per click (CPC) summed for each click. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
TotalClicksOnAdElements | Integer | True | The number of clicks when this ad element was present in the ad copy, whether this or another ad element was clicked on. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerAssist | Double | True | The revenue per assist. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
PublisherUsagePerformanceReport¶
Use this report to see if any website URLs aren't performing well enough for your campaign or ad group target settings. For example, if ad impressions at those URLs yield a low click-through rate, then you might decide to exclude those websites from your campaign.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | True | The campaign name. | ||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignStatus | String | The campaign status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
PublisherUrl | String | True | The URL of the website that displayed the ad. | ||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
SearchCampaignChangeHistoryReport¶
Use this report to discover when changes to an account were made, as well as which user made the changes.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdGroupName | String | The ad group name. | |||
CampaignName | String | The campaign name. | |||
EntityId | String | The Bing Ads system identifier of the entity that was updated. | |||
EntityName | String | The name of the entity that was updated. | |||
DateTime | String | True | The campaign name. | ||
AdTitle | String | The ad title. | |||
AdDescription | String | The campaign name. | |||
DisplayUrl | String | The campaign name. | |||
Keyword | String | The campaign name. | |||
ItemChanged | String | The campaign name. | |||
AttributeChanged | String | The campaign name. | |||
ChangedBy | String | The username of the user that made the change to settings within the account. If the system made the change, the value will be Administrator. | |||
HowChanged | String | The campaign name. | |||
OldValue | String | The campaign name. | |||
NewValue | String | The campaign name. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are LastSevenDays, LastMonth, LastThreeMonths. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
SearchQueryPerformanceReport¶
Use this report to see what your audience is searching for when your ads are shown. You can use this information to make informed additions, removals, or edits to both your keyword and negative keyword lists.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdId | Long | Ad Id | |||
AdType | String | The ad type. | |||
DestinationUrl | String | The destination URL attribute of the ad, keyword, or ad group criterion. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
AdGroupCriterionId | Long | The Bing Ads assigned identifier of an ad group criterion. | |||
AdStatus | String | The ad status. | |||
CampaignStatus | String | The campaign status. | |||
CampaignType | String | The type of campaign. Possible values include Search, Shopping, and Dynamic search. | |||
CustomerId | String | The Bing Ads assigned identifier of a customer. | |||
CustomerName | String | The customer name. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
SearchQuery | String | True | The search term used by your potential audience. | ||
Keyword | String | The keyword text. | |||
KeywordId | Long | The Bing Ads assigned identifier of a keyword. | |||
KeywordStatus | String | The keyword status. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). The formula for calculating the ROAS is (Revenue / Spend). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
ShareOfVoiceReport¶
Use this report to view impression share (%) of successful bids for each keyword, and identify opportunities to increase impression share.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | The account name. | |||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignName | String | The campaign name. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign.. | |||
AdGroupName | String | The ad group name. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an ad group. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
AccountStatus | String | The account status. | |||
AdGroupStatus | String | The ad group status. | |||
CampaignStatus | String | The campaign status. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. The possible values include Computer, Smartphone, Tablet, and Unknown. | |||
Language | String | The ad group language. | |||
Network | String | The current network setting of an ad group. | |||
BidStrategyType | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. | |||
KeywordId | String | True | The Bing Ads assigned identifier of a keyword. | ||
Keyword | String | The keyword text. | |||
KeywordStatus | String | The keyword status. | |||
KeywordLabels | String | The labels applied to the keyword. | |||
AdRelevance | String | How closely related your ads is to the customer's search query or other input. It tells you how relevant your ad and landing page are to potential customers. | |||
LandingPageExperience | String | An aggregate quality assessment of all landing pages on your site. The landing page experience score measures whether your landing page is likely to provide a good experience to customers who click your ad and land on your website. | |||
ExpectedCtr | String | How well your keyword competes against other keywords targeting the same traffic. Ads that are relevant to searchers' queries or other input are more likely to have a higher click-through rate. | |||
Impressions | Integer | True | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | |
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
ExactMatchImpressionSharePercent | Double | True | The estimated percentage of impressions that your account received for searches that exactly matched your keyword, out of the total available exact match impressions you were eligible to receive. | ||
ImpressionSharePercent | Double | True | True | The estimated percentage of impressions, out of the total available impressions in the market you were targeting. The value of this column is empty if the data is not available. | |
ImpressionLostToBudgetPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your daily or monthly budget. The value of this column is empty if the data is not available. | ||
ImpressionLostToRankAggPercent | Double | True | The estimated percentage of impressions your ad did not receive due to issues with your ad ranking. The value of this column is empty if the data is not available. | ||
CurrentMaxCpc | Double | True | The maximum cost per click bid that was in effect at the time the report was generated. It is not a moving historical bid throughout the report time period. | ||
QualityScore | Integer | True | The numeric score shows you how competitive your ads are in the marketplace by measuring how relevant your keywords and landing pages are to customers' search terms. | ||
ClickSharePercent | Double | True | The percentage of clicks that went to your ads. It is the share of the prospective customer's mindshare and buying intent you captured. |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Tags¶
Query the available Tags in Bing Ads.
Table Specific Information¶
Select¶
Searches on this table are processed client-side by the connector; the following query is processed server-side.
SELECT * FROM [Tags]
SELECT * FROM Tags WHERE AccountId = '135096904'
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Id [KEY] | Long | The unique Bing Ads identifier of the UET tag. | |||
Name | String | The UET tag name. | |||
Description | String | Text to help you identify the UET tag. We recommend that you set this to the related website page name or URL. | |||
TrackingNoScript | String | If your website doesn't support JavaScript, you can use this Non-JavaScript representation of the UET tag. If you use Non-JavaScript, you can't track custom events or variable revenue. | |||
TrackingScript | String | The tracking script that you can add to your website to allow Bing Ads to collect actions people take on your website. | |||
TrackingStatus | String | The system-determined status values of a UET tag, for example the system sets the status to Unverified if the UET tag has not yet been verified. The allowed values are Unverified, Active, Inactive. | |||
CustomerShareAggregate | String | True | Contains information about CustomerAccountShares and OwnerCustomerId. | ||
AccountId | Long | The Bing Ads assigned identifier of an account. |
UserLocationPerformanceReport¶
Use this report to see which locations your traffic is coming from. You can then validate whether your location targeting strategy is successful, and identify opportunities to improve. The report also identifies the physical location of the user and the intended geographical location of the user's search query, for example a user in Seattle searching for services in Portland.
Columns¶
Name | Type | Select requirement | Metric | Aggregate | Description |
---|---|---|---|---|---|
Summary | String | True | The report data will be aggregated by the entire specified report time. The report will not include a time period column. | ||
Hourly | String | True | Each row of the report identifies the hour when the transaction occurred. The report data will be aggregated by each hour of the day. | ||
Daily | Date | True | Each row of the report identifies the month, day, and year when the transaction occurred. The report data will be aggregated by each day. Each row of the report identifies the month, day, and year when the transaction occurred. The report will include a column named GregorianDate that contains the day formatted as yyyy-mm-dd. | ||
Weekly | Date | True | Each row of the report identifies the week when the transaction occurred. The report data will be aggregated by each week. The report will include a column named WeekStartDate that contains the date of the Sunday for each week formatted as yyyy-mm-dd. | ||
Monthly | Date | True | Each row of the report identifies the month when the transaction occurred. The report data will be aggregated by each month. The report will include a column named MonthStartDate that contains the first day of the month formatted as yyyy-mm-dd. | ||
Yearly | Integer | True | Each row of the report identifies the year when the transaction occurred. The report data will be aggregated by each year. The report will include a column named Year that contains the year formatted as yyyy. | ||
HourOfDay | Integer | True | Each row of the report identifies the hour of the day when the transaction occurred. The report data will be aggregated by each of the 24 hours across all days | ||
DayOfWeek | Integer | True | Each row of the report identifies the day of the week when the transaction occurred. The report data will be aggregated by each of the seven days in a week. | ||
AccountName | String | True | The account name. | ||
AccountNumber | String | The Bing Ads assigned number of an account. | |||
AccountId | Long | The Bing Ads assigned identifier of an account. | |||
AdGroupId | Long | The Bing Ads assigned identifier of an account. | |||
CampaignId | Long | The Bing Ads assigned identifier of a campaign. | |||
AdGroupName | String | The ad group name. | |||
CampaignName | String | The campaign name. | |||
Language | String | The ad group language. | |||
Country | String | The country where the user was physically located when they clicked the ad. | |||
State | String | The state where the user was physically located when they clicked the ad. | |||
MetroArea | String | The metro area where the user was physically located when they clicked the ad. | |||
City | String | The city where the user was physically located when they clicked the ad. | |||
CurrencyCode | String | The account currency type. | |||
AdDistribution | String | The ad distribution attribute of an ad group. | |||
ProximityTargetLocation | String | The radius target bid name. The name of the geographic radius where the user was physically located when they clicked the ad. | |||
Radius | String | The radius of a radius target bid. The geographic radius where the user was physically located when they clicked the ad. | |||
BidMatchType | String | The keyword bid match type. This can be different from the DeliveredMatchType column, for example if you bid on a broad match and the search term was an exact match. For more information, see Budget and Bid Strategies. | |||
DeliveredMatchType | String | The match type used to deliver an ad. This can be different from the BidMatchType column, for example if you bid on a broad match and the search term was an exact match. For more information, see Budget and Bid Strategies. | |||
Network | String | The current network setting of an ad group. | |||
TopVsOther | String | The report will include a column that indicates whether the ad impression appeared in a top position or elsewhere. | |||
DeviceType | String | The device name attribute of a device OS target bid. The type of device which showed ads. | |||
County | String | The county where the user was physically located when they clicked the ad. | |||
DeviceOS | String | The operating system of the device reported in the DeviceType column. | |||
LocationId | Long | The Bing Ads identifier of the location where the user was physically located when they clicked the ad. For geographical location identifiers, see Geographical Location Codes. | |||
PostalCode | String | The postal code where the user was physically located when they clicked the ad. | |||
QueryIntentCountry | String | The name of a country if the user's geographical intent can be determined. The country is set if the user's intent is related to a country, and not necessarily if they are physically located in the county. | |||
QueryIntentState | String | The name of a state if the user's geographical intent can be determined. The state is set if the user's intent is a state or sub geography of the state, and not necessarily if they are physically located in the state. | |||
QueryIntentCity | String | The name of a city if the user's geographical intent can be determined. The city is set if the user's intent is a city, and not necessarily if they are physically located in the city. | |||
QueryIntentDMA | String | The postal code where the user was physically located when they clicked the ad. | |||
QueryIntentCounty | String | The name of a county if the user's geographical intent can be determined. The county is set if the user's intent is related to a county, and not necessarily if they are physically located in the county. | |||
QueryIntentPostalCode | String | The name of a postal code if the user's geographical intent can be determined. The postal code is set if the user's intent is a postal code, and not necessarily if they are physically located in the postal code. | |||
QueryIntentLocationId | String | The location identifier if the user's geographical intent can be determined. | |||
Goal | String | The goal name. | |||
GoalType | String | The goal type. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url. | |||
Impressions | Integer | True | The number of times an ad has been displayed on search results pages. Without impressions there are no clicks or conversions. | ||
Clicks | Integer | True | Clicks are what you pay for. Clicks typically include a customer clicking an ad on a search results page or on a website on the search network. Clicks can also come from other sources (for example, spiders, robots, and test servers). | ||
Ctr | Double | True | The click-through rate (CTR) is the number of times an ad was clicked, divided by the number of times the ad was shown (impressions). For example, if your ads got 50 clicks given 2, 348 impressions, your CTR is 2.13 (%). | ||
AverageCpc | Double | True | The average cost per click (CPC). The total cost of all clicks on an ad divided by the number of clicks. This is the average amount you're actually charged each time your ad is clicked. For example, if you paid a total of 48.35 for 300 clicks, your average CPC is 0.16. | ||
Spend | Double | True | The cost per click (CPC) summed for each click. | ||
AveragePosition | Double | True | The average position of the ad on a webpage. | ||
Assists | Integer | True | The number of conversions from other ads within the same account that were preceded by one or more clicks from this ad. | ||
Conversions | Integer | True | The number of conversions. A conversion is the completion of an action by a customer after viewing your ad. The action could be purchasing your product, registering for your webinar, joining an organization, or whatever you consider your goal and best measure of the ad's success | ||
CostPerConversion | Double | True | The cost per conversion. The formula for calculating the cost per conversion is (Spend / Conversions). | ||
ConversionRate | Double | True | The conversion rate as a percentage. The number of conversions, divided by the total number of clicks. For example, if the ads in your campaign got 300 clicks and four conversions, the conversion rate is 1.33 (%). | ||
Revenue | Double | True | The revenue optionally reported by the advertiser as a result of conversions. Corresponds to the optional revenue parameter of a Bing Ads campaign analytics tracking script. | ||
ReturnOnAdSpend | Double | True | The return on ad spend (ROAS). | ||
CostPerAssist | Double | True | The cost per assist. The formula for calculating the cost per assist is (Spend / Assists). | ||
RevenuePerConversion | Double | True | The revenue per conversion. The formula for calculating the revenue per conversion is (Revenue / Conversions). | ||
RevenuePerAssist | Double | True | The revenue per assist. The formula for calculating the revenue per assist is (Revenue / Assists). |
Pseudo-Columns¶
Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.
Name | Type | Description |
---|---|---|
DatePreset | String | The time period to use for the report. You can specify a custom date range or select a predefined date range, for example, Today or ThisWeek. The allowed values are Today, Yesterday, LastSevenDays, ThisWeek, LastWeek, LastFourWeeks, ThisMonth, LastMonth, LastThreeMonths, LastSixMonths, ThisYear, LastYear. |
EndDate | String | The end date of the custom date range. The end date cannot be later than today's date. |
StartDate | String | The start date of the custom date range. The start date must be earlier than or the same as the end date. |
Stored Procedures¶
Stored procedures are function-like interfaces that extend the functionality of the connector beyond simple SELECT operations with Microsoft Ads.
Stored procedures accept a list of parameters, perform their intended function, and then return any relevant response data from Microsoft Ads, along with an indication of whether the procedure succeeded or failed.
Jitterbit Connector for Microsoft Ads Stored Procedures¶
Name | Description |
---|---|
GetOAuthAccessToken | Gets the OAuth access token from BingAds. |
GetOAuthAuthorizationURL | Gets the BingAds authorization URL. Access the URL returned in the output in a Web browser. This requests the access token that can be used as part of the connection string to BingAds. |
RefreshOAuthAccessToken | Refreshes the OAuth access token used for authentication with BingAds. |
GetOAuthAccessToken¶
Gets the OAuth access token from BingAds.
Input¶
Name | Type | Required | Description |
---|---|---|---|
AuthMode | String | False | The type of authentication you are attempting. Use App for a Windows application, or Web for Web-based applications. The default value is APP. |
Verifier | String | False | A verifier returned by the service that must be input to return the access token. Needed only when using the Web auth mode. Obtained by navigating to the URL returned in GetOAuthAuthorizationUrl. |
CallbackUrl | String | False | The URL the user will be redirected to after authorizing your application. |
Scope | String | False | The scope or permissions you are requesting. The default value is offline_access https://ads.microsoft.com/msads.manage. |
Prompt | String | False | Defaults to 'select_account' which prompts the user to select account while authenticating. Set to 'None', for no prompt, 'login' to force user to enter their credentials or 'consent' to trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app. |
Result Set Columns¶
Name | Type | Description |
---|---|---|
OAuthAccessToken | String | The authentication token returned from BingAds. |
OAuthRefreshToken | String | A token that may be used to obtain a new access token. |
ExpiresIn | String | The remaining lifetime for the access token in seconds. |
GetOAuthAuthorizationURL¶
Gets the BingAds authorization URL. Access the URL returned in the output in a Web browser. This requests the access token that can be used as part of the connection string to BingAds.
Input¶
Name | Type | Required | Description |
---|---|---|---|
CallbackUrl | String | False | The URL that BingAds will return to after the user has authorized your app. |
Scope | String | False | The scope or permissions you are requesting. The default value is offline_access https://ads.microsoft.com/msads.manage. |
State | String | False | This field indicates any state that may be useful to your application upon receipt of the response. Your application receives the same value it sent, as this parameter makes a round-trip to BingAds authorization server and back. Uses include redirecting the user to the correct resource in your site, using nonces, and mitigating cross-site request forgery. |
Prompt | String | False | Defaults to 'select_account' which prompts the user to select account while authenticating. Set to 'None', for no prompt, 'login' to force user to enter their credentials or 'consent' to trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app. |
Result Set Columns¶
Name | Type | Description |
---|---|---|
URL | String | The URL to be entered into a Web browser to obtain the verifier token and authorize the data provider with. |
RefreshOAuthAccessToken¶
Refreshes the OAuth access token used for authentication with BingAds.
Input¶
Name | Type | Required | Description |
---|---|---|---|
OAuthRefreshToken | String | True | The refresh token returned from the original authorization code exchange. |
Scope | String | False | The scope or permissions you are requesting. The default value is offline_access https://ads.microsoft.com/msads.manage. |
Result Set Columns¶
Name | Type | Description |
---|---|---|
OAuthAccessToken | String | The new OAuthAccessToken returned from the service. |
OAuthRefreshToken | String | A token that may be used to obtain a new access token. |
ExpiresIn | String | The remaining lifetime on the access token. |
System Tables¶
You can query the system tables described in this section to access schema information, information on data source functionality, and batch operation statistics.
Schema Tables¶
The following tables return database metadata for Microsoft Ads:
- sys_catalogs: Lists the available databases.
- sys_schemas: Lists the available schemas.
- sys_tables: Lists the available tables and views.
- sys_tablecolumns: Describes the columns of the available tables and views.
- sys_procedures: Describes the available stored procedures.
- sys_procedureparameters: Describes stored procedure parameters.
- sys_keycolumns: Describes the primary and foreign keys.
- sys_indexes: Describes the available indexes.
Data Source Tables¶
The following tables return information about how to connect to and query the data source:
- sys_connection_props: Returns information on the available connection properties.
- sys_sqlinfo: Describes the SELECT queries that the connector can offload to the data source.
Query Information Tables¶
The following table returns query statistics for data modification queries:
- sys_identity: Returns information about batch operations or single updates.
sys_catalogs¶
Lists the available databases.
The following query retrieves all databases determined by the connection string:
SELECT * FROM sys_catalogs
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The database name. |
sys_schemas¶
Lists the available schemas.
The following query retrieves all available schemas:
SELECT * FROM sys_schemas
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The database name. |
SchemaName | String | The schema name. |
sys_tables¶
Lists the available tables.
The following query retrieves the available tables and views:
SELECT * FROM sys_tables
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The database containing the table or view. |
SchemaName | String | The schema containing the table or view. |
TableName | String | The name of the table or view. |
TableType | String | The table type (table or view). |
Description | String | A description of the table or view. |
IsUpdateable | Boolean | Whether the table can be updated. |
sys_tablecolumns¶
Describes the columns of the available tables and views.
The following query returns the columns and data types for the AdGroups table:
SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='AdGroups'
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the table or view. |
SchemaName | String | The schema containing the table or view. |
TableName | String | The name of the table or view containing the column. |
ColumnName | String | The column name. |
DataTypeName | String | The data type name. |
DataType | Int32 | An integer indicating the data type. This value is determined at run time based on the environment. |
Length | Int32 | The storage size of the column. |
DisplaySize | Int32 | The designated column's normal maximum width in characters. |
NumericPrecision | Int32 | The maximum number of digits in numeric data. The column length in characters for character and date-time data. |
NumericScale | Int32 | The column scale or number of digits to the right of the decimal point. |
IsNullable | Boolean | Whether the column can contain null. |
Description | String | A brief description of the column. |
Ordinal | Int32 | The sequence number of the column. |
IsAutoIncrement | String | Whether the column value is assigned in fixed increments. |
IsGeneratedColumn | String | Whether the column is generated. |
IsHidden | Boolean | Whether the column is hidden. |
IsArray | Boolean | Whether the column is an array. |
IsReadOnly | Boolean | Whether the column is read-only. |
IsKey | Boolean | Indicates whether a field returned from sys_tablecolumns is the primary key of the table. |
sys_procedures¶
Lists the available stored procedures.
The following query retrieves the available stored procedures:
SELECT * FROM sys_procedures
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The database containing the stored procedure. |
SchemaName | String | The schema containing the stored procedure. |
ProcedureName | String | The name of the stored procedure. |
Description | String | A description of the stored procedure. |
ProcedureType | String | The type of the procedure, such as PROCEDURE or FUNCTION. |
sys_procedureparameters¶
Describes stored procedure parameters.
The following query returns information about all of the input parameters for the SelectEntries stored procedure:
SELECT * FROM sys_procedureparameters WHERE ProcedureName='SelectEntries' AND Direction=1 OR Direction=2
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the stored procedure. |
SchemaName | String | The name of the schema containing the stored procedure. |
ProcedureName | String | The name of the stored procedure containing the parameter. |
ColumnName | String | The name of the stored procedure parameter. |
Direction | Int32 | An integer corresponding to the type of the parameter: input (1), input/output (2), or output(4). input/output type parameters can be both input and output parameters. |
DataTypeName | String | The name of the data type. |
DataType | Int32 | An integer indicating the data type. This value is determined at run time based on the environment. |
Length | Int32 | The number of characters allowed for character data. The number of digits allowed for numeric data. |
NumericPrecision | Int32 | The maximum precision for numeric data. The column length in characters for character and date-time data. |
NumericScale | Int32 | The number of digits to the right of the decimal point in numeric data. |
IsNullable | Boolean | Whether the parameter can contain null. |
IsRequired | Boolean | Whether the parameter is required for execution of the procedure. |
IsArray | Boolean | Whether the parameter is an array. |
Description | String | The description of the parameter. |
Ordinal | Int32 | The index of the parameter. |
sys_keycolumns¶
Describes the primary and foreign keys.
The following query retrieves the primary key for the AdGroups table:
SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='AdGroups'
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the key. |
SchemaName | String | The name of the schema containing the key. |
TableName | String | The name of the table containing the key. |
ColumnName | String | The name of the key column. |
IsKey | Boolean | Whether the column is a primary key in the table referenced in the TableName field. |
IsForeignKey | Boolean | Whether the column is a foreign key referenced in the TableName field. |
PrimaryKeyName | String | The name of the primary key. |
ForeignKeyName | String | The name of the foreign key. |
ReferencedCatalogName | String | The database containing the primary key. |
ReferencedSchemaName | String | The schema containing the primary key. |
ReferencedTableName | String | The table containing the primary key. |
ReferencedColumnName | String | The column name of the primary key. |
sys_foreignkeys¶
Describes the foreign keys.
The following query retrieves all foreign keys which refer to other tables:
SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the key. |
SchemaName | String | The name of the schema containing the key. |
TableName | String | The name of the table containing the key. |
ColumnName | String | The name of the key column. |
PrimaryKeyName | String | The name of the primary key. |
ForeignKeyName | String | The name of the foreign key. |
ReferencedCatalogName | String | The database containing the primary key. |
ReferencedSchemaName | String | The schema containing the primary key. |
ReferencedTableName | String | The table containing the primary key. |
ReferencedColumnName | String | The column name of the primary key. |
ForeignKeyType | String | Designates whether the foreign key is an import (points to other tables) or export (referenced from other tables) key. |
sys_primarykeys¶
Describes the primary keys.
The following query retrieves the primary keys from all tables and views:
SELECT * FROM sys_primarykeys
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the key. |
SchemaName | String | The name of the schema containing the key. |
TableName | String | The name of the table containing the key. |
ColumnName | String | The name of the key column. |
KeySeq | String | The sequence number of the primary key. |
KeyName | String | The name of the primary key. |
sys_indexes¶
Describes the available indexes. By filtering on indexes, you can write more selective queries with faster query response times.
The following query retrieves all indexes that are not primary keys:
SELECT * FROM sys_indexes WHERE IsPrimary='false'
Columns¶
Name | Type | Description |
---|---|---|
CatalogName | String | The name of the database containing the index. |
SchemaName | String | The name of the schema containing the index. |
TableName | String | The name of the table containing the index. |
IndexName | String | The index name. |
ColumnName | String | The name of the column associated with the index. |
IsUnique | Boolean | True if the index is unique. False otherwise. |
IsPrimary | Boolean | True if the index is a primary key. False otherwise. |
Type | Int16 | An integer value corresponding to the index type: statistic (0), clustered (1), hashed (2), or other (3). |
SortOrder | String | The sort order: A for ascending or D for descending. |
OrdinalPosition | Int16 | The sequence number of the column in the index. |
sys_connection_props¶
Returns information on the available connection properties and those set in the connection string.
When querying this table, the config connection string should be used:
jdbc:cdata:bingads:config:
This connection string enables you to query this table without a valid connection.
The following query retrieves all connection properties that have been set in the connection string or set through a default value:
SELECT * FROM sys_connection_props WHERE Value <> ''
Columns¶
Name | Type | Description |
---|---|---|
Name | String | The name of the connection property. |
ShortDescription | String | A brief description. |
Type | String | The data type of the connection property. |
Default | String | The default value if one is not explicitly set. |
Values | String | A comma-separated list of possible values. A validation error is thrown if another value is specified. |
Value | String | The value you set or a preconfigured default. |
Required | Boolean | Whether the property is required to connect. |
Category | String | The category of the connection property. |
IsSessionProperty | String | Whether the property is a session property, used to save information about the current connection. |
Sensitivity | String | The sensitivity level of the property. This informs whether the property is obfuscated in logging and authentication forms. |
PropertyName | String | A camel-cased truncated form of the connection property name. |
Ordinal | Int32 | The index of the parameter. |
CatOrdinal | Int32 | The index of the parameter category. |
Hierarchy | String | Shows dependent properties associated that need to be set alongside this one. |
Visible | Boolean | Informs whether the property is visible in the connection UI. |
ETC | String | Various miscellaneous information about the property. |
sys_sqlinfo¶
Describes the SELECT query processing that the connector can offload to the data source.
Discovering the Data Source's SELECT Capabilities¶
Below is an example data set of SQL capabilities. Some aspects of SELECT functionality are returned in a comma-separated list if supported; otherwise, the column contains NO.
Name | Description | Possible Values |
---|---|---|
AGGREGATE_FUNCTIONS | Supported aggregation functions. | AVG , COUNT , MAX , MIN , SUM , DISTINCT |
COUNT | Whether COUNT function is supported. | YES , NO |
IDENTIFIER_QUOTE_OPEN_CHAR | The opening character used to escape an identifier. | [ |
IDENTIFIER_QUOTE_CLOSE_CHAR | The closing character used to escape an identifier. | ] |
SUPPORTED_OPERATORS | A list of supported SQL operators. | = , > , < , >= , <= , <> , != , LIKE , NOT LIKE , IN , NOT IN , IS NULL , IS NOT NULL , AND , OR |
GROUP_BY | Whether GROUP BY is supported, and, if so, the degree of support. | NO , NO_RELATION , EQUALS_SELECT , SQL_GB_COLLATE |
STRING_FUNCTIONS | Supported string functions. | LENGTH , CHAR , LOCATE , REPLACE , SUBSTRING , RTRIM , LTRIM , RIGHT , LEFT , UCASE , SPACE , SOUNDEX , LCASE , CONCAT , ASCII , REPEAT , OCTET , BIT , POSITION , INSERT , TRIM , UPPER , REGEXP , LOWER , DIFFERENCE , CHARACTER , SUBSTR , STR , REVERSE , PLAN , UUIDTOSTR , TRANSLATE , TRAILING , TO , STUFF , STRTOUUID , STRING , SPLIT , SORTKEY , SIMILAR , REPLICATE , PATINDEX , LPAD , LEN , LEADING , KEY , INSTR , INSERTSTR , HTML , GRAPHICAL , CONVERT , COLLATION , CHARINDEX , BYTE |
NUMERIC_FUNCTIONS | Supported numeric functions. | ABS , ACOS , ASIN , ATAN , ATAN2 , CEILING , COS , COT , EXP , FLOOR , LOG , MOD , SIGN , SIN , SQRT , TAN , PI , RAND , DEGREES , LOG10 , POWER , RADIANS , ROUND , TRUNCATE |
TIMEDATE_FUNCTIONS | Supported date/time functions. | NOW , CURDATE , DAYOFMONTH , DAYOFWEEK , DAYOFYEAR , MONTH , QUARTER , WEEK , YEAR , CURTIME , HOUR , MINUTE , SECOND , TIMESTAMPADD , TIMESTAMPDIFF , DAYNAME , MONTHNAME , CURRENT_DATE , CURRENT_TIME , CURRENT_TIMESTAMP , EXTRACT |
REPLICATION_SKIP_TABLES | Indicates tables skipped during replication. | |
REPLICATION_TIMECHECK_COLUMNS | A string array containing a list of columns which will be used to check for (in the given order) to use as a modified column during replication. | |
IDENTIFIER_PATTERN | String value indicating what string is valid for an identifier. | |
SUPPORT_TRANSACTION | Indicates if the provider supports transactions such as commit and rollback. | YES , NO |
DIALECT | Indicates the SQL dialect to use. | |
KEY_PROPERTIES | Indicates the properties which identify the uniform database. | |
SUPPORTS_MULTIPLE_SCHEMAS | Indicates if multiple schemas may exist for the provider. | YES , NO |
SUPPORTS_MULTIPLE_CATALOGS | Indicates if multiple catalogs may exist for the provider. | YES , NO |
DATASYNCVERSION | The Data Sync version needed to access this driver. | Standard , Starter , Professional , Enterprise |
DATASYNCCATEGORY | The Data Sync category of this driver. | Source , Destination , Cloud Destination |
SUPPORTSENHANCEDSQL | Whether enhanced SQL functionality beyond what is offered by the API is supported. | TRUE , FALSE |
SUPPORTS_BATCH_OPERATIONS | Whether batch operations are supported. | YES , NO |
SQL_CAP | All supported SQL capabilities for this driver. | SELECT , INSERT , DELETE , UPDATE , TRANSACTIONS , ORDERBY , OAUTH , ASSIGNEDID , LIMIT , LIKE , BULKINSERT , COUNT , BULKDELETE , BULKUPDATE , GROUPBY , HAVING , AGGS , OFFSET , REPLICATE , COUNTDISTINCT , JOINS , DROP , CREATE , DISTINCT , INNERJOINS , SUBQUERIES , ALTER , MULTIPLESCHEMAS , GROUPBYNORELATION , OUTERJOINS , UNIONALL , UNION , UPSERT , GETDELETED , CROSSJOINS , GROUPBYCOLLATE , MULTIPLECATS , FULLOUTERJOIN , MERGE , JSONEXTRACT , BULKUPSERT , SUM , SUBQUERIESFULL , MIN , MAX , JOINSFULL , XMLEXTRACT , AVG , MULTISTATEMENTS , FOREIGNKEYS , CASE , LEFTJOINS , COMMAJOINS , WITH , LITERALS , RENAME , NESTEDTABLES , EXECUTE , BATCH , BASIC , INDEX |
PREFERRED_CACHE_OPTIONS | A string value specifies the preferred cacheOptions. | |
ENABLE_EF_ADVANCED_QUERY | Indicates if the driver directly supports advanced queries coming from Entity Framework. If not, queries will be handled client side. | YES , NO |
PSEUDO_COLUMNS | A string array indicating the available pseudo columns. | |
MERGE_ALWAYS | If the value is true, The Merge Mode is forcibly executed in Data Sync. | TRUE , FALSE |
REPLICATION_MIN_DATE_QUERY | A select query to return the replicate start datetime. | |
REPLICATION_MIN_FUNCTION | Allows a provider to specify the formula name to use for executing a server side min. | |
REPLICATION_START_DATE | Allows a provider to specify a replicate startdate. | |
REPLICATION_MAX_DATE_QUERY | A select query to return the replicate end datetime. | |
REPLICATION_MAX_FUNCTION | Allows a provider to specify the formula name to use for executing a server side max. | |
IGNORE_INTERVALS_ON_INITIAL_REPLICATE | A list of tables which will skip dividing the replicate into chunks on the initial replicate. | |
CHECKCACHE_USE_PARENTID | Indicates whether the CheckCache statement should be done against the parent key column. | TRUE , FALSE |
CREATE_SCHEMA_PROCEDURES | Indicates stored procedures that can be used for generating schema files. |
The following query retrieves the operators that can be used in the WHERE clause:
SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'
Note that individual tables may have different limitations or requirements on the WHERE clause; refer to the Data Model section for more information.
Columns¶
Name | Type | Description |
---|---|---|
NAME | String | A component of SQL syntax, or a capability that can be processed on the server. |
VALUE | String | Detail on the supported SQL or SQL syntax. |
sys_identity¶
Returns information about attempted modifications.
The following query retrieves the Ids of the modified rows in a batch operation:
SELECT * FROM sys_identity
Columns¶
Name | Type | Description |
---|---|---|
Id | String | The database-generated ID returned from a data modification operation. |
Batch | String | An identifier for the batch. 1 for a single operation. |
Operation | String | The result of the operation in the batch: INSERTED, UPDATED, or DELETED. |
Message | String | SUCCESS or an error message if the update in the batch failed. |
Advanced Configurations Properties¶
The advanced configurations properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure. Click the links for further details.
Property | Description |
---|---|
DeveloperToken | DeveloperToken of the currently authenticated user. |
CustomerId | CustomerId of the currently authenticated user. |
UseSandbox | A boolean indicating if you are using a Sandbox account. The provider makes requests to the production environment by default. |
Property | Description |
---|---|
AccountId | The ID of the account that you want to get data for. |
Property | Description |
---|---|
AzureTenant | The Microsoft Online tenant being used to access data. If not specified, your default tenant is used. |
AzureEnvironment | The Azure Environment to use when establishing a connection. |
Property | Description |
---|---|
InitiateOAuth | Set this property to initiate the process to obtain or refresh the OAuth access token when you connect. |
OAuthClientId | The client ID assigned when you register your application with an OAuth authorization server. |
OAuthClientSecret | The client secret assigned when you register your application with an OAuth authorization server. |
OAuthAccessToken | The access token for connecting using OAuth. |
OAuthSettingsLocation | The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH . Alternatively, you can hold this location in memory by specifying a value starting with 'memory://' . |
CallbackURL | The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings. |
OAuthVerifier | The verifier code returned from the OAuth authorization URL. |
OAuthRefreshToken | The OAuth refresh token for the corresponding OAuth access token. |
OAuthExpiresIn | The lifetime in seconds of the OAuth AccessToken. |
OAuthTokenTimestamp | The Unix epoch timestamp in milliseconds when the current Access Token was created. |
Property | Description |
---|---|
SSLServerCert | The certificate to be accepted from the server when connecting using TLS/SSL. |
Property | Description |
---|---|
Location | A path to the directory that contains the schema files defining tables, views, and stored procedures. |
BrowsableSchemas | This property restricts the schemas reported to a subset of the available schemas. For example, BrowsableSchemas=SchemaA, SchemaB, SchemaC. |
Tables | This property restricts the tables reported to a subset of the available tables. For example, Tables=TableA, TableB, TableC. |
Views | Restricts the views reported to a subset of the available tables. For example, Views=ViewA, ViewB, ViewC. |
Property | Description |
---|---|
MaxRows | Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses. |
Other | These hidden properties are used only in specific use cases. |
PseudoColumns | This property indicates whether or not to include pseudo columns as columns to the table. |
ReportScopes | Allows you to narrow or broaden the scope of access when getting data from Reporting service views. |
Timeout | The value in seconds until the timeout error is thrown, canceling the operation. |
UserDefinedViews | A filepath pointing to the JSON configuration file containing your custom views. |
Authentication¶
This section provides a complete list of authentication properties you can configure.
Property | Description |
---|---|
DeveloperToken | DeveloperToken of the currently authenticated user. |
CustomerId | CustomerId of the currently authenticated user. |
UseSandbox | A boolean indicating if you are using a Sandbox account. The provider makes requests to the production environment by default. |
DeveloperToken¶
DeveloperToken of the currently authenticated user.
Data Type¶
string
Default Value¶
""
Remarks¶
DeveloperToken of the currently authenticated user.
Get a Developer Token¶
To use the Microsoft Ads APIs, you must have a DeveloperToken
in addition to the CustomerId and AccountId. You must have the Super Admin role in Microsoft Ads to create a developer token, though you do not need special permissions to use the token. BBD37VB98
may be used for sandbox accounts.
- Log in at the Bing Ads Developer Portal as a Microsoft Account user with the Microsoft Ads Super Admin role.
- Click the Request Token button and take note of your developer token. You will set it in the
DeveloperToken
connection property.
CustomerId¶
CustomerId of the currently authenticated user.
Data Type¶
string
Default Value¶
""
Remarks¶
CustomerId of the currently authenticated user.
You can find this value in the Microsoft Ads Web application, under Settings -> Accounts and Billing -> Your Account -> Account.
UseSandbox¶
A boolean indicating if you are using a Sandbox account. The provider makes requests to the production environment by default.
Data Type¶
bool
Default Value¶
false
Remarks¶
If you are using a production account, this property can be left blank. If you are using a developer test account, set this to 'TRUE'.
Connection¶
This section provides a complete list of connection properties you can configure.
Property | Description |
---|---|
AccountId | The ID of the account that you want to get data for. |
AccountId¶
The ID of the account that you want to get data for.
Data Type¶
string
Default Value¶
""
Remarks¶
If it is not specified the driver will use the first AccountId it finds from querying the API.
You can find a value either by querying Accounts table or by going to the Microsoft Ads Web application, under Settings -> Accounts and Billing -> Your Account -> Account.
Azure Authentication¶
This section provides a complete list of Azure authentication properties you can configure.
Property | Description |
---|---|
AzureTenant | The Microsoft Online tenant being used to access data. If not specified, your default tenant is used. |
AzureEnvironment | The Azure Environment to use when establishing a connection. |
AzureTenant¶
The Microsoft Online tenant being used to access data. If not specified, your default tenant is used.
Data Type¶
string
Default Value¶
common
Remarks¶
The Microsoft Online tenant being used to access data. For instance, contoso.onmicrosoft.com. Alternatively, specify the tenant Id. This value is the directory ID in the Azure Portal > Azure Active Directory > Properties.
Typically it is not necessary to specify the Tenant. This can be automatically determined by Microsoft when using the OAuthGrantType set to CODE (default). However, it may fail in the case that the user belongs to multiple tenants. For instance, if an Admin of domain A invites a user of domain B to be a guest user. The user will now belong to both tenants. It is a good practice to specify the Tenant, although in general things should normally work without having to specify it.
The AzureTenant
is required when setting OAuthGrantType to CLIENT. When using client credentials, there is no user context. The credentials are taken from the context of the app itself. While Microsoft still allows client credentials to be obtained without specifying which Tenant, it has a much lower probability of picking the specific tenant you want to work with. For this reason, we require AzureTenant
to be explicitly stated for all client credentials connections to ensure you get credentials that are applicable for the domain you intend to connect to.
AzureEnvironment¶
The Azure Environment to use when establishing a connection.
Possible Values¶
GLOBAL
, CHINA
, USGOVT
, USGOVTDOD
Data Type¶
string
Default Value¶
GLOBAL
Remarks¶
In most cases, leaving the environment set to global will work. However, if your Azure Account has been added to a different environment, the AzureEnvironment
may be used to specify which environment. The available values are GLOBAL, CHINA, USGOVT, USGOVTDOD.
OAuth¶
This section provides a complete list of OAuth properties you can configure.
Property | Description |
---|---|
InitiateOAuth | Set this property to initiate the process to obtain or refresh the OAuth access token when you connect. |
OAuthClientId | The client ID assigned when you register your application with an OAuth authorization server. |
OAuthClientSecret | The client secret assigned when you register your application with an OAuth authorization server. |
OAuthAccessToken | The access token for connecting using OAuth. |
OAuthSettingsLocation | The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH . Alternatively, you can hold this location in memory by specifying a value starting with 'memory://' . |
CallbackURL | The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings. |
OAuthVerifier | The verifier code returned from the OAuth authorization URL. |
OAuthRefreshToken | The OAuth refresh token for the corresponding OAuth access token. |
OAuthExpiresIn | The lifetime in seconds of the OAuth AccessToken. |
OAuthTokenTimestamp | The Unix epoch timestamp in milliseconds when the current Access Token was created. |
InitiateOAuth¶
Set this property to initiate the process to obtain or refresh the OAuth access token when you connect.
Possible Values¶
OFF
, GETANDREFRESH
, REFRESH
Data Type¶
string
Default Value¶
OFF
Remarks¶
The following options are available:
OFF
: Indicates that the OAuth flow will be handled entirely by the user. An OAuthAccessToken will be required to authenticate.GETANDREFRESH
: Indicates that the entire OAuth Flow will be handled by the connector. If no token currently exists, it will be obtained by prompting the user via the browser. If a token exists, it will be refreshed when applicable.REFRESH
: Indicates that the connector will only handle refreshing the OAuthAccessToken. The user will never be prompted by the connector to authenticate via the browser. The user must handle obtaining the OAuthAccessToken and OAuthRefreshToken initially.
OAuthClientId¶
The client ID assigned when you register your application with an OAuth authorization server.
Data Type¶
string
Default Value¶
""
Remarks¶
As part of registering an OAuth application, you will receive the OAuthClientId
value, sometimes also called a consumer key, and a client secret, the OAuthClientSecret.
OAuthClientSecret¶
The client secret assigned when you register your application with an OAuth authorization server.
Data Type¶
string
Default Value¶
""
Remarks¶
As part of registering an OAuth application, you will receive the OAuthClientId, also called a consumer key. You will also receive a client secret, also called a consumer secret. Set the client secret in the OAuthClientSecret
property.
OAuthAccessToken¶
The access token for connecting using OAuth.
Data Type¶
string
Default Value¶
""
Remarks¶
The OAuthAccessToken
property is used to connect using OAuth. The OAuthAccessToken
is retrieved from the OAuth server as part of the authentication process. It has a server-dependent timeout and can be reused between requests.
The access token is used in place of your user name and password. The access token protects your credentials by keeping them on the server.
OAuthSettingsLocation¶
The location of the settings file where OAuth values are saved when InitiateOAuth is set to GETANDREFRESH or REFRESH. Alternatively, you can hold this location in memory by specifying a value starting with 'memory://'
.
Data Type¶
string
Default Value¶
%APPDATA%\CData\Acumatica Data Provider\OAuthSettings.txt
Remarks¶
When InitiateOAuth is set to GETANDREFRESH
or REFRESH
, the driver saves OAuth values to avoid requiring the user to manually enter OAuth connection properties and to allow the credentials to be shared across connections or processes.
Instead of specifying a file path, you can use memory storage. Memory locations are specified by using a value starting with 'memory://'
followed by a unique identifier for that set of credentials (for example, memory://user1). The identifier can be anything you choose but should be unique to the user. Unlike file-based storage, where credentials persist across connections, memory storage loads the credentials into static memory, and the credentials are shared between connections using the same identifier for the life of the process. To persist credentials outside the current process, you must manually store the credentials prior to closing the connection. This enables you to set them in the connection when the process is started again. You can retrieve OAuth property values with a query to the sys_connection_props
system table. If there are multiple connections using the same credentials, the properties are read from the previously closed connection.
The default location is "%APPDATA%\CData\Acumatica Data Provider\OAuthSettings.txt" with %APPDATA%
set to the user's configuration directory. The default values are
- Windows: "
register://%DSN
" - Unix: "%AppData%..."
where DSN is the name of the current DSN used in the open connection.
The following table lists the value of %APPDATA%
by OS:
Platform | %APPDATA% |
---|---|
Windows | The value of the APPDATA environment variable |
Linux | ~/.config |
CallbackURL¶
The OAuth callback URL to return to when authenticating. This value must match the callback URL you specify in your app settings.
Data Type¶
string
Default Value¶
""
Remarks¶
During the authentication process, the OAuth authorization server redirects the user to this URL. This value must match the callback URL you specify in your app settings.
OAuthVerifier¶
The verifier code returned from the OAuth authorization URL.
Data Type¶
string
Default Value¶
""
Remarks¶
The verifier code returned from the OAuth authorization URL. This can be used on systems where a browser cannot be launched such as headless systems.
Authentication on Headless Machines¶
See to obtain the OAuthVerifier
value.
Set OAuthSettingsLocation along with OAuthVerifier
. When you connect, the connector exchanges the OAuthVerifier
for the OAuth authentication tokens and saves them, encrypted, to the specified location. Set InitiateOAuth to GETANDREFRESH to automate the exchange.
Once the OAuth settings file has been generated, you can remove OAuthVerifier
from the connection properties and connect with OAuthSettingsLocation set.
To automatically refresh the OAuth token values, set OAuthSettingsLocation and additionally set InitiateOAuth to REFRESH.
OAuthRefreshToken¶
The OAuth refresh token for the corresponding OAuth access token.
Data Type¶
string
Default Value¶
""
Remarks¶
The OAuthRefreshToken
property is used to refresh the OAuthAccessToken when using OAuth authentication.
OAuthExpiresIn¶
The lifetime in seconds of the OAuth AccessToken.
Data Type¶
string
Default Value¶
""
Remarks¶
Pair with OAuthTokenTimestamp to determine when the AccessToken will expire.
OAuthTokenTimestamp¶
The Unix epoch timestamp in milliseconds when the current Access Token was created.
Data Type¶
string
Default Value¶
""
Remarks¶
Pair with OAuthExpiresIn to determine when the AccessToken will expire.
SSL¶
This section provides a complete list of SSL properties you can configure.
Property | Description |
---|---|
SSLServerCert | The certificate to be accepted from the server when connecting using TLS/SSL. |
SSLServerCert¶
The certificate to be accepted from the server when connecting using TLS/SSL.
Data Type¶
string
Default Value¶
""
Remarks¶
If using a TLS/SSL connection, this property can be used to specify the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected.
This property can take the following forms:
Description | Example |
---|---|
A full PEM Certificate (example shortened for brevity) | -----BEGIN CERTIFICATE----- MIIChTCCAe4CAQAwDQYJKoZIhv......Qw== -----END CERTIFICATE----- |
A path to a local file containing the certificate | C:\\cert.cer |
The public key (example shortened for brevity) | -----BEGIN RSA PUBLIC KEY----- MIGfMA0GCSq......AQAB -----END RSA PUBLIC KEY----- |
The MD5 Thumbprint (hex values can also be either space or colon separated) | ecadbdda5a1529c58a1e9e09828d70e4 |
The SHA1 Thumbprint (hex values can also be either space or colon separated) | 34a929226ae0819f2ec14b4a3d904f801cbb150d |
If not specified, any certificate trusted by the machine is accepted.
Certificates are validated as trusted by the machine based on the System's trust store. The trust store used is the 'javax.net.ssl.trustStore' value specified for the system. If no value is specified for this property, Java's default trust store is used (for example, JAVA_HOME\lib\security\cacerts).
Use '*' to signify to accept all certificates. Note that this is not recommended due to security concerns.
Schema¶
This section provides a complete list of schema properties you can configure.
Property | Description |
---|---|
Location | A path to the directory that contains the schema files defining tables, views, and stored procedures. |
BrowsableSchemas | This property restricts the schemas reported to a subset of the available schemas. For example, BrowsableSchemas=SchemaA, SchemaB, SchemaC. |
Tables | This property restricts the tables reported to a subset of the available tables. For example, Tables=TableA, TableB, TableC. |
Views | Restricts the views reported to a subset of the available tables. For example, Views=ViewA, ViewB, ViewC. |
Location¶
A path to the directory that contains the schema files defining tables, views, and stored procedures.
Data Type¶
string
Default Value¶
%APPDATA%\BingAds Data Provider\Schema
Remarks¶
The path to a directory which contains the schema files for the connector (.rsd files for tables and views, .rsb files for stored procedures). The folder location can be a relative path from the location of the executable. The Location
property is only needed if you want to customize definitions (for example, change a column name, ignore a column, and so on) or extend the data model with new tables, views, or stored procedures.
If left unspecified, the default location is "%APPDATA%\BingAds Data Provider\Schema" with %APPDATA%
being set to the user's configuration directory:
Platform | %APPDATA% |
---|---|
Windows | The value of the APPDATA environment variable |
Mac | ~/Library/Application Support |
Linux | ~/.config |
BrowsableSchemas¶
This property restricts the schemas reported to a subset of the available schemas. For example, BrowsableSchemas=SchemaA,SchemaB,SchemaC.
Data Type¶
string
Default Value¶
""
Remarks¶
Listing the schemas from databases can be expensive. Providing a list of schemas in the connection string improves the performance.
Tables¶
This property restricts the tables reported to a subset of the available tables. For example, Tables=TableA,TableB,TableC.
Data Type¶
string
Default Value¶
""
Remarks¶
Listing the tables from some databases can be expensive. Providing a list of tables in the connection string improves the performance of the connector.
This property can also be used as an alternative to automatically listing views if you already know which ones you want to work with and there would otherwise be too many to work with.
Specify the tables you want in a comma-separated list. Each table should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Tables=TableA,[TableB/WithSlash],WithCatalog.WithSchema.`TableC With Space`.
Note that when connecting to a data source with multiple schemas or catalogs, you will need to provide the fully qualified name of the table in this property, as in the last example here, to avoid ambiguity between tables that exist in multiple catalogs or schemas.
Views¶
Restricts the views reported to a subset of the available tables. For example, Views=ViewA,ViewB,ViewC.
Data Type¶
string
Default Value¶
""
Remarks¶
Listing the views from some databases can be expensive. Providing a list of views in the connection string improves the performance of the connector.
This property can also be used as an alternative to automatically listing views if you already know which ones you want to work with and there would otherwise be too many to work with.
Specify the views you want in a comma-separated list. Each view should be a valid SQL identifier with any special characters escaped using square brackets, double-quotes or backticks. For example, Views=ViewA,[ViewB/WithSlash],WithCatalog.WithSchema.`ViewC With Space`.
Note that when connecting to a data source with multiple schemas or catalogs, you will need to provide the fully qualified name of the table in this property, as in the last example here, to avoid ambiguity between tables that exist in multiple catalogs or schemas.
Miscellaneous¶
This section provides a complete list of miscellaneous properties you can configure.
Property | Description |
---|---|
MaxRows | Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses. |
Other | These hidden properties are used only in specific use cases. |
PseudoColumns | This property indicates whether or not to include pseudo columns as columns to the table. |
ReportScopes | Allows you to narrow or broaden the scope of access when getting data from Reporting service views. |
Timeout | The value in seconds until the timeout error is thrown, canceling the operation. |
UserDefinedViews | A filepath pointing to the JSON configuration file containing your custom views. |
MaxRows¶
Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses.
Data Type¶
int
Default Value¶
-1
Remarks¶
Limits the number of rows returned when no aggregation or GROUP BY is used in the query. This takes precedence over LIMIT clauses.
Other¶
These hidden properties are used only in specific use cases.
Data Type¶
string
Default Value¶
""
Remarks¶
The properties listed below are available for specific use cases. Normal driver use cases and functionality should not require these properties.
Specify multiple properties in a semicolon-separated list.
Integration and Formatting¶
Property | Description |
---|---|
DefaultColumnSize | Sets the default length of string fields when the data source does not provide column length in the metadata. The default value is 2000. |
ConvertDateTimeToGMT | Determines whether to convert date-time values to GMT, instead of the local time of the machine. |
RecordToFile=filename | Records the underlying socket data transfer to the specified file. |
PseudoColumns¶
This property indicates whether or not to include pseudo columns as columns to the table.
Data Type¶
string
Default Value¶
""
Remarks¶
This setting is particularly helpful in Entity Framework, which does not allow you to set a value for a pseudo column unless it is a table column. The value of this connection setting is of the format "Table1=Column1, Table1=Column2, Table2=Column3". You can use the "*" character to include all tables and all columns; for example, "*=*".
ReportScopes¶
Allows you to narrow or broaden the scope of access when getting data from Reporting service views.
Data Type¶
string
Default Value¶
""
Remarks¶
For example, the AccountPerformanceReport, CampaignPerformanceReport, AdGroupPerformanceReport, and other views with Report in the name are part of the Report Service.
You can specify the scope so that you include specific Accounts, Campaigns or AdGroups.
- Accounts should be specified in this format:
AccountId, AccountId, AccountId;
- Campaigns should be specified in this comma-separated format:
CampaignId:AccountId, CampaignId:AccountId;
- AdGroups should be specified in this format (again, comma-separated):
AdGroupId:CampaignId:AccountId, AdGroupId:CampaignId:AccountId, AdGroupId:CampaignId:AccountId;
Here are a few examples:
- ReportScopes=
'Accounts=1494730,969378; Campaigns=234401540:18503857,1730399:96740690; AdGroups=1958:9607:1655,0973:192782:1655;';
- ReportScopes=
'AdGroups=1958:9607:1655, 0973:192782:1655;';
- ReportScopes=
'Campaigns=234401540:18503857, 1730399:96740690;';
- ReportScopes=
'Accounts=1494730,969378;';
By default this connection property will be empty. In that case the driver uses the first AccountId that it finds from querying the API.
You can specify up to 1000 Accounts, 300 Campaigns and 300 AdGroups.
Timeout¶
The value in seconds until the timeout error is thrown, canceling the operation.
Data Type¶
int
Default Value¶
60
Remarks¶
If Timeout
= 0, operations do not time out. The operations run until they complete successfully or until they encounter an error condition.
If Timeout
expires and the operation is not yet complete, the connector throws an exception.
UserDefinedViews¶
A filepath pointing to the JSON configuration file containing your custom views.
Data Type¶
string
Default Value¶
""
Remarks¶
User Defined Views are defined in a JSON-formatted configuration file called UserDefinedViews.json
. The connector automatically detects the views specified in this file.
You can also have multiple view definitions and control them using the UserDefinedViews
connection property. When you use this property, only the specified views are seen by the connector.
This User Defined View configuration file is formatted as follows:
- Each root element defines the name of a view.
- Each root element contains a child element, called
query
, which contains the custom SQL query for the view.
For example:
{
"MyView": {
"query": "SELECT * FROM AdGroups WHERE MyColumn = 'value'"
},
"MyView2": {
"query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
}
}
Use the UserDefinedViews
connection property to specify the location of your JSON configuration file. For example:
"UserDefinedViews", C:\Users\yourusername\Desktop\tmp\UserDefinedViews.json
Note that the specified path is not embedded in quotation marks.