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 |
---|---|---|---|
|
The ID of the advertiser whose data will be downloaded |
long |
Yes |
|
The entity level of the requested data. Supported values:
|
enum |
Yes |
|
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 |
|
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 |
|
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 |
---|---|
|
The ID of the submitted job. Use this id to poll the status of the job. |
|
The initial status of a job that was successfully submitted will be ‘submitted’. |
|
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 |
---|---|---|---|
|
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 |
|
The parent type of the the objects to be downloaded. The parent type can be CAMPAIGN or ADGROUP. The 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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Indicates whether negative keywords will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “false” if not specified. |
boolean |
Optional |
|
Indicates whether targeting objects will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “false” if not specified. |
boolean |
Optional |
|
Indicates whether ad extensions will be downloaded. Can be set to “TRUE” or “FALSE”, and will default to “FALSE” if not specified. |
boolean |
Optional |
|
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.