Bing Ads

This page contains the setup guide and reference information for the Bing Ads source connector.

Setup guide

Step 1: Set up Bing Ads

1. Register your application in the Azure portal.
2. Request user consent to get the authorization code.
3. Use the authorization code to get a refresh token.

note

The refresh token expires in 90 days. Repeat the authorization process to get a new refresh token. The full authentication process described here. Please be sure to authenticate with the email (personal or work) that you used to sign in to the Bing ads/Microsoft ads platform.

4. Get your Microsoft developer token.
5. If your OAuth app has a custom tenant and you cannot use Microsoft’s recommended common tenant, use the custom tenant in the Tenant ID field when you set up the connector.

info

The tenant is used in the authentication URL, for example: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize

Step 2: Set up the source connector in Airbyte

For Airbyte Cloud:

1. Log in to your Airbyte Cloud account.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Bing Ads from the Source type dropdown.
4. Enter a name for your source.
5. For Tenant ID, enter the custom tenant or use the common tenant.
6. Add the developer token from Step 1.
7. For Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
8. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode, let it with 0 default value.
9. Click Authenticate your Bing Ads account.
10. Log in and authorize the Bing Ads account.
11. Click Set up source.

For Airbyte Open Source:

1. Log in to your Airbyte Open Source account.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Bing Ads from the Source type dropdown.
4. Enter a name for your source.
5. For Tenant ID, enter the custom tenant or use the common tenant.
6. Enter the Client ID, Client Secret, Refresh Token, and Developer Token from Step 1.
7. For Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
8. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode, let it with 0 default value.
9. Click Set up source.

Supported sync modes

The Bing Ads source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental - Append
• Incremental - Append + Deduped

Supported Streams

The Bing Ads source connector supports the following streams. For more information, see the Bing Ads API.

Basic streams

• accounts
• ad_groups
• ads
• campaigns

Report Streams

• account_performance_report_hourly
• account_performance_report_daily
• account_performance_report_weekly
• account_performance_report_monthly
• account_impression_performance_report_hourly
• account_impression_performance_report_daily
• account_impression_performance_report_weekly
• account_impression_performance_report_monthly
• ad_group_performance_report_hourly
• ad_group_performance_report_daily
• ad_group_performance_report_weekly
• ad_group_performance_report_monthly
• ad_performance_report_hourly
• ad_performance_report_daily
• ad_performance_report_weekly
• ad_performance_report_monthly
• age_gender_audience_report_hourly
• age_gender_audience_report_daily
• age_gender_audience_report_weekly
• age_gender_audience_report_monthly
• geographic_performance_report_hourly
• geographic_performance_report_daily
• geographic_performance_report_weekly
• geographic_performance_report_monthly
• budget_summary_report
• campaign_performance_report_hourly
• campaign_performance_report_daily
• campaign_performance_report_weekly
• campaign_performance_report_monthly
• keyword_performance_report_hourly
• keyword_performance_report_daily
• keyword_performance_report_weekly
• keyword_performance_report_monthly
• user_location_performance_report_hourly
• user_location_performance_report_daily
• user_location_performance_report_weekly
• user_location_performance_report_monthly

Report aggregation

All reports synced by this connector can be aggregated using hourly, daily, weekly, or monthly time windows.

For example, if you select a report with daily aggregation, the report will contain a row for each day for the duration of the report. Each row will indicate the number of impressions recorded on that day.

A report's aggregation window is indicated in its name. For example, account_performance_report_hourly is the Account Performance Reported aggregated using an hourly window.

Performance considerations

The Bing Ads API limits the number of requests for all Microsoft Advertising clients. You can find detailed info here.

Changelog

Version	Date	Pull Request	Subject
1.4.0	2023-10-27	31885	Add new stream: AccountImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.3.0	2023-10-26	31837	Add new stream: UserLocationPerformanceReport (daily, hourly, weekly, monthly)
1.2.0	2023-10-24	31783	Add new stream: SearchQueryPerformanceReport (daily, hourly, weekly, monthly)
1.1.0	2023-10-24	31712	Add new stream: AgeGenderAudienceReport (daily, hourly, weekly, monthly)
1.0.2	2023-10-19	31599	Base image migration: remove Dockerfile and use the python-connector-base image
1.0.1	2023-10-16	31432	Remove primary keys from the geographic performance reports - complete what was missed in version 1.0.0
1.0.0	2023-10-11	31277	Remove primary keys from the geographic performance reports.
0.2.3	2023-09-28	30834	Wrap auth error with the config error.
0.2.2	2023-09-27	30791	Fix missing fields for geographic performance reports.
0.2.1	2023-09-04	30128	Add increasing download timeout if ReportingDownloadException occurs
0.2.0	2023-08-17	27619	Add Geographic Performance Report
0.1.24	2023-06-22	27619	Retry request after facing temporary name resolution error.
0.1.23	2023-05-11	25996	Implement a retry logic if SSL certificate validation fails.
0.1.22	2023-05-08	24223	Add CampaignLabels report column in campaign performance report
0.1.21	2023-04-28	25668	Add undeclared fields to accounts, campaigns, campaign_performance_report, keyword_performance_report and account_performance_report streams
0.1.20	2023-03-09	23663	Add lookback window for performance reports in incremental mode
0.1.19	2023-03-08	23868	Add dimensional-type columns for reports.
0.1.18	2023-01-30	22073	Fix null values in the Keyword column of keyword_performance_report streams
0.1.17	2022-12-10	20005	Add Keyword to keyword_performance_report stream
0.1.16	2022-10-12	17873	Fix: added missing campaign types in (Audience, Shopping and DynamicSearchAds) in campaigns stream
0.1.15	2022-10-03	17505	Fix: limit cache size for ServiceClient instances
0.1.14	2022-09-29	17403	Fix: limit cache size for ReportingServiceManager instances
0.1.13	2022-09-29	17386	Migrate to per-stream states.
0.1.12	2022-09-05	16335	Added backoff for socket.timeout
0.1.11	2022-08-25	15684 (published in 15987)	Fixed log messages being unreadable
0.1.10	2022-08-12	15602	Fixed bug caused Hourly Reports to crash due to invalid fields set
0.1.9	2022-08-02	14862	Added missing columns
0.1.8	2022-06-15	13801	All reports hourly/daily/weekly/monthly will be generated by default, these options are removed from input configuration
0.1.7	2022-05-17	12937	Added OAuth2.0 authentication method, removed redirect_uri from input configuration
0.1.6	2022-04-30	12500	Improve input configuration copy
0.1.5	2022-01-01	11652	Rebump attempt after DockerHub failure at registring the 0.1.4
0.1.4	2022-03-22	11311	Added optional Redirect URI & Tenant ID to spec
0.1.3	2022-01-14	9510	Fixed broken dependency that blocked connector's operations
0.1.2	2021-12-14	8429	Update titles and descriptions
0.1.1	2021-08-31	5750	Added reporting streams)
0.1.0	2021-07-22	4911	Initial release supported core streams (Accounts, Campaigns, Ads, AdGroups)