Welcome to the Yahoo Gemini API Product Bulletin. This update includes a quick snapshot of recent and upcoming releases and is focused on features supported by the API. A summary of supported functionality is also included.
Product Bulletins are updated on a monthly cadence for Gemini API partners, account managers and developers.
- June, 2017
- New Dynamic Product Ads (DPA) performance_stats Cube
- Minor Bulk Sheet Download/Upload Result File Changes
- New Postman API Toolkit
- Gemini Native Ads Specs and Resources
- Changes to Daily Budget Credits Starting 6/26/17
- Gemini API Video Tutorials
- Reminder: Gemini v2 API Resources and v1 Deprecation Timeline
- Reminder: Deprecated Reporting Endpoint
- Getting Started Guide: OAuth 2.0 Authentication Steps
- Glossary of Gemini Terms
- Check Out What’s New
- Using the Gemini Sandbox Environment
New Dynamic Product Ads (DPA) performance_stats Cube¶
- New product_ad_performance_stats cube provides product ad performance stats for all levels down to the ad level. Use this cube when querying for native ads campaign data. It is only available for native ads. The cube does not include keyword level metrics. Data for both search and native campaigns is provided - you can use the “Source” field to filter for a specific channel. For details, see product_ad_performance_stats. Note that the cube does not include any over delivery spend adjustments which are available in the adjustment_stats cube.
- Dynamic Product Ads (DPA) are feed-based ads that can be shown on a native Gemini platform. Use DPAs as retargeting ads from your product feed that scale to promote your products to users who have visited your product websites. See Dynamic Product Ads for additional DPA resources, including integration steps, product feed operations, creation of product sets and Dot Tag Instrumentation. For additional guidance, see the FAQs.
Minor Bulk Sheet Download/Upload Result File Changes¶
- Minor changes have been made to all bulk download/upload result files, where many unnecessary columns will be hidden for both V1 and V2 API users. These changes were live in the Sandbox environment starting 6/14/17 and were live in Production on 6/21/17. For example:
- Unnecessary columns will be hidden in both V1 and V2 APIs (e.g. “Site”, “Video Preview Start Time”). These columns contained blanks before the change.
- All V2-only columns will be hidden for V1 users (e.g. “Segment ID”, “Location ID”, “Editorial Status”, “Supply Group”, “Ad ID”, “Index”, etc.). These columns contained blanks as well before the change.
- “Editorial Status”, “Location ID”, “Segment ID”, “Index”, and Shared Library headers (“Shared Set Type”, “Shared Set ID”, “Shared Object ID”, etc.) will only be written for V2+ jobs as today they are only accepted and filled in for V2+ jobs.
- Upcoming Upgraded URL headers (“Final URL”, “Mobile Final URL”, “Tracking URL”, “Custom Parameters”) will only be written for future API versions.
- DPA headers (“Product Set ID”, “Product Set Name”, etc.) will only be written for V2+ jobs.
- Note: Account ID / Account Name columns are not going away for multi-account downloads and uploads. Action column is also not going away for download/upload results. “Error” column will continue to only be written for upload job results. See Bulk Operations for detailed information about the Gemini bulk operations API.
New Postman API Toolkit¶
- New Postman API Toolkit now available. For purposes of testing and verifying the calls you make in the Gemini API, you may wish to set up the Postman HTTP client, which lets you make requests (GET, PUT, POST, and DELETE calls) to the Gemini RESTful APIs.
- Postman lets you access the Gemini API through a collection (once you get/install Postman, and modify some global variables).
Gemini Native Ads Specs and Resources¶
- Native ads combine various brand assets to produce rich, compelling ad experiences and display them alongside content, providing interaction and engagement superior to traditional display advertising. See Gemini Native Ads for details on native ads, including key benefits, where native ads appear, and detailed information about various Yahoo Gemini native ad types.
Changes to Daily Budget Credits Starting 6/26/17¶
- Starting June 26, 2017, Gemini will introduce a new model for handling ad spend when it exceeds a campaign’s maximum daily budget. The new model is designed to pace campaigns more efficiently and help advertisers capture the most traffic possible, especially on days when traffic is higher.
Previously, the daily campaign budget option did not take into account fluctuations in traffic to help advertisers optimize campaign performance. As a result, advertisers might have missed out on additional clicks during higher traffic days.
What our updated approach to the campaign daily budget option means for you:
- Since traffic can fluctuate, up to 120% of your daily campaign budget may be used to show your ads on certain days of the week where traffic is higher. On days where traffic is less, you may see less than your daily campaign budget spent.
- Daily spend should balance out over the course of the month.
- If your daily spend exceeds 120% of your daily campaign budget, you will only be charged for the 20% over your daily campaign budget.
- We will still provide overdelivery credits for any spend over your cumulative monthly budget at the end of each month.
- This change is consistent with industry standards.
For example, if an advertiser sets a daily campaign budget of $10, up to $12 can be used on certain days based on fluctuations in traffic, with daily spend balancing out over the course of a month (e.g., monthly spend for a 30-day month should not exceed $300).
Gemini API Video Tutorials¶
- In this series of introductory videos, the Gemini Development Team will walk you through some of the basic steps you’ll need to follow before you first begin making API calls and leveraging the Gemini platform for programmatic ad buying.
- Get Started with Programmatic Gemini API - Episode 1
- Working with RESTful Objects in Programmatic Gemini API - Episode 2
- How to set up your Sandbox Environment in the Programmatic Gemini API - Episode 3
Reminder: Gemini v2 API Resources and v1 Deprecation Timeline¶
- New Gemini v2 API has been released. Starting on June 1, 2016, Yahoo Gemini migrated the programmatic Gemini API from v1 to v2; the current version of the Gemini API is v2. Be sure to read the sections on Versioning and API v1 Deprecation, plus the FAQs for details.
The Gemini v1 API was supported for 90 days beyond the June 1, 2016 deprecation date. After that date, starting on September 1, 2016, the Gemini v1 API will be available for one year. After that time, it will be relegated to End of Life (EOL) status.
- See the What’s New section for more information about the new Gemini v2 API.
Reminder: Deprecated Reporting Endpoint¶
- Update: Please be aware that action may be required for the following deprecated reporting endpoint.
Old: https://api.gemini.yahoo.com/v1/rest/reports New: https://api.gemini.yahoo.com/v2/rest/reports/custom
- If you currently make calls only to /v2/rest/reports/custom for both POST and GET, there is no action required.
- If you currently make POST calls to /v1/rest/reports then you need to migrate to the /v2/rest/reports/custom endpoint ASAP.
- If you currently make POST calls to /v1/rest/reports/custom and GET calls to /v1/rest/reports, then you need to migrate to v2 before v1 EOL NEXT year Sept 1, 2017.
- Please see documentation for the new reporting endpoint for more information.
- For additional reference, please see Gemini API documentation: Navigating the API and Reporting.
Getting Started Guide: OAuth 2.0 Authentication Steps¶
- New, detailed explanation of steps to follow before you begin OAuth 2.0 authentication. If you’re new to the Gemini API, you should read the section and follow the steps listed. Note also in the section on OAuth refresh tokens that access tokens will expire after 60 minutes.
Glossary of Gemini Terms¶
Check Out What’s New¶
Using the Gemini Sandbox Environment¶
- The Gemini API lets you work with a sandbox environment to test campaigns you’ve created and managed. You use the same consumer key and consumer secret you obtained when you set up your OAuth to access the sandbox.
- The Gemini sandbox serves as a modified version of the production environment. While all operations are designed to function the same in the sandbox as in the production environment, the campaigns and ads you create in this environment do not actually serve. The sandbox environment is completely separate from your production environment.
- All campaigns, ads, and keywords you create in the sandbox are available in the sandbox environment only. There is no possibility that the ads you create in the sandbox will be accidentally served. Nor will your production accounts be charged for any mock transactions in the sandbox environment.
- You will need to create a sandbox account in order to test in this environment. You can do this by making a POST call to the sandbox signup endpoint and passing in the name you wish to call your test advertiser. The response will be a test advertiser object that will only be available in the sandbox environment. For more details, see Testing - Sandbox.
- Be sure to check out the video tutorial describing How to set up your Sandbox Environment in the Programmatic Gemini API - Episode 3.