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.