To stay current with changes, updates and new features in the Native & Search API, you’ll want to read this section. The What’s New is updated on a weekly cadence for Native & Search API partners and developers.
Each month the Native & Search API Product Bulletin summarizes the latest updates and changes based on input from the Oath team. Be sure to read the Bulletins to retrieve information that may impact your product development.
Introducing the Native & Search API¶
Gemini has now been rebranded as Oath: Ad Platforms Native & Search. The new product brand represents Oath’s full suite of technology solutions for advertisers, agencies and publishers. The new brand replaces BrightRoll, Gemini, ONE by AOL, and Yahoo for Publishers.
Oath: Ad Platforms is connected to the consolidation work completed by the Oath product and engineering teams in September 2018.
Now a global brand, Oath Ad: Platforms will be a visible part of the Oath family of brands in all Oath markets.
All previous references in this documentation suite to the Gemini API will now be designated as Oath Ad: Platforms Native & Search API, or simply Native & Search API.
All endpoints (Resource URIs) will stay the same as in the v2 and v3 Gemini API, and not change. For example, this stays as is, even with the rebranding:
Tune into the October Product Bulletin podcast.
Native & Search API Release Notes are now archived in Resources and available if you wish to review past changes.
Native & Search v3 API¶
The v3 API was released on 25 July 2017. This release provides partners and developers with the following features and capabilities:
Support for Upgraded URLs (UUs), which enable you to better define and control the landing page and tracking of your URLs. For more information on Upgraded URLs (UUs) in v3, refer to Upgraded URLs.
Greater API object stability, as well as improved management of API changes, building on the enhancements in v2 API.
Support for Site X Device Targeting with new available targeting attributes. For more information, refer to Targeting Attributes. Note that Site X Device targeting is also supported in the v2 Native & Search API.
New reporting cubes available for querying at the ad group level:
site_performance_statsfor use when querying for native ads campaign data.
campaign_bid_performance_statsfor use when evaluating group-level bid modifiers.
For more information, refer to Cubes.
- New reporting dimensions available for querying at the advertiser, ad, campaign, ad group and keyword levels. For more information, refer to Dimensions.
- Postman examples added for Upgraded URLs (v3) and Bid by Site (v2). For more information, refer to Postman API Toolkit.
- Additional bug and error fixes for improved performance and stability.
Developers are encouraged to migrate to the v3 Native & Search API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version.
Native & Search v2 API¶
The v2 API includes the following changes:
- Native & Search v2 API has been released. Starting on 1 June 2016, Oath will migrate the programmatic Native & Search API from v1 to v2; the current version of the Native & Search 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 v2 Oath 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.
The Native & Search v1 API will be supported for 90 days beyond the June 1, 2016 deprecation date. After that date, starting on September 1, 2016, the Native & Search 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.
In the v2 API, only one
parentId parameter is allowed to be passed in as a query parameter for all filtered list GET calls. This change will have impact when you filter lists of GET calls on ad, ad group, campaign, ad extensions, keyword, targeting, shared sitelinks, and created, populated and associated shared set calls. Refer to each of the relevant sections in the documentation for details.
v2 Data Model¶
The v2 Native & Search API introduces a new data model with new entities, as shown in the diagram below. The v2 data model illustrates how shared sets and the new shared site link objects work and connect.
Other New Features, Changes & Enhancements¶
call_extension_statscube has been added to 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 Native & Search 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 Keyword
editorialStatusfields added in v2. Also, new Ad
editorialStatusfields added in v2.
- New Bulk schema upload and download changes in v2, providing partners and developers with a unified format for bulk operations and data representation. To consolidate all targeting attributes in bulk files to a single, unified standard, as well as expose targeting attribute entity IDs for all objects, the v2 API includes the changes described in Bulk schema upload and download.
- New, re-architected Native & Search API Table of Contents for easier navigation and retrieval of documentation topics and information. With the introduction of v2, we’ve organized and consolidated much of the technical content, so that each topic folder contains the specific information you need when coding and integrating your apps. If you’ve bookmarked topics in the v1 API, you may find some of those links broken; you’ll need to bookmark new links that are relevant to your development efforts.
Release Notes - Archived¶
The Release Notes section is now an Archive of notes in Resources, dating back to the initial release of the v1 Native & Search API. Explore these if you need to track changes, updates and enhancements to the API over time.
You may wish to check out these additional, external resources dedicated to working with Oath and the Native & Search API: