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.
- December, 2016
- Introducing Yahoo Mail Ads, a New Native Ad Experience
- Reminder: Search on Native Overview and Resources
- Gemini API Video Tutorials
- Reminder: New Cube Name For Close of Books Added
- Reminder: Gemini v2 API Resources and v1 Deprecation Timeline
- Reminder: Deprecated Reporting Endpoint
- Getting Started Guide: OAuth 2.0 Authentication Steps
- New Glossary of Gemini Terms
- Check Out What’s New
- Using the Gemini Sandbox Environment
- Required Fields by Ad Type Matrix
Introducing Yahoo Mail Ads, a New Native Ad Experience¶
- Introducing Yahoo Mail Ads, a new Native ad experience in a context that delivers maximum engagement. Mail Ads are positioned at the top of each user’s inbox. They can open like an email, and may be read, saved, clicked or forwarded, with reporting available on each type of interaction. In addition, we have introduced a new Custom Thumbnail asset (180x180px), used in the pencil ad unit on mobile and desktop.
- For API, see Ad object for details and specs of the new
- For Bulk Field Objects, see Ads for details and specs of the new
Mail Asset URLand
Ad Thumbnail Image Urlfields.
- For Mail Ads reporting, see performance_stats for details on new metrics, including Opens, Saves, Forwards and more.
- For more details about how it works and a brief demo video, see our recent blog post, Creating a better ad experience in Yahoo Mail.
Reminder: Search on Native Overview and Resources¶
- Gemini Search on Native is a new feature extension that provides you with additional supply for your search campaigns in the US. Search on Native allows select advertisers who are buying search on Gemini to extend their search campaigns into native. This new capability enables advertisers to target users who previously searched for their keywords.
- Ad creatives, with the addition of an optional image, will then be served on Gemini native inventory (O&O and Syndication), which includes Yahoo’s homepage, news, finance and Yahoo publisher partners, once signals of intent from a user’s recent search history are detected. This means that you can expand your reach across Yahoo’s massive native inventory in a cost-effective way with the application of bid modifiers.
- For more information on the new campaign-level attributes - subChannel and subChannelModifier - see Campaigns and Bulk Field Objects Campaigns. Also see the Technical Note for some of the technical considerations when working with Search Retargeting on Native.
- Also see the overview in the Gemini Advertiser Guide and What’s New. For additional reference, please see the following blog post with details on how it works: Search retargeting comes to Yahoo Gemini on native supply.
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: New Cube Name For Close of Books Added¶
cubeNamefield added to Close of Books, enabling you to query the name of the cube for COB. The field is optional; you can only pass in one cube name at a time. To query whether books are closed for a given date, you make a GET call to
and pass in these parameters:
- For more information, refer to About Books Closed.
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 will be 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.
New 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 new video tutorial describing How to set up your Sandbox Environment in the Programmatic Gemini API - Episode 3.
Required Fields by Ad Type Matrix¶
- We’ve added a new matrix which details the required fields when serving different ad types. For more information, see Ad documentation > Matrix view of required fields.