Release Notes - Archived¶

June, 2016¶

Introducing the New Gemini v2 API:

• New Gemini v2 API has been released. Starting on 1 June 2016, Yahoo Gemini will migrate the programmatic Gemini API from v1 to v2; the current version of the Gemini API will be v2. Be sure to read the sections on Versioning and API v1 Deprecation, plus the FAQs for details.

• Developers are encouraged to migrate to the new v2 Gemini API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version. In the event of a special situation that would require a fundamental change across all versions, a migration path will be provided. For any migration, you will have at least a 90-day window to migrate and integrate your app.

• Important: 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.

• With the v2 release, new v2 Shared Set Libraries have been added that enable you to create, populate and associate shared sets to your campaigns and ad groups. New v2 Shared Site Link has been added with methods for creating, updating and retrieving shared sitelinks.

May, 2016¶

• New call_extension_stats cube added to Custom Reporting. Use this cube to get detailed information about conversions on click 2 call ad extensions at the account, campaign and adgroup levels. For more information, see call_extension_stats.

• Note the following: Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in a state transition to ON_HOLD for the purposes of editorial review. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Please plan your edits and sync logic, accordingly.

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

April, 2016¶

• New Gemini Advertiser Guide portal introduced, replacing the existing Gemini Help Center with all new content for advertisers, including new videos, how-to information, campaign creation, billing, targeting, reporting, resources and other technical content. If you’re working with Bulk file fields and object types, refer to the section on Get Started with Gemini Bulk for detailed information on downloading and uploading bulk files, as well as navigating Bulk object types. The Gemini UI now points to the Advertiser Guide for Help & Guidelines.

March, 2016¶

• New dynamic URL parameter, {targetid}, 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.

• Support 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.

• 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 targeting fields added for Search Custom Audiences. CUSTOM_AUDIENCE and SEGMENT targeting are available in search. For Bid Modifiers, CUSTOM_AUDIENCE is a valid targeting type with range 0.1 - 10.00. Also, SEGMENT is a valid targeting type with range 0.1 - 10.00. For more information, refer to Targeting.

• Updated information on the number of objects: The total number of campaigns per account for advertisers is 10,000. Once you reach that limit and go beyond it, an error message is returned. There are no restrictions on the number of campaigns you can create daily.

• In Custom Reporting, the Audience cube has been deprecated, as previously announced. Use the user_stats cube. 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.

February, 2016¶

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

• A new appLocale field has been added for Bulk. This is an optional field for INSTALL_APP campaigns. It can be used to specify the desired locale of the app store, and will default to “en-us” if not specified.

• For more information, see Campaigns.

• A Device field has been added to the product_ads cube.

• Note: The first full date that this field is available is February 4, 2016. Dates prior will be blank.

• For more information, see the product_ads section of Custom Reporting > Cubes.

• “Bidding Strategy” and “ECPA Goal” columns have launched in the Gemini bulksheet. These fields are optional and map to biddingStrategy and ecpaGoal in the API. They are set on an ad group level only.

• The minimum value for eCPA Goal varies by campaign objective. It is $1.00 when the campaign objective is app install and $0.20 when the campaign objective is visit my web. The maximum for both campaign objectives is $1,000.00. For more details, see Ad Group.

January, 2016¶

• New fields added to the performance stats and search stats cubes in Custom Reporting. The fields provide you with the total post-click conversions and total post-view conversions that occurred in your app after it was installed. For search stats, the new fields specify the share of Impressions, Clicks and Conversions served by an Advertiser or Campaign. For example, if Campaign X has served 10 impressions to the keyword ‘basketball,’ and a total of 100 bidded searches occurred on ‘basketball’ during the time period selected, then Campaign X has an Impression Share of 10% for the term ‘basketball’.

• Note that for these three new SOV metrics (Impression Share, Click Share and Conversion Share), the data is only able to be pulled in 30-day increments. You can pull data from 12/13/2015 onwards for the SOV reporting attributes. If you pull anything before this date range, you will not get impression, click or conversion share information and the report may fail. The report attributes currently showcase impression, click and conversion data. Note that SOV metrics are currently calculated at the query/search term level.

December, 2015¶

• New lookalike audiences added to Custom Audience. Lookalike audiences let you find more people similar to your existing customers. For more information, refer to Lookalike audiences.

• New user_stats cube added to Custom Reporting. The cube provides a breakdown across various targeting attributes, like age, gender, device, geo (country, state, DMA, city, zip), both for physical user location and the location of user interest.

• New matrix provided that details the required fields when serving different ad types. For more information, see Ad.

