Product Bulletin

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.

March, 2016

New Audience Fields in user_stats Cube

  • New audience fields have been added to the user_stats cube: Audience ID, Audience Name, Audience Type, Audience Status.

  • These fields will help API partners gauge the delivery and performance against audiences they are targeting (custom audience, general interest, or custom segment).

  • For more information, see user_stats.

New Bulk Columns: Created Date and Last Updated Date

  • Two new read-only columns have been added in the bulk schema: “Created Date” and “Last Updated Date”. The format for both is YYYY-MM-DD HH:mm:ss. Example: 2014-08-29 00:11:55.

  • Note: These columns are always populated when using the Gemini APIs, regardless of the API request. They 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). For more information, see Bulk Operations.

[Breaking Change] Bulk No Longer Escapes Backward Slashes

  • A minor breaking change to Gemini Bulk took effect Monday, 3/21/16. With this change, Gemini Bulk no longer escapes backward slashes. As a result, the user will get exactly what they have in the original input in the result file. This change, limited to Bulk only, will be only applied to reading the CSV/TSV files via bulk upload/download services. The change will be applied to all cells of the bulk file. This change only applies to new bulk file parsing and new bulk result file writing (no existing data will change).

New {targetid} Dynamic URL Parameter

  • A new dynamic URL parameter, {targetid}, has been added to Dynamic Parameters.

  • For example, if you add a custom audience list (ID “456”) to your ad group and target the keywords ID “123”, the {targetid} would be replaced by “kwd-123:aud-456”.

  • See Dynamic Parameters for more information.

WOEID Lookup by Zip Code

  • Support has been provided for looking up WOEIDs by Zip code. You can look up the WOEID for a location that may not be in the dictionary by passing in the location name as a parameter, as well as an optional type parameter, which can be Zip.

  • For more information, refer to Data dictionary.

Reminder: audience_stats cube was deprecated 2/29/16; use user_stats cube

  • [Reminder] In Custom Reporting, the Audience cube has been deprecated, as previously announced. Use the user_stats. Note that you’ll need to remove the audience-type filter for Geo (country, city, state, DMA, zip). Use the new Geo fields in your report instead.

Latest Gemini API Release Notes

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.

  • Resource URI:{resource}

  • 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 Getting Started.

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.

Overview of Search Features Currently Available

  • Keywords

    • MATCHING: Exact, Phrase, Broad, BMM. Entry Point: Bulk, API.

    • NEGATIVES: Exact, Phrase. Entry Point: Bulk, API.

    • KEYWORD URLS & PARAMS: Used to create dynamic text or for tracking. More info. Entry Point: Bulk, API.

  • Ad Settings

    • CHARACTER LIMITS: Title: 50; Description: 150; Display URL: 35; Destination URL: 2048. Entry Point: UI, Bulk, API.

  • Targeting

    • GEO: State, City, DMA, Zip, Radius. Entry Point: UI: State, City, DMA | Bulk, API: Zip.

    • Bid Adjustments available via Bulk, API. Range is -90% - +900%.

    • Radius can be specified in increments of 1 mile. Range is 1-500 miles, specified by longitude and latitude.

    • Advanced Geo Targeting options available to support physical location or interest. Entry Point: Bulk, API. For more information, see Campaigns and Ad Groups.

    • TIME OF DAY: Ad scheduling in 15 minute increments. Entry Point: Bulk, API.

    • DEVICE: Bid modifiers are available for all 3 devices, with varying ranges. Desktop: 0% to +100%; Smartphone: -100, -90% to +300%; Tablet: -20% to +300%. Entry Point: Bulk, API.

  • Reporting

    • Performance Reports: Reporting is available at the following levels: Campaign; Ad Group; Ad; Keyword; Targeting (campaign level only); Ad Extensions; Product Ad. Entry Point: UI, API.

  • Ad Formats

    • SITELINK EXTENSIONS: Entry Point: Bulk, API.

    • CALL EXTENSIONS: Entry Point: Bulk, API.

    • PRODUCT ADS - Pilot: Currently available on smartphones and tablets. Testing soon on desktop. Entry Point: UI, Bulk, API

    • LONG AD TITLES: Will not exceed 55 characters on smartphones or 65 on tablets.