Yahoo Web Analytics API Reference Guide

WEB ANALYTICS

Web Services
API Reference Manual
June 30, 2010

Yahoo! Web Analytics Web Services API Reference Manual 2/76

Table of Contents
1 REVISION HISTORY..................................................................................................................... 5
2 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 ...............................................................................................................9
3 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.5.2 The getEdsJobStatus Call ...............................................................................................35
4 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 .................................................................................................................38
5 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.......................................................................................................................59
6 APPENDIX B: FILTERS .............................................................................................................. 60
7 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



Table of Figures
Figure 3 Structure of the updateCampaign Call Response................................................................... 18
Figure 4 Structure of the XML Report.................................................................................................... 29



1 Revision History
Date 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 support
Jun 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 added
April 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 changed
July 2005 1.2
SOAP Implementation



New features : getEditions call, getScenarios call,
July 2005 1.15
getReports call, new reports

June 2005 1.14 Fault Codes updated

February 2005 1.13 time zone identifiers changed

February 2005 1.12 getReport Call XML_RPC Example corrections

January 2005 1.11 Additional error codes

XML-RPC compliance added; Report retrieval methods
January 2005 1.1
added

December 2004 1.0 Initial revision



2 Overview
The Yahoo! Web Analytics API documentation provides the information necessary to access the
Yahoo! 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 Entities
You can use the Yahoo! Web Analytics API to access and change the following entity types:

Entity Notes

account Basic entity, parent of all.

Account’s child entity. One account may have many users with different user
user 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 created
project
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. Project's child entity. One project may have many
campaign
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 project's edition.

Report settings' action filter. Project’s child entity. One project may have many
action
actions.

The list of supported entities may change in the future. Some of the entities may not be accessible to a
particular user, partner, or during a particular login session, depending on the organization’s and
user’s permissions.

2.2 Supported Operations
Operation Description

login Start a session.

logout Finish a session.

createAccount Create an account (including a user and a project).



createProject 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 to
approveOrder
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 API
Each API call is initiated by a request from a client and has a response from the server. API calls are
never initiated from the server to the client. Each API call has a method name, which is one of the
operations described in section 2.2 Supported Operations.

2.4 XML-RPC Implementation
Former versions of the API supported the XML-RPC protocol. The current version (and future
versions) of the API supports only the SOAP protocol.



2.5 SOAP Implementation
The Yahoo! Web Analytics API allows you to encode your calls using the Simple Object Access
Protocol (SOAP). SOAP is an XML-based protocol for exchanging information. See
www.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 this
document.
See the Yahoo! Web Analytics WSDL at
https://reports.web.analytics.yahoo.com/api/IndexToolsApiV3.wsdl

NOTE!
If you have become a customer of IndexTools before May 2008, you need to use the below temporary
URL until the migration to the new Yahoo! data center has been successfully completed:
https://reportx.web.analytics.yahoo.com/api/IndexToolsApiV3.wsdl

You 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 in
the WSDL schema.



3 Yahoo! Web Analytics API Calls

3.1 Initialization
An 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 session
must be closed using the logout call.

3.1.1 The login Call
Each user of the API can find their own API token by logging into their analytics account and
navigating to Settings - Yahoo! Web Analytics API - YWA API Credentials. On the following screen, the
API 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/IndexToolsApiV3
Subsequent 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 temporary
URL until the migration to the new Yahoo! data center has been successfully completed:
https://apix.web.analytics.yahoo.com/IndexTools/services/IndexToolsApiV3

When 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 the
HTTP.
Sample:
POST /api HTTP/1.1
Host: HOST:PORT
Connection: Keep-Alive
YWA_API_TOKEN: YOUR_API_TOKEN
User-Agent: PHP-SOAP/5.2.0-8+etch7
Content-Type: text/xml; charset=utf-8
SOAPAction: "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</U
serId><UserPassword>USER_PASSWORD</UserPassword><IsSecure>false</IsSecure></ns1:Logi
n></SOAP-ENV:Body></SOAP-ENV:Envelope>

The login call takes an API Partner ID and password (note the API Partner ID and password are
different from the Yahoo! Web Analytics partner id and password in the user interface), an optional
User ID and password, and validates them.

The login request requires the following fields (the fields in bold are mandatory):



