YSM Technology Solutions Portal

Introduction

To enhance performance, Yahoo! Search Marketing accounts are distributed across various colocations. When you sign up with Y!SM, your master account, and all master accounts you subsequently create, are assigned to one of these colocations.

When you send an EWS request, you must include the URL that identifies the colocation your master account is assigned to. This URL, referred to as a local URL, is formed by combining a URL prefix with the the current version and the service name.

Process

To form a local URL:

First, send a request to the LocationService to retrieve the URL prefix for the colocation your master account is assigned to.
Next, combine the URL prefix with the current version and the service name to form a complete, local URL (URL prefix / version / service).
Then, send a request to the named service using the local URL.

Note: When you send a request to the LocationService, you do not use a local URL. Rather, you use the URL located in the LocationService WSDL file (sandbox, production).

Once you have the URL prefix, you can use it to create multiple local URLs for multiple service requests.

Example

Suppose, for a specific master account, you want to send requests to the CampaignService and the AdGroupService. Your client application would need to perform the following tasks:

Create and send a request to the LocationService using the URL located in the LocationService WSDL file. Process the response and retrieve the URL prefix for the colocation the master account is assigned to.
Use the URL prefix to form a local URL (URL prefix / version / CampaignService). Create and send the request to the CampaignService using the local URL. Process the response.
Use the URL prefix to form a local URL (URL prefix / version / AdGroupService). Create and send the request to the AdGroupService using the local URL. Process the response.

Summary

To summarize:

To send a request to the LocationService, use the URL located in the LocationService WSDL file.
To send a request to all other services, use the local URL. To form the local URL, send a request to the LocationService to retrieve the URL prefix for the colocation your master account is assigned to. Then, combine the URL prefix with the current version and the relevant service name to form a local URL.

LocationService

Use the LocationService to return the URL prefix for the colocation your master account is assigned to. Once you have the URL prefix, you can use it to form the local URL.

LocationService Request

The LocationService has one operation, getMasterAccountLocation. In the request, enter your credentials and master account ID. Post the request using the URL located in the LocationService WSDL file: "https://global.marketing.ews.yahooapis.com/services/V4/LocationService".

See EWS Requests for more information.

   POST
      https://global.marketing.ews.yahooapis.com/services/V4/LocationService
	     HTTP/1.0
   Content-Type: text/xml; charset=utf-8
   Content-Length: 987

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V4">

      <soapenv:Header>
         <wsse:Security>
           <wsse:UsernameToken>
             <wsse:Username>user</wsse:Username>
             <wsse:Password>password</wsse:Password>
           </wsse:UsernameToken>
         </wsse:Security>

         <license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
         <masterAccountID>9901672</masterAccountID>
      </soapenv:Header>

      <soapenv:Body>
         <getMasterAccountLocation/>
      </soapenv:Body>
   </soapenv:Envelope>

LocationService Response

The LocationService returns the URL prefix for the colocation your master account is assigned to. For example: "https://colo2.marketing.ews.yahooapis.com/services".

See EWS Responses for more information.

   <?xml version='1.0' encoding='UTF-8'?>

   <soap:Envelope
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      	xmlns="http://marketing.ews.yahooapis.com/V4">

         <soap:Header>
            <remainingQuota>9999974</remainingQuota>
            <commandGroup>Marketing</commandGroup>
            <timeTakenMillis>2813</timeTakenMillis>
         </soap:Header>

         <soap:Body>
            <getMasterAccountLocationResponse>
               <out>
                  https://colo2.marketing.ews.yahooapis.com/services
               </out>
	    </getMasterAccountLocationResponse>
         </soap:Body>
   </soap:Envelope>

Combine the URL prefix with the current version and the specific service name to form a local URL (URL prefix + version + service). For example:

To send a request to the CampaignService, the local URL would be
"https://colo2.marketing.ews.yahooapis.com/services/V4/CampaignService".
To send a request to the AdGroupService, the local URL would be
"https://colo2.marketing.ews.yahooapis.com/services/V4/AdGroupService".

Requests and HTTPS

EWS requests must be sent using the POST method over HTTPS. For more information about how to construct and send requests, see Hypertext Transfer Protocol.

Note: EWS does not require a value for the SOAPAction HTTP header. If your toolkit requires the use of this header you may leave it blank.

This example shows how to send an EWS request to the CampaignService. Notice that the request uses the local URL.


POST
   https://colo2.marketing.ews.yahooapis.com/services/V4/CampaignService
   HTTP/1.0
Content-Type: text/xml; charset=utf-8
Content-Length: 987

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V4">

      <soapenv:Header>
         <wsse:Security>
           <wsse:UsernameToken>
             <wsse:Username>user</wsse:Username>
             <wsse:Password>password</wsse:Password>
           </wsse:UsernameToken>
         </wsse:Security>

         <license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
         <masterAccountID>9901672</masterAccountID>
         <accountID>9901673</accountID>
      </soapenv:Header>

      <soapenv:Body>
         <getCampaigns>
            <campaignIDs>
               <long>5354501</long>
               <long>5355001</long>
            </campaignIDs>
         </getCampaigns>
      </soapenv:Body>
   </soapenv:Envelope>

Getting Started Guide: EWS Locations