Campaign entities including ads and keywords can be downloaded individually, in groups, or in bulk. The bulk download service lets you download campaign data in the background.
For information about related programming elements, see Bulk Service Reference.
If you keep a local cache of your campaign data, you should use this service instead of calling the campaign management service’s entity operations, such as GetAdGroupsByCampaignId and GetKeywordsByAdGroupId to get your campaign’s data.
Bulk Download Overview
To download an account’s campaign data, call the DownloadCampaignsByAccountIds operation. To download the data of specific campaigns, call the DownloadCampaignsByCampaignIds operation. You can request all of the campaign’s data or only the data that has changed since the last time you downloaded the campaign’s data.
By default, only the campaign, ad group, ad, and keyword entities are included in the download. However, you can set the AdditionalEntities element of the request to include other campaign and ad group entities such as negative keywords and targets in the download. For a list of additional entities that you can request, see the AdditionalEntity value set.
Typically, the first time that you request a download, you set the LastSyncTimeInUTC element of the request to NULL to download all entities of the campaign. Then, in subsequent requests, you would set LastSyncTimeInUTC to the time stamp of the last download in order to download only those entities that have changed (been updated or deleted) since the last download. After the initial full download, the only time that you must request a full download is if the account was included in a data migration (for example, the URL by match type migration). If you specify a last sync time that predates the end of the migration process, the download will fail with FullSyncRequired (error code 3603).
The download request returns an identifier that you pass to the GetDownloadStatus operation. You call the GetDownloadStatus operation in a loop until the download completes or fails.
The length of time that it takes the download to complete depends on a number of variables, such as the number of campaigns that you requested and the number of requests that are already in the queue. Because of these variables, the polling interval that you use may vary. However, most small requests should complete within minutes, so consider polling at one to two minute intervals for small requests. For medium requests, consider polling at one to two minute intervals after waiting five to 15 minutes. For large requests, consider polling at one to two minute intervals after waiting 30 minutes. If the overall polling period exceeds 60 minutes, consider exiting the loop and trying again later.
When the GetDownloadStatus operation completes successfully, it returns the URL of the download file. Use the URL to copy the download file locally. The URL must be used within five minutes of the time that the GetDownloadStatus operation returns a Success status code. If you do not start the download within this period of time, you will need to call GetDownloadStatus again to get a new URL.
You have five days to download the file from the time it becomes available. If you have not successfully downloaded the file within this period, it is removed from the download site and you will need to call one of the download operations again.
The download file is compressed (in zip format), so you must unzip the file to access the data. The download file is an XML file. For information about the schema used for the download file, see Bulk Download Schema.
Bulk Download Best Practices
Perform a full download one time only. Thereafter, perform delta downloads. (Set the LastSyncTimeInUTC to the time stamp of the last download. The download file contains the time stamp of the download in the SyncTime element of the Customers object.) There is no advantage to performing a full download every time and it decreases everyone’s performance including yours.
The only time that you must perform a subsequent full download is if the account was included in a data migration (for example, the URL by match type migration). If you specify a last sync time that predates the end of the migration process, the download will fail with FullSyncRequeired (error code 3603).
Poll for downloads at reasonable intervals. You know your data better than anyone. If you download an account that is well less than one million keywords, consider polling at one to two minute intervals. If the account contains about one million keywords, consider polling at one minute intervals after waiting five minutes. For accounts with about four million keywords, consider polling at one minute intervals after waiting 30 minutes.
Call the DownloadCampaignsByCampaignIds operation if the account contains more than four million keywords. Calling the DownloadCampaignsByAccountIds operation with an account that contains more than four million keywords will fail.
Include fewer campaigns in your DownloadCampaignsByCampaignIds request. Requests that specify fewer campaigns per call typically complete sooner than calls that specify the maximum number allowed.
Request only those additional entities that you require.