Name Format Description

partner_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, the
user_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 an
secure 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 partner
session will be created and only the createAccount operation will be allowed. If both the partner and
user login information are supplied, a user session will be created with non-restricted privileges.
The login call returns the following parameters:


session_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 to
server_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 Call
The 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 projects
to an account and add new campaigns to a project.

3.1.3 The createAccount Call
The 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 call
should be executed first. The execution of this call requires a successful partner login. After the



successful 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):


Specify the desired user id. Use this id to reference the user
user_id Max. 32 chars
during login in the future.

user_password Max. 32 chars Specify the desired user password.

Max. 128
email Specify a valid e-mail address.
chars

firstname 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. 256
base_url Project’s root URL e.g., www.abc.com
chars

project_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 possible
edition_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:


account_id Digits Numeric identifier of the account.



Numeric identifier of the project. Use this id to reference the
project_id Digits
project in the future.

See section 7.4 createAccount Call SOAP Example.

3.1.4 The createCampaign Call
The createCampaign call creates a new campaign entity within the project.
The createCampaign request requires the following fields (the fields in bold are mandatory):


project_id Digits Numeric identifier of the project.

Identify campaign type. See section 5.1
campaign_type Digits
Campaign Types.

Max.
campaign_name 64
chars

campaign_start YYYY-MM-DD

campaign_end YYYY-MM-DD

Max.
campaign_desc 256 Campaign description.
chars

status SHOW | HIDE

Max. url | referrer | parameter (These are the
parameter 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
chars

currency Digits See section 5.4 Currencies. Default: USD

Max. 8 FREE | FIXED | CPC | CPA| PPC|
cost_type
chars PPC_AUTOSETUP

action_id Digits Specify action id. (Required for CPA)



fix_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 or
Engine_Properties/Username 64
PPC_AUTOSETUP only.)
chars

