Bulk Download API

Abstract

Download bulk files by making standard POST and GET calls in the API.

Download Endpoint

https://api.gemini.yahoo.com/v3/rest/bulk/download

Submit a Job

To download a bulk file, make a POST call to the bulk download endpoint and pass the following in the request body:

 {
  "advertiserId": 30944,
  "objectType": "CAMPAIGN",
  "downloadAllLevels": true,
  "filters": {
             "objectIds": [123,
                456
             ],
             "objectStatus": [
                "ACTIVE"
             ],
             "fromDate": "2014-07-01 00:00:00",
             "toDate": "2014-07-10 00:00:00",
                         "includeNegative":true,
                         "includeTargeting":true,
                         "includeExtensions":true
  }
}

Fields

Name Description Type Required
advertiserId The ID of the advertiser whose data will be downloaded long Yes
objectType

The entity level of the requested data. Supported values:

  • ADVERTISER
  • CAMPAIGN
  • ADGROUP
  • AD
  • KEYWORD
enum Yes
       
downloadAllLevels Indicates whether all descendants of the requested objects will be downloaded as well. This field accepts either “TRUE” or “FALSE”, and will default to “FALSE” if not specified. boolean Optional
compressedFile Indicates whether the downloaded file should be compressed. Can be set to “TRUE” or “FALSE”, and will default to “FALSE” if not specified. boolean Optional
skipExcelSpecificCharFixes Indicates whether the downloaded file should skip special Microsoft Excel fixes for inserting a leading space in front of Excel-specific characters (+,-,=) and inserting a leading single quote ‘ in front of a integer with 11 or more characters. Will default to “FALSE” if not specified. boolean Optional

Response

A sample response when submitting a download job:

{
  "errors": null,
  "response": {
   "jobId": 4196,
   "status": "submitted",
   "jobResponse": null
  }
}

The response includes the following fields:

Name Description
jobId The ID of the submitted job. Use this id to poll the status of the job.
status The initial status of a job that was successfully submitted will be ‘submitted’.
jobResponse When the job is completed, this field provides the token required to download the requested data.

Filters

The following download filters are available:

Name Description Type Required
parentIds The list of parent ids of the objects to be downloaded. This should be used with the parentType filter. A list should not exceed 1000 ids. long Yes
parentType

The parent type of the the objects to be downloaded. The parent type can be CAMPAIGN or ADGROUP. The parentType is only supported with KEYWORD, AD and ADGROUP object types.

ADGROUP parent type can be used with the parentIds filter to download KEYWORD and AD objects.

CAMPAIGN parent type can be used with the parentIds filter to download NEGATIVE KEYWORD assigned to the campaign level and ADGROUP objects.

If parent ids are not specified, then the default behavior will apply (parentType in this case has no effect). Only For KEYWORD object type parentType can be either ADGROUP or CAMPAIGN. In the case of CAMPAIGN (which is the default), all keywords of the account will be downloaded. In the case of ADGROUP, only the account ADGROUP’s keywords will be downloaded.

string Optional
       
objectIds The list of ids of the objects to be downloaded. If none are specified, then all objects for that level will be downloaded. A list should not exceed 1000 ids. long Optional
objectStatus Download only objects in a certain status. For example, status=[”ACTIVE”] will result in downloading only active objects. Refer to the API objects documentation for more information on supported statuses. This filter accepts a list of statuses. enum Optional
fromDate This filter specifies that only objects that were changed since this timestamp should be downloaded. The format is yyyy-mm-dd hh:mm:ss or yyyy-mm-dd. string Optional
toDate This filter specifies that only objects that were changed before this timestamp should be downloaded. The format is yyyy-mm-dd hh:mm:ss or yyyy-mm-dd. string Optional
includeNegative Indicates whether negative keywords will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “false” if not specified. boolean Optional
includeTargeting Indicates whether targeting objects will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “false” if not specified. boolean Optional
includeExtensions Indicates whether ad extensions will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “FALSE” if not specified. boolean Optional
includeAdSiteSettings Indicates whether ad site settings will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “FALSE” if not specified. boolean Optional

Example

{
      "advertiserId": 88922,
      "objectType": "KEYWORD",
      "filters": {
              "parentType": "ADGROUP",
              "parentIds": [
                      9690487560,
                      9685254736
              ]
      }
}

{
      "advertiserId": 88922,
      "objectType": "AD",
      "filters": {
              "parentType": "ADGROUP",
              "parentIds": [
                      9690487560,
                      9685254736
              ]
      }
}

Date filters are applied from top level to bottom level objects (campaign -> campaign level targeting including ad schedules -> ad group -> ad group level targeting -> ad). This means, in cases where the date filters are used, the children ad object data will not be fetched if the parent ad object was not changed in the date range specified.

Important

To download information at all levels (campaign down to all its children entities), make a bulk call for each level (for example, one for campaign, one for ad group and so on). This is a best practice for handling date filters.

Poll Status

Once the job has been submitted, you can poll the job’s status until its completion. You should poll the status at reasonable intervals given the estimated size of your requested data.

Download Job Results

Once the job has completed, you will need to either download your requested data (on a download job) or get your results file (on an upload job). You can do this by making a GET call to the

https://api.gemini.yahoo.com/v3/rest/bulk/read/

endpoint and passing in the token you received in either the resultFile or the jobResponse using the resource parameter.

Example

https://api.gemini.yahoo.com/v3/rest/bulk/read/?resource=iY.mAQcBTiZcZfotBOtNMDnYDUsothZsIbVpfg0bP5R8oKXbAA6VJlCwuuV2oNsNhGQ7tVcEfVM2pNVsIsUoo8EYOj135iBehdHZAF9mPlTBmq9JfWbGLM9OUpD2JWSwlROI9Kj1Pjo.4PQ65zGMowH5D0zTzqlxWumt8mHWP.E8n8NtcD2F

Important

Bulk Download does not work if you want to Download-only Product Group object types. A workaround is available. If you change the objectType to Campaign and download the entire campaign, it will work.