November, 2015¶

• New ad previewing capability added to Ad object that lets you fetch a preview of either an existing ad or a new ad. The preview output is either a raw HTML source file or an iFrame with previews of the ad in different placements. For more information, see Ad.

• New Device field added to keyword_stats cube. The cube provides standard performance metrics at all entity levels of the account down to the keyword level. The Device field provides support for Smartphone, Tablet or Desktop. For more information, see Custom Reporting.

• New lookup of WOEIDs by location name added to Data Dictionary. The WOEIDs returned by the dictionary service cover the locations Yahoo Gemini officially supports. You can still target WOEIDs that are not in the dictionary as long as they are in the country, state, DMA, or city level. 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.

• New VISIT_OFFER objective field added to campaigns. You can use this objective for product ad campaigns. Note that the objective supports the CPC pricing type and SEARCH campaigns only. For more information, see Campaigns.

October, 2015¶

• At the request of many API partners, the Gemini API exposes lastUpdateDate and createdDate as read-only fields in API responses for all Gemini objects. These fields provide UNIX timestamps for when an object was created and last updated.

• New Audiences from your mobile app added for Gemini partners and developers in Custom Audience. This new custom audience type lets you target people who have taken specific actions in your mobile app, like achieving a level in a game or placing an item in a shopping cart. See Custom Audience for details.

• New CONNECTION and CUSTOM_AUDIENCE targeting types added in Targeting Attribute. The CONNECTION type allows targeting of WIFI or any connection types and applies only to video ads with a CPV price type. Note that video ads run on all connection types by default.

• New Broad match modifier (BMM) support provided in the Gemini User Interface, described in How to Use Match Types for Keywords. You enable a Broad Match Modifier by utilizing a plus symbol (+) in front of one or more words of a broad match-enabled keyword. This plus symbol indicates which word(s) must be part of the user query in order for an ad to be considered to serve for a query.

• New Hour field added as a dimension to the performance_stats cube in Custom Reporting. The Hour dimension returns as an integer in the Advertiser timezone: for example, 2 = 2am, 18 = 6pm. Note that hourly data is available for up to 15 day ago. If you run a report that contains dates older than 15 days ago, your report will not return data for those dates. See Custom Reporting for details.

September, 2015¶

• New /count method now exposed for all endpoints. Use this method to get the total number of objects in the data set you are downloading. For more information, see Pagination.

• New advancedGeoPos and advancedGeoNeg fields added to campaigns and ad groups. Both fields provide support for advanced geo targeting. Use these fields for SEARCH campaigns only. For more information, see Campaigns and Ad Groups.

• New Custom Audience added, enabling you to better target your ads by creating audiences from your website or your customer lists. For more information, see Audiences from a website and Audiences from a customer list.

August, 2015¶

• New Frequency Capping for Campaigns added. Use this to define the number of times users can be exposed to your campaign in a given time period by making a POST call. For more information, see Campaigns.

• New conversion_rules_stats cube added. This cube provides a breakdown of stats by conversion rules, conversion categories, and other conversion-related information. See Custom Reporting for details. Refer to Conversion Rules section for more details on creating and managing conversion rules.

• Important update: The https://api.admanager.yahoo.com/v1/rest/reports endpoint will continue to exist to support COB and POLL calls. Any report requests submitted after 9/30/2015 will fail. You should plan on moving to Custom Reporting because custom reports provide more flexibility to get the data you need.

• Compressed files are now supported on both bulk downloads and uploads. For more information, refer to Bulk Operations.

July, 2015¶

• New Yahoo’s universal tracking tag - Dot - introduced for Gemini partners/developers. Use Dot tags to communicate website and app events when you want to track performance and optimize your Yahoo search, native and display campaigns. Also to leverage retargeting and advanced audience targeting for various Yahoo channels. For more information, see the sections on Installing Dot Tags and Managing Dot Tags. Using a single pixel, you can manage multiple objectives, like creating new audiences for retargeting and tracking website conversions, mobile app installs and in-app user behavior.

• New Conversion Rules introduced, enabling you to track user actions, so you can measure and optimize your performance. You use fields and endpoints described in Conversion Rules, making standard POST, PUT and GET calls to accomplish this task. Also, Managing Rules introduced with supported operators and data types that can be filtered.

• New adName field added to the Ad object. An optional string field, this allows you to name ads for your internal purposes. The value is not part of the actual creative that is rendered. Character limit is 255. For more information, see Ad object.

