Bulk operations

Overview

The Gemini bulk operations API allows you to download and edit all the objects in your advertiser account using a spreadsheet in CSV format. You can generate and download a bulk file using the bulk download service. You can also create and edit objects in bulk using the bulk upload service.

When you use the bulk operations API, you are effectively creating asynchronous jobs that are executed by Gemini. Upon submitting a job you will receive an id that you can use to poll the status of your job. When your job is completed, you will receive a token that will enable you to securely download your results.

Gemini bulk schema

Gemini bulk files are tab-separated CSVs. The encoding is UTF16-LE with BOM. On uploads, both comma and tab delimiters are supported. Note that comma separated files need to be encoded in UTF8 and tab separated files needs to be encoded in UTF16LE with BOM.

It is recommended that the file be compressed for upload. When a compressed file is uploaded, the job results will be compressed as well. Compressed files can be uploaded in either zip or gzip format.

For information on working with the Gemini bulk schema, refer to Get Started with Gemini Bulk File Fields and Object Types.

Note

The last two columns in the bulk schema, “Created Date” and “Last Update Date”, are always populated when using the Gemini APIs, regardless of the API request. These specify the creation timestamp for the entity/object type described on the CSV line, and the last updated timestamp, respectively (as long as there is no error on the line). They are both read-only. The format is yyyy-mm-dd hh:mm:ss. For example: 2015-08-29 00:11:55.

Limits

Bulk file limit is 1GB. For downloads, it is recommended to set compressedFile to “TRUE”. If compressedFile was not set to “TRUE” and the result file exceeded 1GB, an error will be thrown. The compressed results file will still be available for downloading using the token provided in the response.

The CSV generated will expire after 30 days.

Bulk download

Endpoint

https://api.admanager.yahoo.com/v1/rest/bulk/download

Submit a job

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

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
filters The following optional filters can be used:    
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

Here is a sample request body for a download job:

 {
  "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
  }
}

Response: The following is 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 in order 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 will provide the token required to download the requested data.

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.

Bulk upload

Endpoint

https://api.admanager.yahoo.com/v1/rest/bulk/upload

Submit a job

Call: To upload a bulk file, make a POST call to the bulk/upload endpoint, passing in the advertiser id in the URL. Here is an example of a request to upload a bulk file for advertiser id 123: https://api.admanager.yahoo.com/v1/rest/bulk/upload/?advertiserId=123 The CSV file you are uploading should be embedded as form-data within the “file” field. Compressed files are accepted. When uploading a compressed file, the results file will be automatically compressed.

Response:The following is a sample response when submitting a job:

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

The response includes the following fields:

Name Description
jobId The ID of the submitted job. Use this id in order 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 will have details on the results of the job.

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.

Get job status

Call: To query the status of your request, make a GET call to

/bulk/status/?jobId={jobId}&advertiserId={advertiserId}

For example, in order to check the status of jobId 4196 that requested data for advertiser 30944, make the following GET call:

Response - download: The following is a sample response of a bulk download job:

{
  "errors": null,
  "response": {
      "jobId": 14151,
      "status": "completed",
              "jobResponse": "iY.mAQcBTiZfotBOtMDnYDUsothZsIbpfg0bP58oKXbAA6VJlCwuuV2oNsNhGQ7tVcEfVM2NVsIsUoo8EYOj135iBehdHZAF9mPlTBmq9JfWbGLJ9OUpD2JWSwlROI9Kj1Pjo.4PQ65zGMowH5D0zTzqWumt8mHWP.E8n8NtcD2F"
                 }
 }

Upon successful completion, the response will include the token you will need to securely download your file with the requested data. This file is available to be downloaded within 30 days of the job’s completion. The meaning of the possible statuses are detailed below:

Name Description
submitted The job is in queue but work on it has yet to commence.
running The job is running.
failed The job ran but unexpectedly failed.
killed The job was killed, typically due to failure to complete in a timely manner.
completed The job completed successfully.

Response - upload: the following is a sample response of an upload job upon completion:

{
  "errors": null,
  "timestamp": "2016-01-11 18:17:04",
  "response": {
      "jobId": 55334,
      "status": "completed",
      "jobResponse": {
          "Radius_Target": {
              "totalCount": 1,
              "addedCount": 1,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Product_Group": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Ad": {
              "totalCount": 11,
              "addedCount": 7,
              "updatedCount": 1,
              "deletedCount": 1,
              "failedCount": 2,
              "systemFailedCount": 0,
              "userFailedCount": 2
          },
          "Keyword": {
              "totalCount": 23,
              "addedCount": 22,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 1,
              "systemFailedCount": 0,
              "userFailedCount": 1
          },
          "Age_Target": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Custom_Audience": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Site_Exclusion": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Invalid_Row": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Sitelink_Extension": {
              "totalCount": 3,
              "addedCount": 2,
              "updatedCount": 1,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Segment_Target": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Location_Extension": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Call_Extension": {
              "totalCount": 1,
              "addedCount": 1,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Location_Target": {
              "totalCount": 7,
              "addedCount": 6,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 1,
              "systemFailedCount": 0,
              "userFailedCount": 1
          },
          "Campaign": {
              "totalCount": 4,
              "addedCount": 3,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 1,
              "systemFailedCount": 0,
              "userFailedCount": 1
          },
          "Gender_Target": {
              "totalCount": 2,
              "addedCount": 2,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Ad_Schedule": {
              "totalCount": 1,
              "addedCount": 1,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Device_Target": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Ad_Group": {
              "totalCount": 4,
              "addedCount": 3,
              "updatedCount": 1,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Product_Filter": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "Interest_Target": {
              "totalCount": 5,
              "addedCount": 4,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 1,
              "systemFailedCount": 0,
              "userFailedCount": 1
          },
          "OS_Version_Target": {
              "totalCount": 0,
              "addedCount": 0,
              "updatedCount": 0,
              "deletedCount": 0,
              "failedCount": 0,
              "systemFailedCount": 0,
              "userFailedCount": 0
          },
          "resultFile": "tU3AUiFGlxtgGw4d0P2wivIqbdQokgJqhJSEen2.AmRLcozFrU0iOdjpF.UkybgHrldx6x.cMVpuC5HQzKO6WmdXd51j56SH00kqsvBHoOy0RAiK132s5Vaa_p8rDHcwxMizSYALyhJ5GHWN_NRQ9yw-~A"
      }
  }
}

When an upload job completes, the jobResponse will include details on the number of added, updated, deleted and failed objects for each object type. The resultFile field will include a token that should be used to download the result file. The result file is a spreadsheet that has one row for every object that was passed and includes error messages for failed objects.

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.admanager.yahoo.com/v1/rest/bulk/read/ endpoint and passing in the token you received in either the resultFile or the jobResponse using the resource parameter.

Here is an example:

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

Important

Bulk Download does not currently work if you want to Download only Product Group object types. There is a workaround, however, which you can use. If you change the objectType to Campaign and download the entire campaign, it will work.