Max.
Specify CPC password. (Required for PPC or
Engine_Properties/Password 64
chars

Max.
Specify Engine account id. (Required for PPC or
Engine_Properties/Overture_Account_Id 64
chars

Possible to use at banner campaign (number of
quantity Digits impression) and email campaign (number of
emails)

Max.
Specify URL parameter that contains the search
Engine_Properties/Listing 32
listing variable. E.g. listing, kw or OVKEY
chars

Max. 8 on | off (Overture autobid function). (Required for
Engine_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).

Max
64
chars

Max
64
chars

Max
64
chars

Max
64
chars



Max
64
chars

Max
64
chars

Max
64
chars

Campaign_Category10 Max
64 Specify the value of Campaign Category 10.
chars

The createCampaign call returns the following parameters:


Numeric identifier of the campaign. Use this id to reference
campaign_id Digits
the campaign in the future.

See section 7.5 createCampaign Call SOAP Example.

3.1.5 The createProject Call
The createProject call creates an additional project entity within the account. Please note than an initial
project is being generated during the createAccount operation, therefore this call is only required if
more than one projects is required.
The createProject request requires the following fields (the fields in bold are mandatory):


Max. 256
base_url Project’s root URL e.g., www.abc.com.
chars

project_name Max. 64 chars Project’s user-friendly name


You can retrieve your available editions with the getEditions
edition_id Max. 8 chars
call, see section 3.2.4 The getEditions Call.

default_currency Digits See section 5.4 Currencies. Default: USD



The createProject call returns the following parameters:


Numeric identifier of the project. Use this id to reference the
project_id Digits
project in the future.

See section 7.6 createProject Call SOAP Example.

3.1.6 The updateCampaign Call
The updateCampaign call allows you to update your campaign settings.
The updateCampaign request requires the following fields (the fields in bold are mandatory):


ProjectId Integer Numeric identifier of the project.

Campaign Structure

Campaign_Category2
Max 64 chars Modify the value of Campaign Category 2.

Campaign_Category3

Campaign_Category4

Campaign_Category5

Campaign_Category6

Campaign_Category7

Campaign_Category8

Campaign_Category9

Campaign_Category10

The Campaign structure contains the following parameters:




Id Digits Unique numeric identifier of the campaign.

Name Max. 64 chars The campaign name.

Max. 256
Description 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 the
State
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 shows
Quantity 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.



Figure 1 Structure of the updateCampaign Call Response



3.2 Account Information
These operations primarily help you to perform other operations in the API, e.g., in order to retrieve a
bookmarked report from the system, you need to download first the list of bookmarks; in order to filter
on specific campaigns, you need to retrieve the list of campaigns from the system.

3.2.1 The getActions Call
The 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):



The getActions call returns an array including the following fields:


action_id Digits Numeric identifier of the action.

Name of the corresponding action. Note that the action id 01
action_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 Call
The getBookmarks call returns all available bookmarks for a project.
The getBookmarks request requires the following field (the field in bold is mandatory):



The getBookmarks call returns an array including the following fields:


id Digits Numeric identifier of the bookmark.

name String Bookmark name.

description String Bookmark’s description.



report_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 Call
The getCampaigns call returns all active campaigns of a project.
The getCampaigns request requires the following the following field (the field in bold is mandatory):



The getCampaigns call returns an array including the following parameters:


campaign_type Digits Identify campaign type. See section 5.1 Campaign Types.

campaign_id Digits Numeric identifier of the campaign.

campaign_name Max. 64 chars

campaign_start DateTime

campaign_end DateTime

Max. 256
campaign_desc Campaign description
chars

created_date DateTime Date when campaign was created

status SHOW | HIDE

parameter Max. 32 chars url | referrer

operator Max. 16 chars equals | contains

Max. 256
condition e.g., source=google
chars



currency Digits See section 5.4 Currencies. Default: USD

cost_type Max. 8 chars FREE | FIXED | CPC | CPA| PPC| PPC_AUTOSETUP

action_id Digits Specify action id. (Required for CPA)

fix_cost Digits Specify fixed CPC cost if applicable, e.g., 0.15

Max. 255
cpc_engine_name Specify CPC engine name
chars

Numeric identifier of the CPC engine. See section 5.3 CPC
cpc_engine_id Digits
Engines. (Required for RTCR only.)

Specify CPC user name. (Required for PPC or
cpc_username Max. 64 chars

Specify CPC password. (Required for PPC or
cpc_password Max. 64 chars

Specify Overture account id. (Required for PPC or
engine_account_id Max. 64 chars

Possible to use at banner campaign (number of impression)
quantity Digits
and email campaign (number of emails)

Specify URL parameter that contains the search listing
cpc_listing Max. 32 chars
variable. E.g. listing, kw or OVKEY

on | off (Overture autobid function). (Required for PPC or
cpc_autobid Max. 8 chars

See section 7.8 getCampaigns Call SOAP Example.

3.2.4 The getEditions Call
The getEditions call returns all available editions to create new project. The getEditions request does
not require any arguments.
The getEditions call returns an array including the following fields (the fields in bold are mandatory):


edition_id Digits Numeric identifier of the edition

name String Name of the edition

description String Description of the edition

See section 7.9 getEditions Call SOAP Example



3.2.5 The getProjects Call
The getProjects call returns all active projects of an account. The getProjects request does not require
any arguments beyond the basic set.
The getProjects call returns an array including the following fields (the fields in bold are mandatory):



project_name Max. 64 chars Project’s user-friendly name

Max. 256
base_url Project’s root URL e.g., www.abc.com
chars


first_record_date Date Date of first time a hit was recorded in the project.

edition_id Max. 8 chars Project’s edition id

default_currency Digits See section 5.4 Currencies.

See section 7.10 getProjects Call SOAP Example.

3.2.6 The getReports Call
The getReports call returns all available reports of a project.

The getReports request requires the following field (the field in bold is mandatory):



The getReports call returns an array including the following parameters:


report_id ReportId Numeric identifier of the report.

name String Name of the report.

description String Report description.

help String Report help.



limitNeed 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 used
actionNeed Digits
1 : optional
2 : required

Available values:
0 : not used
campaignNeed Digits
1 : optional
2 : required

See section 7.13 getReports Call SOAP Example.

3.2.7 The getScenarios Call
The getScenarios call returns all useable scenarios of a project.
The getScenarios request requires the following field (the field in bold is mandatory):



The getScenarios call returns an array including the following parameters:


scenario_id Digits Numeric identifier of the scenario

name String Name of the scenario

description String Description of the scenario

See section 7.14 getScenarios Call SOAP Example.

3.2.8 The getTrackingCode Call
The 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):





Specify whether secure or non-secure tracking code should
transfer_protocol Digits
be retrieved. 0 (HTTP), 1 (HTTPS)

Max. 256 Specify exact location of the JS file if different from the root
trackingjs_location
Chars directory of the server. Default “base_url/indextools.js”

Optional custom variable. See Yahoo! Web Analytics
document_name Max. 32 Chars
Installation Guide.

document_group Max. 32 Chars
Installation Guide.

domains Max. 32 Chars
Installation Guide.

member_id Max. 32 Chars
Installation Guide.

action_id Max. 2 Chars
Installation Guide.

amount Max. 32 Chars
Installation Guide.

The getTrackingCode call returns the following parameters:


tracking_code String HTML tracking code to be inserted into the page.

Max. 256 Download URL of the indextools.js file to be uploaded to the
trackingjs
Chars web site. Note that this file is project specific.

See section 7.15 getTrackingCode Call SOAP Example.

3.3 Reporting
The Reporting call provides operations for getting analytical reports from your Yahoo! Web Analytics
account. The reports are in XML format.
To retrieve reports from the system:
1. Initialize your API session
Send a ScheduleReportJobStandard or ScheduleReportJobBookmark request. The response is the
reportJobId for the scheduled report job.



Get 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 for
the report. The returned URL is valid for 5 minutes. If you need to obtain another URL, simply send
another getReportJob request. Make sure you keep the returned URL confidential since it allows
access to the report without the need to login.
Download the report by sending an HTTP GET request to the download URL using any HTTP client
library.
NOTE:
If you select a user-specific time zone in the user interface, which is different from the project default
time zone, the reports you access via the API will also be adjusted to a user-specific time zone.

3.3.1 The ScheduleReportJobStandard Call
The ScheduleReportJobStandard call returns statistical data for a project.
The ScheduleReportJobStandard request requires the following fields (the fields in bold are
mandatory):



Date Beginning of the reporting period e.g., 2006-04-01. Note that
start_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 dates
end_date
iso8601 must be entered in the year-month-day format.

Use the getReports() call to get the available report ids of the
report_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 for
action_id Digits
conversion reports.

Numeric campaign identifier. This parameter is only needed for
campaign_id Digits
generating campaign details and campaign conversion reports.

Use getScenarios() call to get the available scenario ids of the
scenario_id Digits
selected project.

Session identifier. This parameter is only needed for the session
session_id 10 Chars
path report.



Specifies the sort value of the columns, i.e., 0 means the first
sort 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 the
show_description Boolean
response.

Filters Structure For details see the table below.

The Filters parameter requires the following fields (the fields in bold are mandatory):


Indicates the Type ID of the filter. For a complete list of the filter
Type 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 Browser
Value 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:


The ID of the report job to be used in subsequent
ReportJobId Long
getReportJob calls.

See section 7.11 ScheduleReportJobStandard Call SOAP Example.



When using filters, the ScheduleReportJobStandard call can return the exceptions listed under section
4.4 Filter Fault Codes.

3.3.2 The ScheduleReportJobBookmark Call
The ScheduleReportJobBookmark call returns statistical data for a project.
The ScheduleReportJobBookmark request requires the following fields (the fields in bold are
mandatory):


Numeric identifier of the bookmark. Use getBookmarks() call
BookmarkId Digits
to get the available bookmark ids of the selected project.

Beginning of the reporting period. This parameter is used
StartDate Date iso8601 only if the selected bookmark’s use_saved_period setting =
false.

End of the reporting period. This parameter is used only if
EndDate 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):


Indicates the Type ID of the filter. For a complete list of the filter
Type 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 Browser
Value 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:


The ID of the report job to be used in subsequent
ReportJobId Long
getReportJob calls.

When using filters, the ScheduleReportJobBookmark call can return the exceptions listed under
section 4.4 Filter Fault Codes.

3.3.3 The getReportJob Call
Thes getReportJob call is used to get the status of the report job. The status is Completed, Pending or
Failed. 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 another
getReportJob request. Make sure you keep the returned URL confidential since it allows access to the
report without the need to login.

The getReportJob call requires the following fields (the fields in bold are mandatory):


The ID returned by prior ScheduleReportJobStandard or
ReportJobId 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:


ReportJobStatus ReportJobStatus Completed, InProgress, Pending, Expired or Failed.

ReportJobURL String Temporary download URL for the report.



3.3.4 Report XML Format
The following diagram illustrates the structure of the XML report generated by the
ScheduleReportJobStandard or ScheduleReportJobBookmark calls.

Figure 2 Structure of the XML Report

A simplified description of the XML report structure is the following:

TagName Type Description

Title String Report title.



Description String Report description.

Help String Report help.

Indicates whether the result includes more data to follow. If the
HasMoreRows 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 the
TotalCells 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 Description

Value String This shows data values in raw format. E.g. 35000.

This shows formatted data values, i.e., as they appear on the
FormattedValue String
user interface. E.g. 35,000.

This shows the type of data. Values are : Text, Int, Float,
Type DataType
Currency, Percent

3.4 Order Reconciliation

3.4.1 The approveOrder Call
The approveOrder call changes the status of a previously recorded pending sale action to an approved
sale. This feature allows you to update your reports with your successful sales, without having to worry
about aborted sales showing in your sales summary.
The approveOrder request requires the following arguments:




ProjectId 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.2
Amount 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 the
request 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 within
a 3 day period from the date when the pending sale was first registered.

3.4.2 The changeOrder Call
The changeOrder call changes the order’s (sale action) amount or currency.
The changeOrder request requires the following fields (the fields in bold are mandatory):





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



3.4.3 The cancelOrder Call
The cancelOrder call deletes an order that was previously recorded in the system. The cancelOrder
request requires the following fields (the fields in bold are mandatory):





If the method execution was not successful, an exception will be thrown.

3.4.4 The changeOrderList Call
To use the Bulk Order Change:
Create a ChangeOrderListRequest with the list of modified orders. In the request all the projects must
be the same, otherwise you will get an error message. However, you can include different commands
on the same project in a single request. Send this request to the server, and you will receive the JobId
of 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 of
the arguments listed below (If you use the Change command, you have to set either the amount or the
currency):
The fields in bold are mandatory.


Command Approve | Cancel | Change



Order’s creation date. The date must be within a 3 day
Date Date
range. It must be older than 12 hours.



Amount 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:


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 Call
With 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):


JobId Digits Unique identifier assigned to each changeOrderList call.

The getChangeOrderListStatus call returns the following parameter:


Status Digits PENDING | DONE | DONEWITHERROR (see section 3.4.4).

3.4.6 The getChangeOrderListErrors Call
With the getChangeOrderListErrors call, you can check the list of errors that resulted from trying to
complete the request.
The getChangeOrderListErrors request requires the following field (the field in bold is mandatory):


JobId Digits Unique identifier assigned to each changeOrderList call.

The getChangeOrderListErrors call returns the following list of error parameters:




Command APPROVE | CHANGE | CANCEL



Order’s creation date. The date must be within a 3 day
Date 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 Sources
External Data Sources (EDS) is an integration feature available in the Yahoo! Web Analytics 10
Enterprise Edition, which allows you to merge data originating from external sources, such as
campaign management systems, email systems, or other internal systems with your web analytics
reporting.
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 take
advantage of the Beta version of the EDS feature (before the release of Yahoo! Web Analytics 10), our
Professional Services team will be able to help you depending on your requirements.

3.5.1 The uploadEdsFile Call
With the uploadEdsFile call, you can upload a file to our system.
The uploadEdsFile request requires the following fields (the fields in bold are mandatory):


fileName String Name of the uploaded file.

projectId Digits Numeric project ID.

Numeric ID of the EDS Data source provided by Yahoo! Web
datasourceId Digits
Analytics Professional Services

Possible values: "replace" or "append": "replace" removes
uploadMode 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!



The uploadEdsFile call returns the following parameter:


edsJobId 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 the
datasourceID match, and the attachment is present), the attached file will be saved, and an ID will be
given 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 processing
the content and completes the EDS job. After completing the job, the EDS daemon sets the status of
the job to COMPLETED or FAILED.
Typically, uploading the EDS file takes 1-2 minutes; however, depending on the size of the file, the
uploading process can take up to 30 minutes.

3.5.2 The getEdsJobStatus Call
With 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):


