WEB ANALYTICSWeb ServicesAPI Reference ManualJune 30, 2010
Yahoo! Web Analytics Web Services API Reference Manual                                                                    ...
Yahoo! Web Analytics Web Services API Reference Manual                                                                    ...
Yahoo! Web Analytics Web Services API Reference Manual                                                                    ...
Yahoo! Web Analytics Web Services API Reference Manual                                               5/761 Revision Histor...
Yahoo! Web Analytics Web Services API Reference Manual                                               6/76                 ...
Yahoo! Web Analytics Web Services API Reference Manual                                                       7/762 Overvie...
Yahoo! Web Analytics Web Services API Reference Manual                                                   8/76createProject...
Yahoo! Web Analytics Web Services API Reference Manual                                                9/762.5 SOAP Impleme...
Yahoo! Web Analytics Web Services API Reference Manual                                           10/763 Yahoo! Web Analyti...
Yahoo! Web Analytics Web Services API Reference Manual                                                  11/76Name         ...
Yahoo! Web Analytics Web Services API Reference Manual                                                     12/76successful...
Yahoo! Web Analytics Web Services API Reference Manual                                                   13/76            ...
Yahoo! Web Analytics Web Services API Reference Manual                                                14/76fix_cost       ...
Yahoo! Web Analytics Web Services API Reference Manual                                                 15/76Campaign_Categ...
Yahoo! Web Analytics Web Services API Reference Manual                                                   16/76The createPr...
Yahoo! Web Analytics Web Services API Reference Manual                                                 17/76Name          ...
Yahoo! Web Analytics Web Services API Reference Manual   18/76Figure 1 Structure of the updateCampaign Call Response© 2000...
Yahoo! Web Analytics Web Services API Reference Manual                                                19/763.2 Account Inf...
Yahoo! Web Analytics Web Services API Reference Manual                                                  20/76report_id    ...
Yahoo! Web Analytics Web Services API Reference Manual                                                   21/76currency    ...
Yahoo! Web Analytics Web Services API Reference Manual                                                  22/763.2.5 The get...
Yahoo! Web Analytics Web Services API Reference Manual                                                        23/76limitNe...
Yahoo! Web Analytics Web Services API Reference Manual                                                     24/76         N...
Yahoo! Web Analytics Web Services API Reference Manual                                                        25/76Get the...
Yahoo! Web Analytics Web Services API Reference Manual                                                           26/76    ...
Yahoo! Web Analytics Web Services API Reference Manual                                                           27/76When...
Yahoo! Web Analytics Web Services API Reference Manual                                                         28/76      ...
Yahoo! Web Analytics Web Services API Reference Manual                               29/763.3.4 Report XML FormatThe follo...
Yahoo! Web Analytics Web Services API Reference Manual                                                       30/76Descript...
Yahoo! Web Analytics Web Services API Reference Manual                                               31/76          Name  ...
Yahoo! Web Analytics Web Services API Reference Manual                                                  32/763.4.3 The can...
Yahoo! Web Analytics Web Services API Reference Manual                                                   33/76            ...
Yahoo! Web Analytics Web Services API Reference Manual                                                  34/76          Nam...
Yahoo! Web Analytics Web Services API Reference Manual                                                 35/76The uploadEdsF...
Yahoo! Web Analytics Web Services API Reference Manual                                                  36/764 Fault Codes...
Yahoo! Web Analytics Web Services API Reference Manual                                  37/761007                        S...
Yahoo! Web Analytics Web Services API Reference Manual                                                   38/761120        ...
Yahoo! Web Analytics Web Services API Reference Manual                   39/765 Appendix A: Constants5.1 Campaign TypesId ...
Yahoo! Web Analytics Web Services API Reference Manual                  40/7614                         Atlantic : Atlanti...
Yahoo! Web Analytics Web Services API Reference Manual            41/7639                         Ekaterinburg : Ekaterinb...
Yahoo! Web Analytics Web Services API Reference Manual   42/765.3 CPC EnginesEngine Id                  Name1             ...
Yahoo! Web Analytics Web Services API Reference Manual   43/7624                         eSpotting DK25                   ...
Yahoo! Web Analytics Web Services API Reference Manual   44/761                          CAD15                         CHF...
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Yahoo Web Analytics API Reference Guide
Upcoming SlideShare
Loading in …5
×

Yahoo Web Analytics API Reference Guide

