The Yahoo! Search Marketing API provides programmatic access to the same functionality exposed visually in the web-based interface. You can create and manage campaigns, pull reports, set bids and more. All of these capabilities are exposed via a collection of SOAP-based Web Services that are easy to use and thoroughly documented.
Yahoo! Search Marketing has a new version of the Enterprise Web Services (EWS) Marketing API. Which are:-
- Enterprise Web Services Version 7.0.0
- Enterprise Web Services Version 6.1.0
- Enterprise Web Services Version 6.0.0
What’s New After Version 7.0.0?
Keyword participation status API for mobile accounts
- A new API getKeywordParticipationStatusByAdGroupIdByCarrierIDs has been added for retrieving the detailed participation status of keywords in an ad group ID by carriers. Adopt the latest KeywordService WSDL to take advantage of the new feature. This is available only for mobile accounts.
Ad Delivery reports and Domain Blocking available in more markets
- Ad Delivery reports and Domain Blocking are now available in Austria (AT), Switzerland (CH), Netherlands (NL), Norway (NO), Denmark (DK), Sweden (SE) and Finland (FI) markets.
New Operations
KeywordService
- getKeywordParticipationStatusByAdGroupIdByCarrierIDs
New Data Objects
- KeywordCarrierParticipationStatus
- CarrierParticipationStatus
Getting Started
For developers like yourself, Yahoo! Search Marketing provides an extensive online resource for your development, prototyping, and testing needs. Make sure you have a solid understanding of the lingo, and feel comfortable with basic concepts, like what a Campaign, AdGroup, Ads, Keywords, etc… are. This will make your experience with the Yahoo! Search Marketing API much more fulfilling.
Important Entities
There are some important entities included in the system and its hierarchy is listed below.
—> Campaign
—> AdGroup
—> Creative/Ads
—> Keyword
- Campaign
Campaigns are used to give structure to the products or services you want to advertise. This is the top level of the hierarchy. According to Yahoo Search Engine there are 20 campaign’s we can have in an account.
- Ad-Group
An ad group is a grouping of individual advertisements. Separate ad groups within a campaign help distinguish ads in meaningful ways. And we can have maximum of 1,000 AdGroups per campaign. And this should be unique into a campaign. The immediate children of adgroup are Ad and Keyword.
- Ad
An ad is an individual advertisement that is presented to a user. An ad group consists of one or more ads. In yahoo we can have maximum of 20 Ads per adgroup. And this should be unique into an adgroup.
- Keyword
A keyword is a word that, either singly or grouped with other keywords as a keyword phrase, causes an ad to be displayed when it matches criteria entered by a customer. In Yahoo we can maximum of 1,000 keywords per adgroup or maximum of 50,000 keywords per account.
The Marketing API Reference includes sample code in four “first class” languages. These are the programming languages that we have, through community insight, determined to be the most widely used to integrate with our APIs. In no particular order, they are: Java, .NET, Perl and PHP.
Enterprise Web Services (EWS) and the Search Marketing API Program
Enterprise Web Services (EWS) is the platform for the Yahoo! Search Marketing API program. It helps you build applications that can interact with Yahoo!’s Sponsored Search marketplace using the Search Marketing APIs. Client software can be built to manage large accounts, and automate tasks for implementing and managing campaigns.
EWS can also be used to develop innovative solutions that can help you integrate your programs with Yahoo!’s Sponsored Search marketplace. Many third-party vendors offer value-added services to our clients. We provide you with appropriate technical and marketing support to help you get your business get started and grow. EWS and the Search Marketing APIs enable you, as a developer, to build client software that interacts directly with the Yahoo! Search marketplace through a web services interface.
Access and Authentication
Before you can access EWS, you need to sign up with Yahoo! Search Marketing and obtain an EWS license. Your EWS license includes a license key and defines your command groups and quotas. With the help of your Technical Account Management team you will need to set up a username and password, and create your initial accounts. The main parameters you required to create a successful authentication, we required the following parameters.
- Username
- Password
- License key
- masterAccountId
- AccountId
To access EWS, you need to write webservices client software in the programming language of your choice. With the client software you can make internet connections to our web service endpoints over a secure HTTP connection.
Quotas
Each EWS request includes either an operation, for example, getKeyword, or a list-based operation, for example, getKeywords that counts against your quota. For each operation, one quota point is deducted. For each list-based operation, one quota point is deducted for each object in the list.
Each EWS response includes elements in the SOAP header that show the command group to which the operation belongs and the remaining quota for that command group. You can use this information to track your quota consumption and to manage your EWS requests. When you exceed your quota for any command group, additional EWS requests are rejected with a Quota Exceeded SOAP fault. Your quota is reset at midnight in time zone of the master account.
Operations
Each service includes one or more operations. However, only one operation may be included in an EWS request. That is, each operation represents a single request to and response from EWS. Read operations include the “get” operations or any operation that retrieves but does not change the value of an object. Write operations include the “add”, “copy”, “delete”, “move”, “set”, and “update” operations or any operation that modifies the value of an object.
EWS requests:- an operation may or may not include parameters. If an operation does include parameters, you must specify a value for each parameter; that is, all parameters are required and must be included in the EWS request. For certain parameters, you may pass in the null value or the null string.
EWS responses:- an operation may or may not return data. If an operation does not return data, the response simply states “none.” Please note that response “none” does not mean that no response is returned; rather, it means that the response returns an empty response element that does not include data.
EWS Sandbox Environment
The EWS sandbox is a test environment that allows you to experiment with the Yahoo! Search marketplace by creating and running Enterprise Web Services (EWS) client applications. The EWS sandbox provides a modified version of the production system, and focuses on the Marketing API. While all services and operations are designed to function the same way as on production, the actual result sets observed on sandbox may vary.
Access :- To obtain a license key for the sandbox, contact your account manager. You will be issued a test master account, MasterAccountID, a test account, AccountID, and a new username and password for accessing these test accounts.
Quota : – Quota for the sandbox is set at 500 operations per day per license. All quota is assigned to the Marketing command group, which is the only command group available in the sandbox.
WOEID
WOEID, Where on Earth ID, is a unique identifier for any supported targetable geographical location. Each geographical location (GeoLocation object) is mapped to a WOEID which is unique to a given market. This is used by the operations in this service to return the type of geographical locations that you want to target. The mapping between GeoLocation object and WOEID is immutable and we recommended that you store the mapping and use WOEID directly.
How it works
EWS webservices use SOAP, an XML-based protocol, as it’s underlying messaging technology. Although you can generate XML requests and parse the XML responses directly in your client application, typically your client software uses a toolkit that supports SOAP and thus manages the details of the connection and response for you.
Before going to start with EWS, you should have basic knowledge about, what is SOAP (Simple Object Access Protocol)? And what is WSDL (web Service Definition Language)?. Because the interaction between the Yahoo Search Marketing API and your client software is happening through SOAP request and SOAP response.
We have seen different hierarchy or entities we can perform in Yahoo EWS.
Some of the basic Web Service Definition Language of Yahoo EWS are listed below:-
- CampaignService:
http://developer.searchmarketing.yahoo.com/docs/V7/wsdl/V7/CampaignService.wsdl
- AdGroupService :
http://developer.searchmarketing.yahoo.com/docs/V7/wsdl/V7/AdGroupService.wsdl
- AdService :
http://developer.searchmarketing.yahoo.com/docs/V7/wsdl/V7/AdService.wsdl
- KeywordService :
http://developer.searchmarketing.yahoo.com/docs/V7/wsdl/V7/KeywordService.wsdl
For each time if we want communicate with Yahoo Search Engine, first we have to establish a connection or header authentication. For a successful header authentication we should have username, password, licence key, masterAccountId and an accountId. And this is a mandatory factor to get the header authentication first. Once we have obtained a successful header authentication, then we can send our soap request, which we want to perform with Yahoo EWS.
Yahoo EWS providing a test environment to test our requests are correct or not. For this we have sandbox environment. Once we have tested and verified in sandbox we can put our Ads into production environment. Which will charge based on your usage. The Yahoo API usage measured as quota. For each operation its consumption will be one quota.
We can get the real time reports with the help of report services. Either by daily, weekly, monthly ,etc… based on our requirement. You can download the report by all supported format, example CSV, XML. And the report download url will valid only for 5 minutes. Once we cross the five minutes time we can’t download the report from the url provided by Yahoo. We have to do again a report request. Summary Reports: which includes performance data from your Yahoo! Search Marketing campaigns, either Sponsored Search or Content Match traffic, or both. Advanced Reports: which includes the performance data as well as conversion and advanced analytics data from your tagged web sites. Multi-Channel Reports: which includes the performance data, the conversion and advanced analytics data from your tagged web sites, and additional marketing activity you have uploaded using the web application. Multi-Channel reports are only available for accounts where tagging is enabled with Full Analytics at the master account level.
Running a Report
The general procedure to run a report is:
* Check if the books are closed (optional).
* Submit a request for a new report.
* Check the status of the report to determine if it executed completely.
* Obtain the URL for the completed report.
* Use the URL to download the report using the HTTP GET method.
* Depending on which operations you use, steps 3 and 4 may overlap.
Deleting Objects
Use the delete operations to delete a campaign, ad group, ad, or keyword, for example, deleteCampaign or deleteCampaigns. When you delete an object, they are affected as follows:
Campaigns – When you delete a campaign, the status of the campaign is changed to Deleted. The ad groups within that campaign and the ads and keywords within those ad groups will behave as if they are deleted; however, their status is not changed.
Ad Groups – When you delete an ad group, the status of the ad group is changed to Deleted. The ads and keywords within that ad group will behave as if they are deleted; however, their status is not changed.
Ads and Keywords – When you delete an ad or a keyword, the status of the ad or keyword is changed to Deleted. Deleting an ad or keyword does not affect the status of the other ads or keywords in the ad group.
To determine if an object is deleted, create logic to traverse your account hierarchy, beginning at the account level. If you encounter an object whose status is Deleted, you should assume that all the objects under that object will behave as if they are deleted.
Note: Once you delete an object you cannot undelete it.
These are some of the features and the working methodology of Yahoo Search Marketing API, and how it will work, what are the basic things we have to get in touch with, before going to start with Yahoo Enterprise Web Service etc… are explained. Then how we can use Yahoo Search Marketing API for an agency/reseler or for an advertiser.
2 Comments