Getting Started Guide: LocationService Overview

About Colocations

When you enroll with Yahoo! Search Marketing, your initial master account, and all subsequent master accounts that you create, are assigned to specific colocations.

When you send an EWS request using the POST method, you must include a 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 current version and the relevant service name (URL prefix / version / service).

You use the LocationService to retrieve the URL prefix and then combine the URL prefix with the current version and service name to form the local URL. You then use the local URL to send a request to the named service (see EWS Locations).

We recommend that you make regular queries to the LocationService, typically at the start of each session or whenever you switch master accounts. Doing so ensures that your requests are posted to a currently available server.

If a colocation is offline for maintenance or otherwise unavailable, your master account data will always be available at one or more alternate locations.

Account Movements

Occasionally, for issues such as load balancing, we may need to move your master account from one colocation to another. When an account movement is scheduled, we will notify your Technical Account Management Team. During the move, which may take a few hours, certain restrictions will apply to the master account and all accounts under that master account:

• During the first phase of the move, you can perform read operations (for example, getCampaign or getCampaigns) and non-list-based write operations (for example, addCampaign or updateCampaign), but you cannot perform list-based write operations (for example, addCampaigns or updateCampaigns).
• During the second phase of the move, you can perform read operations, but you cannot perform write operations.
• When the move is complete, you will need to send a request to the LocationService to retrieve the URL prefix for the new colocation (see below).

For more information on read, write, and list-based operations, see the Marketing API Reference.

Accounts in Preview Mode

If your accounts are in preview mode, use the UpgradeService rather than the LocationService (see the UpgradeService Overview).

Send a Request to the LocationService

The LocationService has one operation, getMasterAccountLocation. Use this operation to retrieve the URL prefix for the colocation the master account is assigned to.

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

Note: The UpgradeService and VaultService work in a similar fashion.

Send a Request to a Service

To send a request to a service (other than the LocationService, UpgradeService, or VaultService), do the following.

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 (using variable V4) and service name to form the local URL (URL prefix / version / service). Then, reference the local URL when you post the request (see Requests and HTTPS).

For example, suppose you want to post a request to the CampaignService. If the URL prefix returned by the LocationService is

"https://colo2.marketing.ews.yahooapis.com/services"

then the local URL would be

"https://colo2.marketing.ews.yahooapis.com/services/V4/CampaignService".