1,275 views

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,275
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
10
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Yahoo Web Analytics API Reference Guide

  1. 1. WEB ANALYTICSWeb ServicesAPI Reference ManualJune 30, 2010
  2. 2. Yahoo! Web Analytics Web Services API Reference Manual 2/76Table of Contents1 REVISION HISTORY..................................................................................................................... 52 OVERVIEW ................................................................................................................................... 7 2.1 SUPPORTED ENTITIES ...................................................................................................................7 2.2 SUPPORTED OPERATIONS .............................................................................................................7 2.3 GENERAL FORM OF THE YAHOO! WEB ANALYTICS API.................................................................... 8 2.4 XML-RPC IMPLEMENTATION .........................................................................................................8 2.5 SOAP IMPLEMENTATION ...............................................................................................................93 YAHOO! WEB ANALYTICS API CALLS ...................................................................................... 10 3.1 INITIALIZATION ............................................................................................................................10 3.1.1 The login Call ...................................................................................................................10 3.1.2 The logout Call................................................................................................................. 11 3.1.3 The createAccount Call ...................................................................................................11 3.1.4 The createCampaign Call ................................................................................................13 3.1.5 The createProject Call .....................................................................................................15 3.1.6 The updateCampaign Call ...............................................................................................16 3.2 ACCOUNT INFORMATION ..............................................................................................................19 3.2.1 The getActions Call..........................................................................................................19 3.2.2 The getBookmarks Call ...................................................................................................19 3.2.3 The getCampaigns Call ...................................................................................................20 3.2.4 The getEditions Call.........................................................................................................21 3.2.5 The getProjects Call ........................................................................................................22 3.2.6 The getReports Call .........................................................................................................22 3.2.7 The getScenarios Call .....................................................................................................23 3.2.8 The getTrackingCode Call ...............................................................................................23 3.3 REPORTING ................................................................................................................................ 24 3.3.1 The ScheduleReportJobStandard Call ............................................................................25 3.3.2 The ScheduleReportJobBookmark Call .......................................................................... 27 3.3.3 The getReportJob Call .....................................................................................................28 3.3.4 Report XML Format .........................................................................................................29 3.4 ORDER RECONCILIATION .............................................................................................................30 3.4.1 The approveOrder Call ....................................................................................................30 3.4.2 The changeOrder Call .....................................................................................................31 3.4.3 The cancelOrder Call .......................................................................................................32 3.4.4 The changeOrderList Call................................................................................................32 3.4.5 The getChangeOrderListStatus Call................................................................................33 3.4.6 The getChangeOrderListErrors Call ................................................................................33 3.5 EXTERNAL DATA SOURCES .........................................................................................................34 3.5.1 The uploadEdsFile Call....................................................................................................34© 2000-2010 Yahoo! Inc. All rights reserved.
  3. 3. Yahoo! Web Analytics Web Services API Reference Manual 3/76 3.5.2 The getEdsJobStatus Call ...............................................................................................354 FAULT CODES ........................................................................................................................... 36 4.1 HTTP, XML LEVEL FAULT CODES ...............................................................................................36 4.2 HTTP HEADER AND XML FAULT CODES ......................................................................................36 4.3 USER-LEVEL FAULT CODES .........................................................................................................37 4.4 FILTER FAULT CODES .................................................................................................................385 APPENDIX A: CONSTANTS ....................................................................................................... 39 5.1 CAMPAIGN TYPES .......................................................................................................................39 5.2 TIMEZONES ................................................................................................................................ 39 5.3 CPC ENGINES ............................................................................................................................42 5.4 CURRENCIES ..............................................................................................................................43 5.5 COUNTRY CODES .......................................................................................................................45 5.6 REPORTS ...................................................................................................................................55 5.7 REPORTFILETYPE.......................................................................................................................596 APPENDIX B: FILTERS .............................................................................................................. 607 APPENDIX C: SOAP EXAMPLES ............................................................................................... 63 7.1 SOAP FAULT CODE EXAMPLE .....................................................................................................63 7.2 LOGIN CALL SOAP EXAMPLE ......................................................................................................63 7.3 LOGOUT CALL SOAP EXAMPLE ...................................................................................................64 7.4 CREATEACCOUNT CALL SOAP EXAMPLE .....................................................................................64 7.5 CREATECAMPAIGN CALL SOAP EXAMPLE ....................................................................................65 7.6 CREATEPROJECT CALL SOAP EXAMPLE ......................................................................................66 7.7 GETACTIONS CALL SOAP EXAMPLE ............................................................................................66 7.8 GETCAMPAIGNS CALL SOAP EXAMPLE........................................................................................67 7.9 GETEDITIONS CALL SOAP EXAMPLE ...........................................................................................68 7.10 GETPROJECTS CALL SOAP EXAMPLE..........................................................................................68 7.11 SCHEDULEREPORTJOBSTANDARD CALL SOAP EXAMPLE ............................................................ 69 7.12 XML REPORT EXAMPLE ..............................................................................................................70 7.13 GETREPORTS CALL SOAP EXAMPLE ...........................................................................................74 7.14 GETSCENARIOS CALL SOAP EXAMPLE ........................................................................................75 7.15 GETTRACKINGCODE CALL SOAP EXAMPLE .................................................................................75© 2000-2010 Yahoo! Inc. All rights reserved.
  4. 4. Yahoo! Web Analytics Web Services API Reference Manual 4/76Table of FiguresFigure 3 Structure of the updateCampaign Call Response................................................................... 18Figure 4 Structure of the XML Report.................................................................................................... 29© 2000-2010 Yahoo! Inc. All rights reserved.
  5. 5. Yahoo! Web Analytics Web Services API Reference Manual 5/761 Revision HistoryDate API Version Revisions New feature:February 2008 3.0 - Filters parameter for the ScheduleReportJobBookmarkRequest and the ScheduleReportJobStandardRequest calls New feature:September 2007 3.0 - External Data Sources (EDS) (uploadEdsFile call, getEdsJobStatus call) Removed: XML-RPC support New feature: - asynchronous reporting,April 2007 3.0 - compressed report response (ScheduleReportJobStandard call, ScheduleReportJobBookmark call, ScheduleReportJobResponse call) New feature:December 2006 2.26 - new getReport XML response structure, - new updateCampaign call New feature: - Bulk Order Reconciliation supportJun 2006 2.25 ( changeOrderList call, getChangeOrderListStatus call, getChangeOrderListErrors call) There are 2 new reports. See section 5.6 Reports. New features:May 2006 2.24 - Order Reconciliation support (approveOrder call, changeOrder call, cancelOrder call) getCampagins call modified : new cost type addedApril 2006 2.23 (ppc_autosetup)April 2006 2.22 New features: getReportFromBookmarkV2 call New features: getBookmarks call,March 2006 1.21 getReportFromBookmark call GetReport call’s response changedJuly 2005 1.2 SOAP Implementation© 2000-2010 Yahoo! Inc. All rights reserved.
  6. 6. Yahoo! Web Analytics Web Services API Reference Manual 6/76 New features : getEditions call, getScenarios call,July 2005 1.15 getReports call, new reportsJune 2005 1.14 Fault Codes updatedFebruary 2005 1.13 time zone identifiers changedFebruary 2005 1.12 getReport Call XML_RPC Example correctionsJanuary 2005 1.11 Additional error codes XML-RPC compliance added; Report retrieval methodsJanuary 2005 1.1 addedDecember 2004 1.0 Initial revision© 2000-2010 Yahoo! Inc. All rights reserved.
  7. 7. Yahoo! Web Analytics Web Services API Reference Manual 7/762 OverviewThe Yahoo! Web Analytics API documentation provides the information necessary to access theYahoo! Web Analytics API. The API provides a programmatic means of interacting with the Yahoo!Web Analytics platform to access and change data for the main entities represented in the Yahoo!Web Analytics system.2.1 Supported EntitiesYou can use the Yahoo! Web Analytics API to access and change the following entity types:Entity Notesaccount Basic entity, parent of all. Account’s child entity. One account may have many users with different useruser rights. By creating an account, a user entity is created automatically with the same user name as the account name. This user has full administrative rights. Account’s child entity. One account may have many projects with a separate tracking data space. By creating an account, a project entity is createdproject automatically. One project may be used to track a (1) whole web site, a (2) subsection of a web site, (3) multiple web sites. An advertisement campaign. Projects child entity. One project may have manycampaign campaigns. A series of steps web visitors take in order to complete a given transaction.scenario Project’s child entity. One project may have many scenarios.edition The projects edition. Report settings action filter. Project’s child entity. One project may have manyaction actions.The list of supported entities may change in the future. Some of the entities may not be accessible to aparticular user, partner, or during a particular login session, depending on the organization’s anduser’s permissions.2.2 Supported OperationsOperation Descriptionlogin Start a session.logout Finish a session.createAccount Create an account (including a user and a project).© 2000-2010 Yahoo! Inc. All rights reserved.
  8. 8. Yahoo! Web Analytics Web Services API Reference Manual 8/76createProject Create an additional project within an account.createCampaign Create a campaign within a project.getActions Retrieve the available actions of a project.getBookmarks Retrieve the bookmarks of a project.getCampaigns Retrieve the campaigns of a project.getEditions Retrieve editions.getProjects Retrieve the projects of an account.getReport Retrieve a report.getReportFromBookmark Retrieve a bookmarked report.getReportFromBookmarkV2 Retrieve a bookmarked report. New parameters: offset and limit.getReports Retrieve the available reports of a user/account.getTrackingCode Retrieve the tracking code for a project.getScenarios Retrieve scenarios for a project. Changes the status of a previously recorded pending sale action toapproveOrder an approved sale.changeOrder Changes the order’s (sale action) amount or currency.cancelOrder Deletes an order that was previously recorded in the system.ScheduleReportJobStandard Returns statistical data for a project.ScheduleReportJobBookmark Returns statistical data for a project.2.3 General Form of the Yahoo! Web Analytics APIEach API call is initiated by a request from a client and has a response from the server. API calls arenever initiated from the server to the client. Each API call has a method name, which is one of theoperations described in section 2.2 Supported Operations.2.4 XML-RPC ImplementationFormer versions of the API supported the XML-RPC protocol. The current version (and futureversions) of the API supports only the SOAP protocol.© 2000-2010 Yahoo! Inc. All rights reserved.
  9. 9. Yahoo! Web Analytics Web Services API Reference Manual 9/762.5 SOAP ImplementationThe Yahoo! Web Analytics API allows you to encode your calls using the Simple Object AccessProtocol (SOAP). SOAP is an XML-based protocol for exchanging information. Seewww.w3.org/TR/SOAP for a detailed description of SOAP.SOAP specifications for the Yahoo! Web Analytics API are detailed in the API calls sections of thisdocument.See the Yahoo! Web Analytics WSDL athttps://reports.web.analytics.yahoo.com/api/IndexToolsApiV3.wsdlNOTE!If you have become a customer of IndexTools before May 2008, you need to use the below temporaryURL until the migration to the new Yahoo! data center has been successfully completed:https://reportx.web.analytics.yahoo.com/api/IndexToolsApiV3.wsdlYou may also find the WSDL file linked from the YWA user interface under the Settings section.Yahoo! Web Analytics uses several custom types for its SOAP implementation, which are described inthe WSDL schema.© 2000-2010 Yahoo! Inc. All rights reserved.
  10. 10. Yahoo! Web Analytics Web Services API Reference Manual 10/763 Yahoo! Web Analytics API Calls3.1 InitializationAn API sessions first needs to be initialized using the login Call. The URL (including a session ID)returned by the login call can be reused during subsequent calls until the session expires. The sessionmust be closed using the logout call.3.1.1 The login CallEach user of the API can find their own API token by logging into their analytics account andnavigating to Settings - Yahoo! Web Analytics API - YWA API Credentials. On the following screen, theAPI token is available, as well as links to the Yahoo! Web Analytics WSDL.Each SOAP login call must be made to the URL:https://api.web.analytics.yahoo.com/IndexTools/services/IndexToolsApiV3Subsequent calls are made to the URL returned by the login call.NOTE!If you have become a customer of IndexTools before May 2008, you need to use the below temporaryURL until the migration to the new Yahoo! data center has been successfully completed:https://apix.web.analytics.yahoo.com/IndexTools/services/IndexToolsApiV3When using the final URL - https://api.web.analytics.yahoo.com/IndexTools/services/IndexToolsApiV3- for authentication purposes, you need to include with each request the YWA_API_TOKEN in theHTTP.Sample:POST /api HTTP/1.1Host: HOST:PORTConnection: Keep-AliveYWA_API_TOKEN: YOUR_API_TOKENUser-Agent: PHP-SOAP/5.2.0-8+etch7Content-Type: text/xml; charset=utf-8SOAPAction: "urn:IndexToolsApiAction"Content-Length: 455<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="http://v3.soap.api.indextools.com"><SOAP-ENV:Body><ns1:Login><PartnerId>YOUR_API_TOKEN</PartnerId><PartnerPassword>YOUR_API_PASSWORD</PartnerPassword><UserId>USER_ID</UserId><UserPassword>USER_PASSWORD</UserPassword><IsSecure>false</IsSecure></ns1:Login></SOAP-ENV:Body></SOAP-ENV:Envelope>The login call takes an API Partner ID and password (note the API Partner ID and password aredifferent from the Yahoo! Web Analytics partner id and password in the user interface), an optionalUser ID and password, and validates them.The login request requires the following fields (the fields in bold are mandatory):© 2000-2010 Yahoo! Inc. All rights reserved.
  11. 11. Yahoo! Web Analytics Web Services API Reference Manual 11/76Name Format Descriptionpartner_id String API Partner identifier supplied by IndexTools.partner_password Max. 32 chars API Partner password supplied by IndexTools. Account’s administrative User ID. If the user_id/user_password parameters are not supplied, theuser_id Max. 32 chars session will have limited privileges and only the createAccount operation will be allowed. If the user_id/user_password parameters are not supplied,user_password Max. 32 chars the session will have limited privileges and only the createAccount operation will be allowed. Boolean. Specifies whether the login response should return a secure URL in the “server_url” parameter. This is ansecure Boolean obsolete parameter, as all responses will be sent to secure URLs. This parameter must be set to “true” at all times.There are two types of login privileges. If only the partner id and password are supplied, a partnersession will be created and only the createAccount operation will be allowed. If both the partner anduser login information are supplied, a user session will be created with non-restricted privileges.The login call returns the following parameters:Name Format Descriptionsession_id Max. 64 chars This parameter is obsolete in this version. Max. 128 All future requests to the API in this session must be sent toserver_url chars this URL.The other call’s endpoint must be the retrieved server_url!See section 7.2 login Call SOAP Example.3.1.2 The logout CallThe logout call does not require any arguments beyond the basic set. A successful response is empty.See section 7.3 logout Call SOAP Example.Using Account Management calls, you can create an Yahoo! Web Analytics account, add new projectsto an account and add new campaigns to a project.3.1.3 The createAccount CallThe createAccount call creates an account entity, as well as a user and a project entity in the Yahoo!Web Analytics system. If the client does not have an Yahoo! Web Analytics account yet, this callshould be executed first. The execution of this call requires a successful partner login. After the© 2000-2010 Yahoo! Inc. All rights reserved.
  12. 12. Yahoo! Web Analytics Web Services API Reference Manual 12/76successful execution of the createAccount operation, the partner session will automatically be"upgraded" to a user session, in order to allow you to perform further operations to the account.The createAccount request requires the following fields (the fields in bold are mandatory):Name Format Description Specify the desired user id. Use this id to reference the useruser_id Max. 32 chars during login in the future.user_password Max. 32 chars Specify the desired user password. Max. 128email Specify a valid e-mail address. charsfirstname Max. 16 chars First name.lastname Max. 16 chars Last name.tel Max. 16 chars Telephone number.address Max. 16 chars Address.city Max. 16 chars City.country Max. 2 chars Two letter country code. See section 5.5 Country Codes. Max. 256base_url Project’s root URL e.g., www.abc.com charsproject_name Max. 64 chars Project’s user-friendly name.timezone Digits See section 5.2 Timezones. You can only create a trial edition and the only possibleedition_id Max. 8 chars values are STAT3TRL (for an E-Business edition) and STAT5TRL (for a Enterprise edition).company Max. 64 chars Company name.default_currency Digits Default: USD. See section 5.4 Currencies.The createAccount call returns the following parameters:Name Format Descriptionaccount_id Digits Numeric identifier of the account.© 2000-2010 Yahoo! Inc. All rights reserved.
  13. 13. Yahoo! Web Analytics Web Services API Reference Manual 13/76 Numeric identifier of the project. Use this id to reference theproject_id Digits project in the future.See section 7.4 createAccount Call SOAP Example.3.1.4 The createCampaign CallThe createCampaign call creates a new campaign entity within the project.The createCampaign request requires the following fields (the fields in bold are mandatory):Name Format Descriptionproject_id Digits Numeric identifier of the project. Identify campaign type. See section 5.1campaign_type Digits Campaign Types. Max.campaign_name 64 charscampaign_start YYYY-MM-DDcampaign_end YYYY-MM-DD Max.campaign_desc 256 Campaign description. charsstatus SHOW | HIDE Max. url | referrer | parameter (These are theparameter 32 equivalents for Page URL, Referring URL, Query chars Parameter in the campaign setup interface.) Max.operator 16 equals | contains chars Max.condition 256 e.g., source=google charscurrency Digits See section 5.4 Currencies. Default: USD Max. 8 FREE | FIXED | CPC | CPA| PPC|cost_type chars PPC_AUTOSETUPaction_id Digits Specify action id. (Required for CPA)© 2000-2010 Yahoo! Inc. All rights reserved.
  14. 14. Yahoo! Web Analytics Web Services API Reference Manual 14/76fix_cost Digits Specify fixed CPC cost if applicable, e.g., 0.15 Max.Engine_Properties/Engine 255 Specify CPC engine name. chars Max. Specify CPC user name. (Required for PPC orEngine_Properties/Username 64 PPC_AUTOSETUP only.) chars Max. Specify CPC password. (Required for PPC orEngine_Properties/Password 64 PPC_AUTOSETUP only.) chars Max. Specify Engine account id. (Required for PPC orEngine_Properties/Overture_Account_Id 64 PPC_AUTOSETUP only.) chars Possible to use at banner campaign (number ofquantity Digits impression) and email campaign (number of emails) Max. Specify URL parameter that contains the searchEngine_Properties/Listing 32 listing variable. E.g. listing, kw or OVKEY chars Max. 8 on | off (Overture autobid function). (Required forEngine_Properties/Is_Auto_Bid chars PPC or PPC_AUTOSETUP only.)Campaign_Category2 Specify the value of Campaign Category 2. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 2 is chars higher than Campaign 3).Campaign_Category3 Specify the value of Campaign Category 3. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 3 is chars higher than Campaign 4).Campaign_Category4 Specify the value of Campaign Category 4. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 4 is chars higher than Campaign 5).Campaign_Category5 Specify the value of Campaign Category 5. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 5 is chars higher than Campaign 6).Campaign_Category6 Specify the value of Campaign Category 6. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 6 is chars higher than Campaign 7).© 2000-2010 Yahoo! Inc. All rights reserved.
  15. 15. Yahoo! Web Analytics Web Services API Reference Manual 15/76Campaign_Category7 Specify the value of Campaign Category 7. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 3 is chars higher than Campaign 8).Campaign_Category8 Specify the value of Campaign Category 8. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 8 is chars higher than Campaign 9).Campaign_Category9 Specify the value of Campaign Category 9. Max Campaign categories are presented in a 64 hierarchical structure (Campaign Category 9 is chars higher than Campaign 10).Campaign_Category10 Max 64 Specify the value of Campaign Category 10. charsThe createCampaign call returns the following parameters:Name Format Description Numeric identifier of the campaign. Use this id to referencecampaign_id Digits the campaign in the future.See section 7.5 createCampaign Call SOAP Example.3.1.5 The createProject CallThe createProject call creates an additional project entity within the account. Please note than an initialproject is being generated during the createAccount operation, therefore this call is only required ifmore than one projects is required.The createProject request requires the following fields (the fields in bold are mandatory):Name Format Description Max. 256base_url Project’s root URL e.g., www.abc.com. charsproject_name Max. 64 chars Project’s user-friendly nametimezone Digits See section 5.2 Timezones. You can retrieve your available editions with the getEditionsedition_id Max. 8 chars call, see section 3.2.4 The getEditions Call.default_currency Digits See section 5.4 Currencies. Default: USD© 2000-2010 Yahoo! Inc. All rights reserved.
  16. 16. Yahoo! Web Analytics Web Services API Reference Manual 16/76The createProject call returns the following parameters: Name Format Description Numeric identifier of the project. Use this id to reference theproject_id Digits project in the future.See section 7.6 createProject Call SOAP Example.3.1.6 The updateCampaign CallThe updateCampaign call allows you to update your campaign settings.The updateCampaign request requires the following fields (the fields in bold are mandatory):Name Format DescriptionProjectId Integer Numeric identifier of the project.Campaign StructureCampaign_Category2 Max 64 chars Modify the value of Campaign Category 2.Campaign_Category3 Max 64 chars Modify the value of Campaign Category 3.Campaign_Category4 Max 64 chars Modify the value of Campaign Category 4.Campaign_Category5 Max 64 chars Modify the value of Campaign Category 5.Campaign_Category6 Max 64 chars Modify the value of Campaign Category 6.Campaign_Category7 Max 64 chars Modify the value of Campaign Category 7.Campaign_Category8 Max 64 chars Modify the value of Campaign Category 8.Campaign_Category9 Max 64 chars Modify the value of Campaign Category 9.Campaign_Category10 Max 64 chars Modify the value of Campaign Category 10.The Campaign structure contains the following parameters:© 2000-2010 Yahoo! Inc. All rights reserved.
  17. 17. Yahoo! Web Analytics Web Services API Reference Manual 17/76Name Format DescriptionId Digits Unique numeric identifier of the campaign.Name Max. 64 chars The campaign name. Max. 256Description Campaign description. chars It shows whether the campaign is active or not. If the SHOW, HIDE, campaign is active, the State parameter is SHOW. If theState DELETED campaign is inactive, the State parameter is HIDE. If the campaign is deleted, the State parameter is DELETED.StartDate Digits The date when the campaign starts. If true, the campaign runs continuously and the campaign does not have an end date.IsEndDateContinuous Boolean If false, the campaign has an end date, which must be specified with the EndDate parameter.EndDate Digits The date when the campaign ends. This parameter is only valid for Banner and Email Campaigns. For a Banner campaign, the Quantity showsQuantity Digits the number of impressions. For an Email Campaign, the Quantity shows the number of emails.If the method execution was not successful, one of the following exceptions will be thrown:1101 - Campaign NOT found in this project.1101 - If the isEndDateContinous is false, you have to set the EndDate too.1101 - Unknown/missing parameter (required, wrong parameter).The following diagram illustrates the structure of the updateCampaign call request.© 2000-2010 Yahoo! Inc. All rights reserved.
  18. 18. Yahoo! Web Analytics Web Services API Reference Manual 18/76Figure 1 Structure of the updateCampaign Call Response© 2000-2010 Yahoo! Inc. All rights reserved.
  19. 19. Yahoo! Web Analytics Web Services API Reference Manual 19/763.2 Account InformationThese operations primarily help you to perform other operations in the API, e.g., in order to retrieve abookmarked report from the system, you need to download first the list of bookmarks; in order to filteron specific campaigns, you need to retrieve the list of campaigns from the system.3.2.1 The getActions CallThe getActions call returns all useable action name sand code of a project.The getActions request requires the following field (the field in bold is mandatory):Name Format Descriptionproject_id Digits Numeric identifier of the project.The getActions call returns an array including the following fields:Name Format Descriptionaction_id Digits Numeric identifier of the action. Name of the corresponding action. Note that the action id 01action_name Max. 64 Chars is reserved for the sale action, other actions can be renamed.See section 7.7 getActions Call SOAP Example.3.2.2 The getBookmarks CallThe getBookmarks call returns all available bookmarks for a project.The getBookmarks request requires the following field (the field in bold is mandatory): Name Format Descriptionproject_id Digits Numeric identifier of the project.The getBookmarks call returns an array including the following fields: Name Format Descriptionid Digits Numeric identifier of the bookmark.name String Bookmark name.description String Bookmark’s description.© 2000-2010 Yahoo! Inc. All rights reserved.
  20. 20. Yahoo! Web Analytics Web Services API Reference Manual 20/76report_id ReportId Numeric identifier of the report. If true, the reporting period is from the bookmark’s start_date until the bookmark’s end_date.use_saved_period Boolean If false, the reporting period is based on the parameters of the getReportFromBookmark call.start_date Date Begining of the reporting period.end_date Date End of the reporting period.3.2.3 The getCampaigns CallThe getCampaigns call returns all active campaigns of a project.The getCampaigns request requires the following the following field (the field in bold is mandatory):Name Format Descriptionproject_id Digits Numeric identifier of the project.The getCampaigns call returns an array including the following parameters:Name Format Descriptioncampaign_type Digits Identify campaign type. See section 5.1 Campaign Types.campaign_id Digits Numeric identifier of the campaign.campaign_name Max. 64 charscampaign_start DateTimecampaign_end DateTime Max. 256campaign_desc Campaign description charscreated_date DateTime Date when campaign was createdstatus SHOW | HIDEparameter Max. 32 chars url | referreroperator Max. 16 chars equals | contains Max. 256condition e.g., source=google chars© 2000-2010 Yahoo! Inc. All rights reserved.
  21. 21. Yahoo! Web Analytics Web Services API Reference Manual 21/76currency Digits See section 5.4 Currencies. Default: USDcost_type Max. 8 chars FREE | FIXED | CPC | CPA| PPC| PPC_AUTOSETUPaction_id Digits Specify action id. (Required for CPA)fix_cost Digits Specify fixed CPC cost if applicable, e.g., 0.15 Max. 255cpc_engine_name Specify CPC engine name chars Numeric identifier of the CPC engine. See section 5.3 CPCcpc_engine_id Digits Engines. (Required for RTCR only.) Specify CPC user name. (Required for PPC orcpc_username Max. 64 chars PPC_AUTOSETUP only.) Specify CPC password. (Required for PPC orcpc_password Max. 64 chars PPC_AUTOSETUP only.) Specify Overture account id. (Required for PPC orengine_account_id Max. 64 chars PPC_AUTOSETUP only.) Possible to use at banner campaign (number of impression)quantity Digits and email campaign (number of emails) Specify URL parameter that contains the search listingcpc_listing Max. 32 chars variable. E.g. listing, kw or OVKEY on | off (Overture autobid function). (Required for PPC orcpc_autobid Max. 8 chars PPC_AUTOSETUP only.)See section 7.8 getCampaigns Call SOAP Example.3.2.4 The getEditions CallThe getEditions call returns all available editions to create new project. The getEditions request doesnot require any arguments.The getEditions call returns an array including the following fields (the fields in bold are mandatory): Name Format Descriptionedition_id Digits Numeric identifier of the editionname String Name of the editiondescription String Description of the editionSee section 7.9 getEditions Call SOAP Example© 2000-2010 Yahoo! Inc. All rights reserved.
  22. 22. Yahoo! Web Analytics Web Services API Reference Manual 22/763.2.5 The getProjects CallThe getProjects call returns all active projects of an account. The getProjects request does not requireany arguments beyond the basic set.The getProjects call returns an array including the following fields (the fields in bold are mandatory): Name Format Descriptionproject_id Digits Numeric identifier of the project.project_name Max. 64 chars Project’s user-friendly name Max. 256base_url Project’s root URL e.g., www.abc.com charstimezone Digits See section 5.2 Timezones.first_record_date Date Date of first time a hit was recorded in the project.edition_id Max. 8 chars Project’s edition iddefault_currency Digits See section 5.4 Currencies.See section 7.10 getProjects Call SOAP Example.3.2.6 The getReports CallThe getReports call returns all available reports of a project.The getReports request requires the following field (the field in bold is mandatory): Name Format Descriptionproject_id Digits Numeric identifier of the project.The getReports call returns an array including the following parameters: Name Format Descriptionreport_id ReportId Numeric identifier of the report.name String Name of the report.description String Report description.help String Report help.© 2000-2010 Yahoo! Inc. All rights reserved.
  23. 23. Yahoo! Web Analytics Web Services API Reference Manual 23/76limitNeed Boolean If true, the limit property is mandatory for this report.sessionNeed Boolean If true, the session property is mandatory for this report.scenarioNeed Boolean If true, the scenario property is mandatory for this report. Available values: 0 : not usedactionNeed Digits 1 : optional 2 : required Available values: 0 : not usedcampaignNeed Digits 1 : optional 2 : requiredSee section 7.13 getReports Call SOAP Example.3.2.7 The getScenarios CallThe getScenarios call returns all useable scenarios of a project.The getScenarios request requires the following field (the field in bold is mandatory): Name Format Descriptionproject_id Digits Numeric identifier of the project.The getScenarios call returns an array including the following parameters: Name Format Descriptionscenario_id Digits Numeric identifier of the scenarioname String Name of the scenariodescription String Description of the scenarioSee section 7.14 getScenarios Call SOAP Example.3.2.8 The getTrackingCode CallThe getTrackingCode call returns the tracking code and the tracking JS file for a project.The getTrackingCode request requires the following fields (the fields in bold are mandatory):© 2000-2010 Yahoo! Inc. All rights reserved.
  24. 24. Yahoo! Web Analytics Web Services API Reference Manual 24/76 Name Format Descriptionproject_id Digits Numeric identifier of the project. Specify whether secure or non-secure tracking code shouldtransfer_protocol Digits be retrieved. 0 (HTTP), 1 (HTTPS) Max. 256 Specify exact location of the JS file if different from the roottrackingjs_location Chars directory of the server. Default “base_url/indextools.js” Optional custom variable. See Yahoo! Web Analyticsdocument_name Max. 32 Chars Installation Guide. Optional custom variable. See Yahoo! Web Analyticsdocument_group Max. 32 Chars Installation Guide. Optional custom variable. See Yahoo! Web Analyticsdomains Max. 32 Chars Installation Guide. Optional custom variable. See Yahoo! Web Analyticsmember_id Max. 32 Chars Installation Guide. Optional custom variable. See Yahoo! Web Analyticsaction_id Max. 2 Chars Installation Guide. Optional custom variable. See Yahoo! Web Analyticsamount Max. 32 Chars Installation Guide.The getTrackingCode call returns the following parameters: Name Format Descriptiontracking_code String HTML tracking code to be inserted into the page. Max. 256 Download URL of the indextools.js file to be uploaded to thetrackingjs Chars web site. Note that this file is project specific.See section 7.15 getTrackingCode Call SOAP Example.3.3 ReportingThe Reporting call provides operations for getting analytical reports from your Yahoo! Web Analyticsaccount. The reports are in XML format.To retrieve reports from the system: 1. Initialize your API sessionSend a ScheduleReportJobStandard or ScheduleReportJobBookmark request. The response is thereportJobId for the scheduled report job.© 2000-2010 Yahoo! Inc. All rights reserved.
  25. 25. Yahoo! Web Analytics Web Services API Reference Manual 25/76Get the status of the report job by sending the getReportJob request. The status is Completed,Pending or Failed. When the status is Completed, the response also includes the download URL forthe report. The returned URL is valid for 5 minutes. If you need to obtain another URL, simply sendanother getReportJob request. Make sure you keep the returned URL confidential since it allowsaccess to the report without the need to login.Download the report by sending an HTTP GET request to the download URL using any HTTP clientlibrary.NOTE:If you select a user-specific time zone in the user interface, which is different from the project defaulttime zone, the reports you access via the API will also be adjusted to a user-specific time zone.3.3.1 The ScheduleReportJobStandard CallThe ScheduleReportJobStandard call returns statistical data for a project.The ScheduleReportJobStandard request requires the following fields (the fields in bold aremandatory): Name Format Descriptionproject_id Digits Numeric identifier of the project. Date Beginning of the reporting period e.g., 2006-04-01. Note thatstart_date iso8601 dates must be entered in the year-month-day format. Date End of the reporting period e.g., 2006-05-01. Note that datesend_date iso8601 must be entered in the year-month-day format. Use the getReports() call to get the available report ids of thereport_id ReportId selected project. See section 5.6 Reports for examples of report ids. Number of rows omitted from the beginning of the report. The default value is 0 and the report starts with the first row.offset Digits If you are interested in looking at rows 20-30, the offset should be 19.limit Digits Number of rows to be displayed in the report. Numeric action identifier. This parameter is only needed foraction_id Digits conversion reports. Numeric campaign identifier. This parameter is only needed forcampaign_id Digits generating campaign details and campaign conversion reports. Use getScenarios() call to get the available scenario ids of thescenario_id Digits selected project. Session identifier. This parameter is only needed for the sessionsession_id 10 Chars path report.© 2000-2010 Yahoo! Inc. All rights reserved.
  26. 26. Yahoo! Web Analytics Web Services API Reference Manual 26/76 Specifies the sort value of the columns, i.e., 0 means the firstsort Digits column, 1 the second column etc. Note that the sorting order always starts with the sort values of the left-head labels. Sorts the column specified in the sort field. Possible values: ‘asc’ –sort_direction Max. 4 chars ascending; ‘desc’ - descending.show_help Boolean Indicates whether report help should be included in the response. Indicates whether report description should be included in theshow_description Boolean response.Filters Structure For details see the table below.The Filters parameter requires the following fields (the fields in bold are mandatory): Name Format Description Indicates the Type ID of the filter. For a complete list of the filterType String type IDs, see section 6 Appendix B: Filters. Indicates the operator to be used for a filter. It can be a String or a Number Operator. String Operators: Equals, NotEquals, BeginsWith, NotBeginsWith, EndsWith, NotEndsWith, Contains, NotContains, Empty, NotEmpty, Regexp. Number Operators: Equals, NotEquals, Greater, GreaterOrEquals, Less,Operator String LessOrEquals Indicates the value of the filter (e.g., when filtering by the BrowserValue String report, the Value can be Firefox).CaseSensitive Boolean Indicates whether the value is case-sensitive or not. Indicates the scope of the filter.Scope String Possible values: Session, Action, Page View.The ScheduleReportJobStandard call returns the following parameters: Name Format Description The ID of the report job to be used in subsequentReportJobId Long getReportJob calls.See section 7.11 ScheduleReportJobStandard Call SOAP Example.© 2000-2010 Yahoo! Inc. All rights reserved.
  27. 27. Yahoo! Web Analytics Web Services API Reference Manual 27/76When using filters, the ScheduleReportJobStandard call can return the exceptions listed under section4.4 Filter Fault Codes.3.3.2 The ScheduleReportJobBookmark CallThe ScheduleReportJobBookmark call returns statistical data for a project.The ScheduleReportJobBookmark request requires the following fields (the fields in bold aremandatory): Name Format Description Numeric identifier of the bookmark. Use getBookmarks() callBookmarkId Digits to get the available bookmark ids of the selected project. Beginning of the reporting period. This parameter is usedStartDate Date iso8601 only if the selected bookmark’s use_saved_period setting = false. End of the reporting period. This parameter is used only ifEndDate Date iso8601 the selected bookmark’s use_saved_period setting = false. Number of rows omitted from the beginning of the report.offset Digits Default 0.limit Digits Number of rows to be displayed.Filters Structure For details see the table below.The Filters parameter requires the following fields (the fields in bold are mandatory): Name Format Description Indicates the Type ID of the filter. For a complete list of the filterType String type IDs, see section 6 Appendix B: Filters. Indicates the operator to be used for a filter. It can be a String or a Number Operator. String Operators: Equals, NotEquals, BeginsWith, NotBeginsWith, EndsWith, NotEndsWith, Contains, NotContains, Empty, NotEmpty, Regexp. Number Operators: Equals, NotEquals, Greater, GreaterOrEquals, Less,Operator String LessOrEquals© 2000-2010 Yahoo! Inc. All rights reserved.
  28. 28. Yahoo! Web Analytics Web Services API Reference Manual 28/76 Indicates the value of the filter (e.g., when filtering by the BrowserValue String report, the Value can be Firefox).CaseSensitive Boolean Indicates whether the value is case-sensitive or not. Indicates the scope of the filter.Scope String Possible values: Session, Action, Page View.The ScheduleReportJobBookmark call returns the following parameters: Name Format Description The ID of the report job to be used in subsequentReportJobId Long getReportJob calls.When using filters, the ScheduleReportJobBookmark call can return the exceptions listed undersection 4.4 Filter Fault Codes.3.3.3 The getReportJob CallThes getReportJob call is used to get the status of the report job. The status is Completed, Pending orFailed. When the status is Completed, the response also includes the download URL for the report.The returned URL is valid for 5 minutes. If you need to obtain another URL, simply send anothergetReportJob request. Make sure you keep the returned URL confidential since it allows access to thereport without the need to login.The getReportJob call requires the following fields (the fields in bold are mandatory): Name Format Description The ID returned by prior ScheduleReportJobStandard orReportJobId Long ScheduleReportJobBookmark calls. The file format in which the report should be returned (XML, CSV, PDF, DOC, XLS).ReportFileType ReportFileType NOTE: This feature is not fully implemented yet. Currently only XML output is supported.The getReportJob call returns the following parameters: Name Format DescriptionReportJobStatus ReportJobStatus Completed, InProgress, Pending, Expired or Failed.ReportJobURL String Temporary download URL for the report.© 2000-2010 Yahoo! Inc. All rights reserved.
  29. 29. Yahoo! Web Analytics Web Services API Reference Manual 29/763.3.4 Report XML FormatThe following diagram illustrates the structure of the XML report generated by theScheduleReportJobStandard or ScheduleReportJobBookmark calls.Figure 2 Structure of the XML ReportA simplified description of the XML report structure is the following: TagName Type DescriptionTitle String Report title.© 2000-2010 Yahoo! Inc. All rights reserved.
  30. 30. Yahoo! Web Analytics Web Services API Reference Manual 30/76Description String Report description.Help String Report help. Indicates whether the result includes more data to follow. If theHasMoreRows Boolean value is ‘false’ you can use the ‘offset’ and/or ‘limit’ parameters to request the next page or request a longer report.TopHeadRows Array Array of report head names in each row.LeftHeadLabels String[] Labels of the left headers.LeftHeadRows Array Left header names with indent flag.DataRows Array[] This field contains DataCell fields in each row.SubTotalCells Array Array of subtotal (DataCell) values. Array of total (DataCell) values. Please note that this is not necessarily the total of what is returned in the report but theTotalCells Array total of the whole report including unknown items and data not shown on the page.UnknownCells Array Array of unknown (DataCell) values.The format of the DataCell is the following: TagName Type DescriptionValue String This shows data values in raw format. E.g. 35000. This shows formatted data values, i.e., as they appear on theFormattedValue String user interface. E.g. 35,000. This shows the type of data. Values are : Text, Int, Float,Type DataType Currency, Percent3.4 Order Reconciliation3.4.1 The approveOrder CallThe approveOrder call changes the status of a previously recorded pending sale action to an approvedsale. This feature allows you to update your reports with your successful sales, without having to worryabout aborted sales showing in your sales summary.The approveOrder request requires the following arguments:© 2000-2010 Yahoo! Inc. All rights reserved.
  31. 31. Yahoo! Web Analytics Web Services API Reference Manual 31/76 Name Format DescriptionProjectId Digits Numeric identifier of the project.OrderId String Order Identifier.Date Date Order’s creation date. The date must be older than 24 hours. Order’s amount expressed in whole numbers (e.g., a 10.2Amount Digits Euro amount will be expressed as a 1020 eurocents amount).Currency Digits Order’s currency. See section 5.4 Currencies.If sending the request is not successful, the interface will display an exception message. If sending therequest is successful, the interface will not display anything.NOTE:- You have to wait 12 hours before you can change the status of a pending sale into an approved sale.- You have to send us the request to change the status of a pending sale into an approved sale withina 3 day period from the date when the pending sale was first registered.3.4.2 The changeOrder CallThe changeOrder call changes the order’s (sale action) amount or currency.The changeOrder request requires the following fields (the fields in bold are mandatory): Name Format DescriptionProjectId Digits Numeric identifier of the project.OrderId String Order Identifier.Date Date Order’s creation date. The date must be older than 24 hours. Order’s amount expressed in whole numbers (e.g., a 10.2Amount Digits euro amount will be expressed as a 1020 eurocents amount).Currency Digits Order’s currency. See section 5.4 Currencies.If the method execution was not successful, an exception will be thrown.© 2000-2010 Yahoo! Inc. All rights reserved.
  32. 32. Yahoo! Web Analytics Web Services API Reference Manual 32/763.4.3 The cancelOrder CallThe cancelOrder call deletes an order that was previously recorded in the system. The cancelOrderrequest requires the following fields (the fields in bold are mandatory): Name Format DescriptionProjectId Digits Numeric identifier of the project.OrderId String Order Identifier.Date Date Order’s creation date. The date must be older than 24 hours.If the method execution was not successful, an exception will be thrown.3.4.4 The changeOrderList CallTo use the Bulk Order Change:Create a ChangeOrderListRequest with the list of modified orders. In the request all the projects mustbe the same, otherwise you will get an error message. However, you can include different commandson the same project in a single request. Send this request to the server, and you will receive the JobIdof this request.Get the status of the report job by sending the getChangeOrderListStatus call. The status can be:Pending, Done, Done With Error.Pending: the request has been accepted and is still in progress.Done: all orders have been completed without errors.Done with Error: all orders have been completed, but some orders contained errors.If the result is Done With Error, you can get the list of errors with the getChangeOrderListErrors call.With the changeOrderList call, you can approve, change or removes order (sale) actions.Depending on the type of command, the changeOrderList request requires different combinations ofthe arguments listed below (If you use the Change command, you have to set either the amount or thecurrency):The fields in bold are mandatory. Name Format DescriptionCommand Approve | Cancel | ChangeProjectId Digits Numeric identifier of the project.OrderId String Order Identifier. Order’s creation date. The date must be within a 3 dayDate Date range. It must be older than 12 hours.© 2000-2010 Yahoo! Inc. All rights reserved.
  33. 33. Yahoo! Web Analytics Web Services API Reference Manual 33/76 Order’s amount expressed in whole numbers (e.g., a 10.2Amount Digits euro amount will be expressed as a 1020 eurocents amount).Currency Digits Order’s currency. See section 5.4 Currencies.The changeOrderList call returns the following parameters: Name Format Description Unique identifier assigned to each changeOrderList call.JobId Digits With this ID you can get status information and the list of errors, if any.3.4.5 The getChangeOrderListStatus CallWith the getChangeOrderListStatus call, you can check the status of the previously sent request.The getChangeOrderListStatus request requires the following field (the field in bold is mandatory): Name Format DescriptionJobId Digits Unique identifier assigned to each changeOrderList call.The getChangeOrderListStatus call returns the following parameter: Name Format DescriptionStatus Digits PENDING | DONE | DONEWITHERROR (see section 3.4.4).3.4.6 The getChangeOrderListErrors CallWith the getChangeOrderListErrors call, you can check the list of errors that resulted from trying tocomplete the request.The getChangeOrderListErrors request requires the following field (the field in bold is mandatory): Name Format DescriptionJobId Digits Unique identifier assigned to each changeOrderList call.The getChangeOrderListErrors call returns the following list of error parameters:© 2000-2010 Yahoo! Inc. All rights reserved.
  34. 34. Yahoo! Web Analytics Web Services API Reference Manual 34/76 Name Format DescriptionCommand APPROVE | CHANGE | CANCELProjectId Digits Numeric identifier of the project.OrderId String Order Identifier. Order’s creation date. The date must be within a 3 dayDate Date range. It must be older than 12 hours.ErrorCode Digits See section 4.2 HTTP Header and XML Fault Codes.3.5 External Data SourcesExternal Data Sources (EDS) is an integration feature available in the Yahoo! Web Analytics 10Enterprise Edition, which allows you to merge data originating from external sources, such ascampaign management systems, email systems, or other internal systems with your web analyticsreporting.To use the EDS feature, you need to contact the Yahoo! Web Analytics Professional Services team,which will assist you at every level of the implementation process. Furthermore, if you want to takeadvantage of the Beta version of the EDS feature (before the release of Yahoo! Web Analytics 10), ourProfessional Services team will be able to help you depending on your requirements.3.5.1 The uploadEdsFile CallWith the uploadEdsFile call, you can upload a file to our system.The uploadEdsFile request requires the following fields (the fields in bold are mandatory): Name Format DescriptionfileName String Name of the uploaded file.projectId Digits Numeric project ID. Numeric ID of the EDS Data source provided by Yahoo! WebdatasourceId Digits Analytics Professional Services Possible values: "replace" or "append": "replace" removesuploadMode String and replaces the existing EDS file; "append" adds a new EDS file to the existing files. The file that contains the data to be uploaded.attached file Stream It must be sent as a SOAP attachment!© 2000-2010 Yahoo! Inc. All rights reserved.
  35. 35. Yahoo! Web Analytics Web Services API Reference Manual 35/76The uploadEdsFile call returns the following parameter: Name Format DescriptionedsJobId Digits Numeric ID of the started EDS job.If the given parameters are valid (the project ID and the datasourceID are valid, the project ID and thedatasourceID match, and the attachment is present), the attached file will be saved, and an ID will begiven to the EDS job. This EDS job ID is then returned to the caller.Afterwards, the EDS daemon, which is checking periodically for newly uploaded files, starts processingthe content and completes the EDS job. After completing the job, the EDS daemon sets the status ofthe job to COMPLETED or FAILED.Typically, uploading the EDS file takes 1-2 minutes; however, depending on the size of the file, theuploading process can take up to 30 minutes.3.5.2 The getEdsJobStatus CallWith the getEdsJobStatus call, you can check the status of the EDS job.The getEdsJobStatus request requires the following field (the field in bold is mandatory): Name Format Description Numeric ID of the started EDS job, retrieved as theedsJobId Digits uploadEdsFile calls result.If the edsJobId is valid, the system returns the status of the EDS job; if the edsJobId status is Failed,the system returns an error list.The getEdsJobStatus call returns the following parameters: Name Format Description Status of the EDS job identified by the edsJobId; possiblestatus String values: Pending, InProgress, Completed, Failed. If the status of the EDS job is Failed, this parameter contains a list of Error Code - Error Message pairs regarding the nature of the error (i.e., If the uploaded data contains an error, theerrorList Pair error list will indicate the row and the column where the error occurs and the type of error.) Note that only the first 10 errors appearing in a document will be displayed.© 2000-2010 Yahoo! Inc. All rights reserved.
  36. 36. Yahoo! Web Analytics Web Services API Reference Manual 36/764 Fault CodesYahoo! Web Analytics API requests can return a successful response or a fault response. A faultresponse indicates that the request could not be completed. A fault response is composed of an errorcode and a text message. The fault message is a short description in English that can be displayed tothe user as a minimally descriptive error message. If you display the fault message, you should alsodisplay the fault code. Clients should always recognize the fault codes, not the fault messages. Theactual fault messages may vary slightly from the messages listed in this appendix.Some faults are particular to certain calls, while others are more general faults that could happen onany call, such as error code 1000 for a null parameter list. Each subsection lists fault codes thatcommonly occur with a particular call. However, the fault codes listed for a particular call could occurwith any other call as well.Beyond the fault codes, clients should also check that the response Content-Type in the HTTP headeris .text/xml. Any other type, such as .text/html, indicates that the application server is down orunreachable, such as being blocked by a firewall.See section 7.1 SOAP Fault Code Example.4.1 HTTP, XML Level Fault CodesFault codes 0 and -1 are used for general faults.Code Message Invalid XML or XML-RPC syntax. Usually indicates a development error on the0 client. The server does not attempt to inform you about how to correct the XML or XML-RPC. You must validate the request on your own. Unspecified internal API error while processing the request. Usually indicates a-1 runtime error on the server. Contact Yahoo! Web Analytics for more help.4.2 HTTP Header and XML Fault CodesCode Message1001 Session ID required in cookie for non-login request1002 Invalid Content-Encoding1003 API currently disabled1004 API not enabled for this user or organization User or organization is not allowed to use the API during this time period, or has1005 exceeded its API quota for this time period. User or organization has exceeded rate limit. Sleep and try again in ’X’ ms1006 (where ’X’ is an integer listed at the beginning of the text message and followed by „ms delay:”)© 2000-2010 Yahoo! Inc. All rights reserved.
  37. 37. Yahoo! Web Analytics Web Services API Reference Manual 37/761007 Servers temporarily unavailable1008 Session timeout1009 Internal Server Error4.3 User-level Fault CodesCode Message1101 Unknown/missing parameter (required, wrong parameter)1102 Bad size1103 Not unique (This parameter already exists in the system)1104 Syntax error (For example: not valid email, url)1105 Invalid partner name or password1106 Invalid user name or password1107 Date error1108 Data conflict1109 Bad protocol id1110 Upgrade protocol1111 No data available1112 Unknown/missing report id1113 Report not supported1114 Maximum number of projects reached1115 Quota limit reached for this function1116 User or organization is not allowed to use this function.1117 Expired user1118 Renew password1119 User not active yet© 2000-2010 Yahoo! Inc. All rights reserved.
  38. 38. Yahoo! Web Analytics Web Services API Reference Manual 38/761120 No such order id in the specified date or the date is to early (<12 hours)1121 Invalid project ID1122 Invalid datasource ID1123 Project ID and datasource ID mismatch1124 Invalid/missing attachment4.4 Filter Fault CodesCode Message1121 Invalid Filter Type1122 Invalid Filter Operator1123 Invalid Filter ValueFor details about how to use filters, see sections 3.3.1 The ScheduleReportJobStandard Call and 3.3.2The ScheduleReportJobBookmark Call.© 2000-2010 Yahoo! Inc. All rights reserved.
  39. 39. Yahoo! Web Analytics Web Services API Reference Manual 39/765 Appendix A: Constants5.1 Campaign TypesId Note1 Banner Campaigns2 Email Campaigns3 CPC Search Engines5 Affiliate Program7 Other5.2 TimezonesId Note1 Dateline : Eniwetok, Kwajalein2 Samoa : Midway Island, Samoa3 Hawaiian : Hawaii4 Alaskan : Alaska5 Pacific : Pacific Time (U.S. & Canada)6 Mountain : Mountain Time (U.S. & Canada)7 U.S. Mountain : Arizona8 Canada Central : Saskatchewan9 Central : Central Time (U.S. & Canada)10 Mexico : Mexico City, Tegucigalpa11 Eastern : Eastern Time (U.S. & Canada)12 South Amercia Pacific : Bogota, Lima, Quito13 U.S. Eastern : Indiana (East)© 2000-2010 Yahoo! Inc. All rights reserved.
  40. 40. Yahoo! Web Analytics Web Services API Reference Manual 40/7614 Atlantic : Atlantic Time (Canada)15 W. South America : Caracas, La Paz16 Newfoundland : Newfoundland17 E. South America : Brasilia18 E. South America : Buenos Aires19 Mid-Atlantic : Mid-Atlantic20 Azores : Azores, Cape Verde Is.21 Greenwich Mean Time : Casablanca, Monrovia22 BST : Dublin, Lisbon, London23 Balkan : Sarajevo, Sofija, Zagreb24 Central Europe : Prague, Warsaw25 Romance : Brussels, Madrid, Paris26 W. Europe : Amsterdam, Berlin27 E. Europe : E. Europe28 Egypt : Cairo29 Finland : Helsinki30 GT : Athens, Istanbul31 Israel : Israel32 South Africa : Harare, Pretoria33 Russian : Moscow, St. Petersburg34 Saudi Arabia : Kuwait, Nairobi35 Iran : Tehran36 Arabian : Abu Dhabi, Muscat37 Tbilisi : Tbilisi38 Afghanistan : Kabul© 2000-2010 Yahoo! Inc. All rights reserved.
  41. 41. Yahoo! Web Analytics Web Services API Reference Manual 41/7639 Ekaterinburg : Ekaterinburg40 West Asia : Islamabad, Karachi41 India : Bombay, New Delhi42 loCentral Asia : Almaty, Dhakacation43 Colombo : Colombo44 Bangkok : Bangkok45 Hanoi : Hanoi46 Jakarta : Jakarta47 China : Beijing, Hong Kong, Urumqi48 Singapore : Singapore49 Taiwan : Taipei50 W. Australia : Perth51 Korea : Seoul52 Tokyo : Osaka, Sapporo, Tokyo53 Yakutsk : Yakutsk54 AUS Central : Darwin55 Central Australia : Adelaide56 E. Australia : Canberra, Sydney57 E. Australia : Brisbane58 Tasmania : Hobart59 Vladivostok : Vladivostok60 West Pacific : Guam, Port Moresby61 Central Pacific : Magadan, Sol. Is.62 Fiji : Fiji, Kamchatka, Marshall Is.63 New Zealand : Auckland, Wellington© 2000-2010 Yahoo! Inc. All rights reserved.
  42. 42. Yahoo! Web Analytics Web Services API Reference Manual 42/765.3 CPC EnginesEngine Id Name1 Overture US2 FindWhat3 Sprinks4 Kanoodle5 Ah-ha6 ePilot7 Overture UK8 eSpotting UK9 Overture DE10 eSpotting FR11 eSpotting DE12 eSpotting IT13 eSpotting ES14 Overture FR15 Overture JP16 Google Adwords17 Google Adwords Content18 Shopping.com19 BizRate.com20 PriceGrabber.com21 7Search22 SearchFeed23 RedZone Global© 2000-2010 Yahoo! Inc. All rights reserved.
  43. 43. Yahoo! Web Analytics Web Services API Reference Manual 43/7624 eSpotting DK25 eSpotting IE26 eSpotting NO27 eSpotting SE28 Overture AT29 Overture AU30 Overture CH31 Overture ES32 Overture FI33 Overture IT34 Overture NO35 Overture SE36 Overture DK37 Overture NL38 Mirago39 Nextag40 Overture US Local Match41 MySimon5.4 CurrenciesCurrency ID Currency30 AED13 AUD14 BGN12 BRL© 2000-2010 Yahoo! Inc. All rights reserved.
  44. 44. Yahoo! Web Analytics Web Services API Reference Manual 44/761 CAD15 CHF16 CNY39 CRC10 CZK31 DJF5 DKK17 EEK2 EUR3 GBP37 HKD18 HRK6 HUF40 ILS36 INR9 ISK32 JOD4 JPY19 KRW33 KWD20 LTL21 LVL34 MTL22 MXN7 NOK© 2000-2010 Yahoo! Inc. All rights reserved.

×