• New search_stats cube added to Custom Reporting. The cube contains keyword-level performance data, enabling you to query for search queries that trigger keywords and ads, as well as for keyword-level performance by device. Custom reports let you query cubes, which are pre-defined collections of fields that define the context of your report.

June, 2015¶

• New Call to Action Buttons introduced, enabling you to add call to action buttons to your native ads, which encourages users to take specific actions after seeing your ad. See the Call to Action Buttons section for more details. The callToActionText field added to the Ad object.

May, 2015¶

• New Product Ads API introduced, enabling you to promote your offers in Gemini search campaigns. You create a product ads campaign by making a POST call to the /campaign endpoint and setting the campaign objective to be VISIT_OFFER. See the Product Ads documentation for more details.

April, 2015¶

• New API support provided for native video ads and video app install ads to help advertisers with both brand awareness and performance-based objectives. Gemini offers two distinct video offerings: native video (under the PROMOTE_BRAND objective) and video app install ads (under the INSTALL_APP objective). See the ad object documentation for more details.

March, 2015¶

• New API support added for post click and post impression conversions in Custom Reporting. Post impression conversions are the conversion events made by online users who have previously seen the ads within a certain time range.

• New API support added for setting ad schedules for search campaigns in Targeting Attribute. The API allows you to set a schedule for your ads to serve on specific days and times of the week. You can also set multiple schedules for a given campaign or ad group.

• New section added on how to create a sandbox account for testing purposes. To accomplish this, you make a POST call to the sandbox signup endpoint and pass in the name you wish to call your test advertiser. The response will be a test advertiser object only available in the sandbox environment.

POST  http://sandbox-api.admanager.yahoo.com/v1/rest/advertisersignup

February, 2015¶

• New API added for Resellers who manage accounts. Resellers are now provided with additional functionality for managing their accounts, but only within the advertiser object. Customer/Partner Impact: As a reseller, you may still use all other RESTful objects in the Gemini API when making campaign management and reporting calls on behalf of your managed advertisers. This additional functionality enables you to make GET, POST and PUT calls to the advertiser endpoint in order to create, manage and retrieve advertiser data for your child accounts. If you require reseller functionality, please speak to your Yahoo representative about whitelisting for this feature.”

• New support provided for creating an app install campaign in the Campaign Object. You create an app install campaign by setting the objective field in the Campaign object to INSTALL_APP and providing a link to your app in the defaultLandingUrl field. Customer/Partner Impact: If your goal is to generate app downloads, you can take advantage of this new capability in the Gemini API. You simply set the objective field to INSTALL_APP. Note that the objective field supports CPC pricing type and NATIVE campaigns only.

• New bid modifier feature added to the Targeting Attribute Object. Bid modifiers enable you to increase or decrease your search campaign bids based on certain targeting types. You accomplish this by leveraging the optional bidModifier field in the TargetingAttribute object.

January, 2015¶

• New defaultLandingURL field added to Campaigns with illustrating calls and examples.

December, 2014¶

• New Data Dictionary service introduced to the Gemini API. Customer/Partner Impact: The service lets you get a list of supported values for different Gemini object attributes. To retrieve that list, you simply make a GET call to the dictionary endpoint.

• New field added to Campaign Object:- isPartnerNetwork, which applies only to mobile search campaigns. Determines whether your campaign will run on the Yahoo partner network. This field accepts TRUE or FALSE and defaults to TRUE. The isPartnerNetwork field must be set to TRUE. The enum is optional.

• New targeting type added to Targeting Attribute: URL Customer/Partner Impact: This targeting type allows you to block your mobile search campaign from serving on specific domains. Valid values are URL strings, for example: https://www.blockdomain.com. When setting URL targeting objects exclude should be set to TRUE. If no URL targeting is set, no domains will be blocked and your mobile search campaign will be eligible for all of Gemini mobile search supply.

November, 2014¶

• Added to Dynamic Parameters: {matchtype}: The delivered match type of the bidded term that triggers the ad. “e” - exact match, “p” - phrase match, and “b” - broad match. {bidmatchtype}: The match type of the bidded term that triggers the ad. “e” - exact match, “p”- phrase match, and “b” - broad match.

• Added RADIUS type and field descriptions to Targeting Attribute in Objects. This targeting type accepts values in the following format: “latitude, longitude, radius”.

• Added a Conversions field to the Custom Reporting section on keyword_stats cube.

• Added to the Tracking macros section of Dynamic Parameters, that both {network} and {device} dynamic URL parameters are supported.

• Added: Set the value for param2 using the insertionText field for paramIndex=2 in the adParamValues attribute of a given keyword. Set the value for param3 using the insertionText field for paramIndex=3 in the adParamValues attribute of a given keyword.

