Bulk operations¶
The Yahoo Native 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 Yahoo Native. 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.
Yahoo Native Bulk Schema¶
Yahoo Native 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 Yahoo Native bulk schema, refer to Get Started with Native 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 Yahoo Native 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.
Note
In order to prevent any issues when new backward compatible columns are added to the bulk schema, you should parse by column name and not by any specific column orders.
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.
New Bulk filters¶
The following new filters have been added to bulk. Support is provided for v1, v2 and v3 versions of the API.
Name |
Description |
---|---|
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. |
parentType |
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 parentIds filter to download KEYWORD and AD objects. CAMPAIGN parent type can be used with 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. |
Example JSON representations¶
{
"advertiserId": 88922,
"objectType": "KEYWORD",
"filters": {
"parentType": "ADGROUP",
"parentIds": [
9690487560,
9685254736
]
}
}
{
"advertiserId": 88922,
"objectType": "AD",
"filters": {
"parentType": "ADGROUP",
"parentIds": [
9690487560,
9685254736
]
}
}
Bulk changes in v3 Yahoo Native API¶
The following describes the fields available in Site X Device Targeting:
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Site |
The site name to target. |
enum |
Required |
Required |
For more information on this targeting attribute in Bulk, refer to Site X Device Targeting.
For information on this new targeting type in the v3 Yahoo Native API, as well as a new bid modifier, refer to Targeting Attributes.
Bulk schema changes in v2 Yahoo Native API¶
Important
One of the primary goals of the v2 Yahoo Native API has been to provide partners and developers with a unified format for bulk operations and data representation.
Because bulk file upload and download operations behave differently in v2 Yahoo Native than in v1, there are breaking changes you may wish to consider when coding and integrating your apps.
In the v1 Yahoo Native API, targeting attributes – like age, gender and device – utilized an Object ID to populate the targeting attribute entity ID in the result file. Exceptions to this rule included interest, custom audience and location targeting, all of which overloaded the Object ID to store either the Segment ID or Location WOEID. Because of these exceptions, v1 Yahoo Native API did not populate the entity IDs for these targeting attributes in bulk files.
To consolidate all targeting attributes in bulk files to a single, unified standard, as well as expose targeting attribute entity IDs for all objects, the v2 Yahoo Native API includes the following set of changes, described in the tables below.
Interest Target v1
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The ID of interest. |
long |
Required |
Required |
Interest Target v2
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The ID of the targeting attribute. |
long |
Read-Only/Optional |
Read-Only/Optional |
Segment ID |
The ID of interest. |
long |
Required |
Required |
Custom Audience v1
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The ID of the custom audience. |
long |
Required |
Required |
Custom Audience v2
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The ID of the targeting attribute. |
long |
Read-Only/Optional |
Read-Only/Optional |
Segment ID |
The ID of the custom audience. |
long |
Required |
Required |
Location Target v1
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The Object ID of the location. Optional when specifying the WOEID value. Required for creates if the Location field is not used. |
long |
Optional |
Required |
Location |
The name of the geographic location associated with the Object ID. Required for creates if the Object ID field is not used. |
string |
Optional |
Read-Only |
Location Target v2
Name |
Description |
Type |
Add |
Delete |
---|---|---|---|---|
Object ID |
The ID of the targeting attribute entity. |
long |
Read-Only/Optional |
Read-Only/Optional |
Location |
The name of the geographic location associated with the Location ID. Required for creates if the |
string |
Optional |
Read-Only |
Location ID |
The Location ID of the location. Optional when specifying the WOEID value. Required for creates if the |
long |
Optional |
Required |
Bulk download¶
Endpoint
https://api.gemini.yahoo.com/v3/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 |
---|---|---|---|
|
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 |
filters |
The following optional filters can be used: |
||
|
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 |
The following 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 |
---|---|
|
The ID of the submitted job. Use this id in order 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 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.
Note
Date filters will be 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
As a best practice, if a data filter is used, 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).
v3 API Filter Option For Download¶
A new filter option includeAdSiteSettings
is available in v3 Yahoo Native API. When set to true
, this indicated whether ad site settings will be downloaded. Default value is false
.
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,
"includeAdSiteSettings":true
}
}
Bulk upload¶
Endpoint
https://api.gemini.yahoo.com/v3/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 an advertiser id 123:
https://api.gemini.yahoo.com/v3/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.
Note
There is a new, optional query parameter skipExcelSpecificCharFixes
for bulk upload, in addition to the advertiserId
query parameter, that can be passed. The skipExcelSpecificCharFixes
parameter indicates whether the uploaded 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. It will default to FALSE if not specified.
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 |
---|---|
|
The ID of the submitted job. Use this id in order 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 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:
https://api.gemini.yahoo.com/v3/rest/bulk/status/?jobId=4196&advertiserId=30944
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-06-13 16:57:41",
"response": {
"jobId": 26597,
"status": "completed",
"jobResponse": {
"Invalid_Row": {
"totalCount": 0
},
"Ad": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Age_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Site_Exclusion": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Sitelink_Extension": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Call_Extension": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Location_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Device_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Ad_Schedule": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"OS_Version_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Radius_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Product_Group": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Keyword": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Shared_Sitelink": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Custom_Audience": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Shared_Negative_Keyword": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Campaign_Shared_Set": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Campaign": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Gender_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Shared_Set": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Ad_Group": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Product_Filter": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Interest_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Shared_Sitelink_Setting": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"Connection_Target": {
"totalCount": 0,
"addedCount": 0,
"updatedCount": 0,
"deletedCount": 0,
"failedCount": 0
},
"resultFile": "Q_Fy4sBGlxvzkrj.O_6nfabIu2lwu1AapjNQXhyVZX3wkag3Qdl_xo0ubHHRGG8plok_7rzZCSjVO5jjH647ozkKWbWwXOhDunEedtAMIb_24MpQChnQkOge1PaCLA5.6Ho-~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.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.
Here is an example:
https://api.gemini.yahoo.com/v3/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.
Caveats¶
Budgets that are set to less than the minimum value (for example, $3 rather $5) will automatically default to the minimum bid value, i.e., $5. No error will be reported to the user. This is standard Native API behavior. Note that when working with the Native UI, you will be able to identify such an error and take the necessary steps to fix it. When working with the BULK API, this may be more difficult to identify and thus fix, so the standard behavior is to default to the minimum bid value.
Cancel a Job That’s Processing Via API¶
To cancel a job that is processing via the Yahoo Native API, make a PUT call in Bulk via the API while it is processing by adding cancel
in the body of your request, like this:
PUT https://api.gemini.yahoo.com/v3/rest/bulk/cancel/?jobId=47991235&advertiserId=1518070
The response will be:
{
"errors": null,
"timestamp": "2018-06-15 18:47:59",
"response":
{
"jobId": 47991235,
"status": "killed"
}
}
Important
Ensure that you specify the advertiserId
, which is required.
Create Search Retargeting Campaigns¶
To create Search Retargeting (SRT) campaigns via bulk, you need to set the following values specified in the table below:
Channel |
Sub Channel |
Campaign Objective |
---|---|---|
Native |
SRN_ONLY |
VISIT_WEB |
Use the bulksheet to import your previous adgroup, keyword and ad assets into the new campaign as new items. Ensure that you add and remove the adgroup ids and object ids, update the campaign id and create a new adgroup as needed.
Important
If you are bulk-loading a previous keyword Search on Native (SoN) campaign, note that there is no SoN modifier in the Native Keyword Retargeting campaign. You should multiply the modifier to your keyword bids and load them into the account before going live.
Some Caveats:
When working with Keyword Retargeting (KRT), note the following:
A native keyword retargeting campaign cannot be converted into a standard native campaign.
A standard native campaign, however, can be converted into a native keyword retargeting campaign, but age, gender and audience targeting are not supported.
Cloning a search campaign and converting it to KRT is not supported at this time. Bulksheet support is, however, provided.
Account sync for Google Ads is not supported currently, but will be in a future release.
Available currently only for Visit my website campaign objectives.
[New] Search on Native (SON) Demand Through Native API¶
For bulk downloads, the following new channels have been introduced:
CHANNEL = SEARCH
SUBCHANNEL = SRN_ONLY, SRN_AND_SEARCH
The current Search and SON demand:
CHANNEL = SEARCH
SUB_CHANNEL = NULL (CATEGORY 1) or SRN_ONLY OR SRN_AND_SEARCH(CATEGORY 2,3,4)
The current Search and Native demand:
CHANNEL = NATIVE
SUB_CHANNEL = NULL