Numeric ID of the started EDS job, retrieved as the
edsJobId Digits
uploadEdsFile call's 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:

Status of the EDS job identified by the edsJobId; possible
status 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, the
errorList 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.



4 Fault Codes
Yahoo! Web Analytics API requests can return a successful response or a fault response. A fault
response indicates that the request could not be completed. A fault response is composed of an error
code and a text message. The fault message is a short description in English that can be displayed to
the user as a minimally descriptive error message. If you display the fault message, you should also
display the fault code. Clients should always recognize the fault codes, not the fault messages. The
actual 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 on
any call, such as error code 1000 for a null parameter list. Each subsection lists fault codes that
commonly occur with a particular call. However, the fault codes listed for a particular call could occur
with any other call as well.
Beyond the fault codes, clients should also check that the response Content-Type in the HTTP header
is .text/xml. Any other type, such as .text/html, indicates that the application server is down or
unreachable, such as being blocked by a firewall.
See section 7.1 SOAP Fault Code Example.

4.1 HTTP, XML Level Fault Codes
Fault codes 0 and -1 are used for general faults.

Code Message

Invalid XML or XML-RPC syntax. Usually indicates a development error on the
0 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 Codes
Code Message

1001 Session ID required in cookie for non-login request

1002 Invalid Content-Encoding