• In the AdParamValueObject section, the following parameters are supported: paramIndex: The index for params (1, 2, and 3), which identifies which placeholder must use which replacement text. Valid values are 1, 2, and 3. insertionText: The substitution text to display on the ad. The character limit for the insertionText of paramIndex=1 is 1022. The character limit for the insertionText of paramIndex=2 and paramIndex=3 is 70 each.”,”Values for {device} are specified: “p” - Phone, “t” - Tablet, “c” - Desktop or laptop computer. Values for {network} are specified: “n” - Native, “s” - Search.

• New additions and revisions to the Ad Extensions section: Call Extensions, often referred to as Click-to-Call, display an advertiser provided phone number in the format of a Call button for text ads on smartphones. Call extensions are available for search campaigns and can be set at the campaign level. Only one call extension is allowed per campaign.

• New added example representations of Call Extensions.

September, 2014¶

• New Bulk Operations added with a new bulk schema. Gemini bulk files are tab-separated CSV, encoded as UTF16-LE with BOM. Customer/Partner Impact: The new Gemini bulk operations API lets you download and edit all the objects in your advertiser account using a spreadsheet in CSV format. You generate and download a bulk file using the bulk download service. You can also create and edit objects in bulk using the bulk upload service.

• New Custom Reporting service introduced to the Gemini API. Customer/Partner Impact: The workflow for custom reporting is similar to other Gemini reports. However, custom reports let you query cubes, which are pre-defined collections of fields. When you query cubes, you can choose the rollup aggregation level, apply various filters, and select which fields you would like the report to include.

January, 2015¶

• New section added to Objects, explaining how to clear values of any optional string field, using a PUT call to the keyword endpoint.

• Updated objective field description for Campaigns.

• Updated sample campaigns in Objects.

• Updated priceType field description in the bidSet object in Ad Group, describing that CPC is supported for the INSTALL_APP objective.

• Added a new section entitled Create a new ad group in the operations for Ad Group, similar to other objects described in this section.

• Updated description for imageUrlHQ field in Ad.

December, 2014¶

• Noted in the Ad Extensions section that adxtype is not supported for Call Extensions because the Click-to-Call link doesn’t load an advertiser’s landing page.

• Fixed in Custom Reporting: cube: ad_stats changed to cube: performance_stats.

• Minor typo fix to Custom Reporting: change Average position to Average Position. Must be capitalized, otherwise returns errors.

• Fixes to Keyword section: matchType is not required when adding a keyword and will default to BROAD if not provided. status is not required when creating any object type and will default to ACTIVE if not provided.

November, 2014¶

• Minor change to Custom Reporting: Campaign Goal renamed to Campaign Objective.

• Keyword Destination URL renamed to Keyword Landing URL.

• Minor fix with removal of PAUSED value in status field of Targeting Attribute.

• Updated in the Cubes section of Custom Reporting, the Conversions fact field description.

• Removed a note that says Conversions are available only at the campaign level.

• Moved the AdParamValueObject section from Dynamic Parameters to the Keyword section.

• In the Dynamic Parameters section, whenever {param1} is referred to, the explanation now states: You can set the value for param1 using the insertionText field for paramIndex=1 in the adParamValues attribute of a given keyword. A link is added to the AdParamValue Object section as part of the Keyword section.

• Minor re-ordering of the Documentation Table of Contents.

• Added new section describing the new service for Custom Reporting.

• Added new tables with fields and reporting job samples. Customer/Partner Impact: Customers and API partners can now begin to take advantage of these new reporting tools.

October, 2014¶

• Revised data model diagram added to Getting Started section.

• New section added in Getting Started on Related Topics, dealing with using your own analytics in Gemini ads and needed to understand briefly how Yahoo ad monitoring and URL crawling work. Section is duplicated for better coverage and to address partner queries in Dynamic Parameters.

• Added new Keyword Landing URL field to the keyword level fields in the Reporting section.

September, 2014¶

• Added Getting Started subsection on using OAuth Refresh Tokens.

• Terminology issues addressed: Documentation now uses DELETED and not Deleted. Also, issue of advertiser and account terms used interchangeably. Correct term is advertiser. Term account is removed.

• Phrase “competitive import only” stripped from docs.

• Renaming of objects in Table of Contents for consistency and ease of navigation. Customer/Partner Impact: the Keyword insertion topic is now covered in the new Dynamic Parameters section and is no longer needed. Better understanding of when and if refresh tokens expire. Terms clarified, eliminating confusion.