#!/usr/bin/python # # Copyright 2009 Google Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # """Methods to access SiteSuggestionService service.""" __author__ = 'api.sgrinberg@gmail.com (Stan Grinberg)' from aw_api import SanityCheck as glob_sanity_check from aw_api import SOAPPY from aw_api import ZSI from aw_api.Errors import ValidationError from aw_api.WebService import WebService class SiteSuggestionService(object): """Wrapper for SiteSuggestionService. The Site Suggestion Service provides operations for getting web site suggestions four different ways: by category, topics you define, URLs or demographics. """ def __init__(self, headers, config, op_config, lock, logger): """Inits SiteSuggestionService with authentication headers, configuration values, server, version, version, and HTTP proxy. Args: headers: dict dictionary object with populated authentication credentials. config: dict dictionary object with populated configuration values. op_config: dict dictionary object with additional configuration values for this operation. lock: thread.lock the thread lock. logger: Logger the instance of Logger """ url = [op_config['server'], 'api/adwords', op_config['version'], self.__class__.__name__] if config['access']: url.insert(len(url) - 1, config['access']) self.__service = WebService(headers, config, op_config, '/'.join(url), lock, logger) self.__config = config if self.__config['soap_lib'] == SOAPPY: from aw_api.soappy_toolkit import SanityCheck elif self.__config['soap_lib'] == ZSI: from aw_api import API_VERSIONS from aw_api.zsi_toolkit import SanityCheck if op_config['version'] in API_VERSIONS: module = '%s_services' % self.__class__.__name__ try: web_services = __import__('aw_api.zsi_toolkit.%s.%s' % (op_config['version'], module), globals(), locals(), ['']) except ImportError, e: # If one of library's required modules is missing, re raise exception. if str(e).find(module) < 0: raise ImportError(e) msg = ('The version \'%s\' is not compatible with \'%s\'.' % (op_config['version'], self.__class__.__name__)) raise ValidationError(msg) else: msg = 'Invalid API version, not one of %s.' % str(list(API_VERSIONS)) raise ValidationError(msg) self.__web_services = web_services self.__loc = eval('web_services.%sLocator()' % self.__class__.__name__) self.__sanity_check = SanityCheck def GetSitesByCategoryName(self, category_name, targeting): """Return site suggestions based on the specified category name. Args: category_name: str name of a category. targeting: dict language and geo targeting information. Ex: category_name = 'Software' targeting = { 'countries': ['US'], 'languages': ['en'], 'metros': ['501'], 'regions': ['US-NY'] } Returns: tuple response from the API method. """ glob_sanity_check.ValidateTypes(((category_name, (str, unicode)),)) self.__sanity_check.ValidateLanguageGeoTargetingV13(targeting) method_name = 'getSitesByCategoryName' if self.__config['soap_lib'] == SOAPPY: return self.__service.CallMethod(method_name, (category_name, targeting)) elif self.__config['soap_lib'] == ZSI: web_services = self.__web_services request = eval('web_services.%sRequest()' % method_name) return self.__service.CallMethod(method_name, (({'categoryName': category_name}, {'targeting': targeting})), 'SiteSuggestion', self.__loc, request) def GetSitesByDemographics(self, demo, targeting): """Return site suggestions based on the specified demographics criteria. Demographics criteria including gender, age, income, ethnicity and whether there are children in the household. Args: demo: dict demographics targeting criteria. targeting: dict language and geo targeting information. Ex: demo = { 'childrenTarget': 'HouseholdsWithChildrenOnly', 'ethnicityTarget': 'NoPreference', 'genderTarget': 'NoPreference', 'maxAgeRange': 'Range35To44', 'maxHouseholdIncomeRange': 'Range40000To59999', 'minAgeRange': 'Range18To24', 'minHouseholdIncomeRange': 'Range15000To24999' } targeting = { 'countries': ['US'], 'languages': ['en'], 'metros': ['501'], 'regions': ['US-NY'] } Returns: tuple response from the API method. """ self.__sanity_check.ValidateDemographicsTargetV13(demo) self.__sanity_check.ValidateLanguageGeoTargetingV13(targeting) method_name = 'getSitesByDemographics' if self.__config['soap_lib'] == SOAPPY: return self.__service.CallMethod(method_name, (demo, targeting)) elif self.__config['soap_lib'] == ZSI: web_services = self.__web_services request = eval('web_services.%sRequest()' % method_name) return self.__service.CallMethod(method_name, (({'demo': demo}, {'targeting': targeting})), 'SiteSuggestion', self.__loc, request) def GetSitesByTopics(self, topics, targeting): """Return site suggestions based on the specified topics. Args: topics: list list of keywords, each of which can be a word or phrase. targeting: dict language and geo targeting information. Ex: topics = ['Flowers'] targeting = { 'countries': ['US'], 'languages': ['en'], 'metros': ['501'], 'regions': ['US-NY'] } Returns: tuple response from the API method. """ glob_sanity_check.ValidateTypes(((topics, list),)) for item in topics: glob_sanity_check.ValidateTypes(((item, (str, unicode)),)) self.__sanity_check.ValidateLanguageGeoTargetingV13(targeting) method_name = 'getSitesByTopics' if self.__config['soap_lib'] == SOAPPY: return self.__service.CallMethod(method_name, (topics, targeting)) elif self.__config['soap_lib'] == ZSI: web_services = self.__web_services request = eval('web_services.%sRequest()' % method_name) return self.__service.CallMethod(method_name, (({'topics': topics}, {'targeting': targeting})), 'SiteSuggestion', self.__loc, request) def GetSitesByUrls(self, urls, targeting): """Return site suggestions based on the specified URLs. Args: urls: list list of seed URLs. targeting: dict language and geo targeting information. Ex: urls = ['www.google.com'] targeting = { 'countries': ['US'], 'languages': ['en'], 'metros': ['501'], 'regions': ['US-NY'] } Returns: tuple response from the API method. """ glob_sanity_check.ValidateTypes(((urls, list),)) for item in urls: glob_sanity_check.ValidateTypes(((item, (str, unicode)),)) self.__sanity_check.ValidateLanguageGeoTargetingV13(targeting) method_name = 'getSitesByUrls' if self.__config['soap_lib'] == SOAPPY: return self.__service.CallMethod(method_name, (urls, targeting)) elif self.__config['soap_lib'] == ZSI: web_services = self.__web_services request = eval('web_services.%sRequest()' % method_name) return self.__service.CallMethod(method_name, (({'urls': urls}, {'targeting': targeting})), 'SiteSuggestion', self.__loc, request)