1003 API currently disabled

1004 API not enabled for this user or organization

User or organization is not allowed to use the API during this time period, or has
1005
exceeded its API quota for this time period.

User or organization has exceeded rate limit. Sleep and try again in ’X’ ms
1006 (where ’X’ is an integer listed at the beginning of the text message and followed
by „ms delay:”)



1007 Servers temporarily unavailable

1008 Session timeout

1009 Internal Server Error

4.3 User-level Fault Codes
Code Message

1101 Unknown/missing parameter (required, wrong parameter)

1102 Bad size

1103 Not unique (This parameter already exists in the system)

1104 Syntax error (For example: not valid email, url)

1105 Invalid partner name or password

1106 Invalid user name or password

1107 Date error

1108 Data conflict

1109 Bad protocol id

1110 Upgrade protocol

1111 No data available

1112 Unknown/missing report id

1113 Report not supported

1114 Maximum number of projects reached

1115 Quota limit reached for this function

1116 User or organization is not allowed to use this function.

1117 Expired user

1118 Renew password

1119 User not active yet



1120 No such order id in the specified date or the date is to early (<12 hours)

1121 Invalid project ID

1122 Invalid datasource ID

1123 Project ID and datasource ID mismatch

1124 Invalid/missing attachment

4.4 Filter Fault Codes
Code Message

