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.