Bulk Upload API¶
Abstract¶
Upload bulk files by making standard POST and GET calls in the API.
Upload Endpoint¶
https://api.gemini.yahoo.com/v3/rest/bulk/upload
Submit a Job¶
To upload a bulk file, make a POST call to the bulk upload endpoint, passing in the advertiser id in the URL.
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’re 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.
Query Parameters Fields¶
Name |
Description |
Required |
---|---|---|
|
The account the upload is for. |
Yes |
|
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. Defaults to FALSE if not specified. |
optional |
|
Defaults to FALSE. Recommended to set to TRUE. This generates a compressed (gzip) of the CSV file result for a smaller, over-network footprint. |
optional |
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¶
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
The meaning of the possible statuses are detailed below:
Name |
Description |
---|---|
submitted |
The job is in the 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. |
Upload Completion¶
Upon successful completion, the response includes the token you’ll 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.
Upload Details¶
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.
Example Response¶
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"
}
}
}
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.