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.
Tune into the November Product Bulletin podcast for the latest on Gemini API features, changes and product enhancements released this month by the Gemini product development team.
New Conversion Rule Custom Audience Introduced¶
New slot_performance_stats Cube Released in API¶
New slot_performance_stats cube released in API. This cube is used for per-card Carousel Ads reporting. For more information, see Cubes.
With this new feature release, reporting data for up to 1000 advertiser IDs can be pulled using one reporting call itself. For more information, see Reporting.
Update to Upgraded URLs¶
A solution has been deployed to support all upgrade/downgrade scenarios for Upgraded URLs. For more details on Upgraded URLs, refer to Upgraded URLs - New in v3. Summary of expected behavior:
If you use Gemini API v3, and include a mix of UU and non-UU attributes, the system will throw an error.
If you use Gemini API v3 and update an entity with only UU or non-UU attributes (and the entity is in the opposite state), the system will upgrade or downgrade based on the pieces sent.
An attribute set to null or empty string
("")will be treated as if it was not included.
BULK Updates: Advanced Location and Tumblr Post URL¶
Advanced Location BULK campaign field available. You can now explicitly target either users physically located in your geo-targeted location or users searching for your geo-targeted location, or both (default). For more details see Bulk Campaign Fields.
Tumblr Post URL field available. If you have a Tumblr post you would like to associate with your ad, you can provide a valid post URL using this field. Doing this will make your ad eligible to run on Tumblr. Whitelisting for a Social_Engagment objective is not necessary. An optional field for native ads, separate from the landing URL, is provided, so an ad is eligible to run on Tumblr, but is not limited to Tumblr. For more details, see Bulk Ads Fields.
Gemini UI Updates¶
Please see the What’s New section of the Advertiser Guide for Gemini UI updates released this month. Recent updates include new Gemini Scheduled Reporting feature.
Reminder: Updated Postman to v3 Endpoint¶
Updated the Postman collection to the v3 endpoint for all Gemini API calls. Using Postman, you can test and verify the calls you make in the Gemini API. See Postman API Toolkit.
Reminder: Ad Site Setting in the Gemini v3 API and BULK UI¶
Ad Site Setting is a new RESTful object, available in the v3 Gemini API, that provides methods for creating, updating, and retrieving settings for site-specific ads, including pagination. A site-specific ad is a native ad that has been tagged by the advertiser to be shown to a user when that user visits a specific website. For example use cases, fields, and more details, see Ad Site Setting.
Also see new fields for creating and deleting ad site settings in BULK. For more details, see Ad Site Settings in BULK Field Objects documentation.
Also note a new v3 API filter option
includeAdSiteSettingsfor BULK download. When set to
true, this indicates whether ad site settings will be downloaded. Default value is
false. For more details, see Bulk Operations.
Reminder: New Guide: How To Utilize Dot Pixel & Conversion Rules¶
New step-by-step guide on how to effectively utilize dot pixel and conversion rules, based on your particular needs and setup, i.e., whether your advertiser account contains either a single website or multiple websites. The API workflow described in this document involves, essentially, no more than five basic steps to set up your Dot Pixel tags and Conversion Rules.
Reminder: Bulk Downloads Performance¶
If you have a large account and notice your bulk downloads are taking longer over time, please consider deleting dormant or orphaned objects (Campaigns, Keywords, Ads, Ad Groups). See the Gemini Guide for more details on Bulk operations.
Reminder: Migration to Gemini v2 API or v3 API - Action May Be Required¶
Please be aware that starting on September 1, 2017, the Gemini v1 API was relegated to End of Life (EOL) status; the Gemini v3 API was released on July 25, 2017. The Gemini v2 API is still supported post-release. Official deprecation for the v2 API has not yet occurred. Partners and developers will be notified once this has been officially determined, and a schedule provided. Please note that new features will not be added to v1, and v1 will not be supported. For details on the v3 release schedule, as well as dates for the v1 deprecation, see the Release Schedule and Gemini API Versioning.
Action may be required: Gemini API users may choose to migrate to either v2 API or v3 API.
To migrate to v2 API:
Please visit the v1 deprecation note.
Note: Action may be required to migrate from the Deprecated v1 Reporting Endpoint.
To migrate to v3 API:
Users are encouraged to migrate to the new Gemini v3 API directly. v3 is backward compatible with v2, and users may continue using the current landing/display URL structure on v3 without Upgraded URLs migration for the time being. The new Gemini v3 API has been released as of July 25, 2017. This release provides partners and developers with multiple new features and capabilities. For details, see Versioning.
Reminder: v1 API Deprecation¶
Reminder: The Gemini v1 API was deprecated on June 1, 2016. Starting on September 1, 2017, the Gemini v1 API was relegated to End of Life (EOL) status. In addition, new features will not be added to v1.
Reminder: Deprecated v1 Reporting Endpoint¶
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 THIS year Sept 1, 2017.
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.
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.
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.
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.