1121 Invalid Filter Type

1122 Invalid Filter Operator

1123 Invalid Filter Value

For details about how to use filters, see sections 3.3.1 The ScheduleReportJobStandard Call and 3.3.2
The ScheduleReportJobBookmark Call.



5 Appendix A: Constants

5.1 Campaign Types
Id Note

1 Banner Campaigns

2 Email Campaigns

3 CPC Search Engines

5 Affiliate Program

7 Other

5.2 Timezones
Id Note

1 Dateline : Eniwetok, Kwajalein

2 Samoa : Midway Island, Samoa

3 Hawaiian : Hawaii

4 Alaskan : Alaska

5 Pacific : Pacific Time (U.S. & Canada)

6 Mountain : Mountain Time (U.S. & Canada)

7 U.S. Mountain : Arizona

8 Canada Central : Saskatchewan

9 Central : Central Time (U.S. & Canada)

10 Mexico : Mexico City, Tegucigalpa

11 Eastern : Eastern Time (U.S. & Canada)

12 South Amercia Pacific : Bogota, Lima, Quito

13 U.S. Eastern : Indiana (East)



14 Atlantic : Atlantic Time (Canada)

15 W. South America : Caracas, La Paz

16 Newfoundland : Newfoundland

17 E. South America : Brasilia

18 E. South America : Buenos Aires

19 Mid-Atlantic : Mid-Atlantic

20 Azores : Azores, Cape Verde Is.

21 Greenwich Mean Time : Casablanca, Monrovia

22 BST : Dublin, Lisbon, London

23 Balkan : Sarajevo, Sofija, Zagreb

