Enterprise Web Services - Yahoo! Search Marketing Enterprise Web Services

Introduction

The Marketing API enables you, as a developer, to build client software that interacts directly with the Yahoo! search marketplace. Use the Marketing API services, operations, and other components to send EWS requests and to handle EWS responses. EWS requests and EWS responses form the basis of your client applications (see Sample Code).

Note: Access to any service or operation is determined by your EWS license (see Access and Licensing).

Services

The Marketing API includes several services, each of which supports a particular product area. The Getting Started Guide places these services in their logical groups (see Service Descriptions and Details) and provides conceptual overviews that supplement the materials presented in the API reference (see Service Overviews).

Operations

Each service includes one or more operations. However, only one operation may be included in an EWS request. That is, each operation represents a single request to and response from EWS.

For EWS requests, an operation may or may not include parameters. If an operation does include parameters, you must specify a value for each parameter; that is, all parameters are required and must be included in the EWS request. For certain parameters, you may pass in the null value or the null string.

For EWS responses, an operation may or may not return data. If an operation does not return data, the response simply states "none." Please note that response "none" does not mean that no response is returned; rather, it means that the response returns an empty response element that does not include data.

Read operations include the "get" operations or any operation that retrieves but does not change the value of an object. Write operations include the "add", "copy", "delete", "move", "set", and "update" operations or any operation that modifies the value of an object.

List-based operations, for example, getAccounts as opposed to getAccount, allow you to read or write multiple objects (see List-Based Operations for EWS resquests and List-Based Operations for EWS responses. From a programming or network standpoint, list-based operations may be more efficient; however, make sure you understand how quota is tracked for both list-based and non-list-based operations (see Quotas).

All operations belong to license command groups and have assigned capabilities; and, as stated earlier, access to any service or operation is determined by your EWS license (see Command Groups and Capabilities).

Data Objects

Data objects are complex data types composed of complex or simple data types. Data objects form the elements of an operation.

Constants

Constants are valid EWS values for markets, credit cards, time zones, and other data elements.

Note: The names of services, operations, data objects, and constants are case sensitive.

Restrictions

Restrictions apply to some data objects and define how an element is used with add and update operations. We use the following notations in the Marketing API:

For operations: Add (Add), Full Update (Full-Up), Partial Update (Part-Up).
For values: Required (Req), Read-Only (RO), Optional (Opt).

Add Operations

Add operations work this way:

Required elements must be specified.
Read-Only elements cannot be changed and will be ignored if specified.
Optional elements may or may not be specified. This is your choice.

Full Update Operations

Full Update operations work this way:

Required elements must be specified.
Read-Only elements cannot be changed and will be ignored if specified.
Optional elements may or may not be specified. This is your choice. If you pass in the null value or omit the element, the current value is cleared.

Partial Update Operations

Partial Update operations work this way:

Required elements must be specified.
Read-Only elements cannot be changed and will be ignored if specified.
Optional elements may or may not be specified (it is your choice). If you pass in the null value or omit the element, the current value is not changed.

Valid Characters for Text Elements

User-settable text elements such as account and campaign names or keyword text, string datatypes, may include any character, with the following exceptions:

HTML is not allowed.
Javascript is not allowed.
Content contained within <script> tags is not allowed.
The escape sequence & is allowed for entering the ampersand (&) character. All other escape sequences are not allowed.
For ads, the title, long description, and short description elements cannot contain contact information such as phone numbers.

Also, Microsoft Windows® special characters (Windows 1252) will be replaced by equivalent unicode characters. See Microsoft's Global Development and Computing Portal.

Time Zones

The Marketing API accepts and returns dates and times in xsd:dateTime format as specified by the XML Schema specification http://www.w3.org/TR/xmlschema-2/#dateTime. All dateTime values returned by EWS will include the UTC time zone offset.

In most cases, the SOAP toolkit on the client side takes care of the translation of a dateTime value into the native language representation. It is important to remember to do a proper time zone conversion when displaying dates and times on the client side. Most technologies will default to the time zone of the server the code is running on. Some technologies also allow you to specify the desired time zone. See Sample Code.

If your accounts reside in the same time zone as the servers that are running the code, in most cases you should not have to explicitly convert dateTime values. If your accounts reside in a time zone that is different from the time zone of the servers running the code, you will need to explicitly convert dateTime values to the desired time zone. See Sample Code.

.NET

.NET does not have the capability to translate dateTime values into an arbitrary time zone. If you are using .NET, we suggest you follow these guidelines:

If your accounts reside in the same time zone as the servers that are running the code, you do not need to modify your code.
If you operate in a limited set of time zones, you can get around the .NET limitation by hardcoding UTC offsets and converting to and from the local time zone.
If you need to convert to arbitrary time zones, you will need to figure out a way to find UTC offsets for the time zones you are working with.