24 Central Europe : Prague, Warsaw

25 Romance : Brussels, Madrid, Paris

26 W. Europe : Amsterdam, Berlin

27 E. Europe : E. Europe

28 Egypt : Cairo

29 Finland : Helsinki

30 GT : Athens, Istanbul

31 Israel : Israel

32 South Africa : Harare, Pretoria

33 Russian : Moscow, St. Petersburg

34 Saudi Arabia : Kuwait, Nairobi

35 Iran : Tehran

36 Arabian : Abu Dhabi, Muscat

37 Tbilisi : Tbilisi

38 Afghanistan : Kabul



39 Ekaterinburg : Ekaterinburg

40 West Asia : Islamabad, Karachi

41 India : Bombay, New Delhi

42 loCentral Asia : Almaty, Dhakacation

43 Colombo : Colombo

44 Bangkok : Bangkok

45 Hanoi : Hanoi

46 Jakarta : Jakarta

47 China : Beijing, Hong Kong, Urumqi

48 Singapore : Singapore

49 Taiwan : Taipei

50 W. Australia : Perth

51 Korea : Seoul

52 Tokyo : Osaka, Sapporo, Tokyo

53 Yakutsk : Yakutsk

54 AUS Central : Darwin

55 Central Australia : Adelaide

56 E. Australia : Canberra, Sydney

57 E. Australia : Brisbane

58 Tasmania : Hobart

59 Vladivostok : Vladivostok

60 West Pacific : Guam, Port Moresby

61 Central Pacific : Magadan, Sol. Is.

62 Fiji : Fiji, Kamchatka, Marshall Is.

63 New Zealand : Auckland, Wellington



5.3 CPC Engines
Engine Id Name

1 Overture US

2 FindWhat

3 Sprinks

4 Kanoodle

5 Ah-ha

6 ePilot

7 Overture UK

8 eSpotting UK

9 Overture DE

10 eSpotting FR

11 eSpotting DE

12 eSpotting IT

13 eSpotting ES

14 Overture FR

15 Overture JP

16 Google Adwords

17 Google Adwords Content

18 Shopping.com

19 BizRate.com

20 PriceGrabber.com

21 7Search

22 SearchFeed

23 RedZone Global



24 eSpotting DK

25 eSpotting IE

26 eSpotting NO

27 eSpotting SE

28 Overture AT

29 Overture AU

30 Overture CH

31 Overture ES

32 Overture FI

33 Overture IT

34 Overture NO

35 Overture SE

36 Overture DK

37 Overture NL

38 Mirago

39 Nextag

40 Overture US Local Match

41 MySimon

5.4 Currencies
Currency ID Currency

30 AED

13 AUD

14 BGN

12 BRL



1 CAD

15 CHF

16 CNY

39 CRC

10 CZK

31 DJF

5 DKK

17 EEK

2 EUR

3 GBP

37 HKD

18 HRK

6 HUF

40 ILS

36 INR

9 ISK

32 JOD

4 JPY

19 KRW

33 KWD

20 LTL

21 LVL

34 MTL

22 MXN

7 NOK



23 NZD

24 PLN

25 RON

26 RSD

27 RUB

8 SEK

38 SGD

11 SKK

41 THB

28 TRY

29 UAH

0 USD

35 ZAR

5.5 Country Codes
Id Name

af Afghanistan

al Albania

dz Algeria

as American Samoa

ad Andorra

ao Angola

ai Anguilla

aq Antartica

ag Antigua and Barbuda



ar Argentina

am Armenia

aw Aruba

ac Ascension Island

au Australia

at Austria

az Azerbaijan

bs Bahamas

bh Bahrain

bd Bangladesh

bb Barbados

by Belarus

be Belgium

bz Belize

bj Benin

bm Bermuda

bt Bhutan

bo Bolivia

ba Bosnia and Herzegovina

bw Botswana

bv Bouvet Island

br Brazil

io British Indian Ocean Territory

bn Brunei Darussalam

bg Bulgaria


Yahoo Web Analytics API Reference Guide

Yahoo Web Analytics API Reference Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Yahoo Web Analytics API Reference Guide

Similar to Yahoo Web Analytics API Reference Guide (20)

Yahoo Web Analytics API Reference Guide