django-google-adwords 0.7.2

Django modelling and helpers for the Google Adwords API.

Django modelling and helpers for the Google Adwords API.

Using Celery to process tasks in the background the provided models include methods to retrieve and store data for Accounts, Campaigns, Ad Groups and Ads to your database for further processing.

Currently Google Adwords API version v201506 is supported.

Installation

You can install django-google-adwords either via the Python Package Index (PyPI) or from github.

To install using pip;

pip install django-google-adwords

From github;

pip install git+https://github.com/alexhayes/django-google-adwords.git

Settings

django-google-adwords uses django-appconf to set default settings, of which there are quite a lot. Out of the box you only need to set the required settings however you will most likely want to change the Celery queues settings.

Required

You must place the following in your django settings file.

GOOGLEADWORDS_CLIENT_ID          = 'your-adwords-client-id'          # ie.. xyz123.apps.googleusercontent.com
GOOGLEADWORDS_CLIENT_SECRET      = 'your-adwords-client-secret'      # xyz123xyz123xyz123xyz123
GOOGLEADWORDS_REFRESH_TOKEN      = 'your-adwords-refresh-token'      # 1/xyz123xyz123xyz123xyz123xyz123xyz123xyz123x
GOOGLEADWORDS_DEVELOPER_TOKEN    = 'your-adwords-developer-token'    # 1234567890
GOOGLEADWORDS_CLIENT_CUSTOMER_ID = 'your-adwords-client-customer-id' # xyz123xyz123xyz123xyz1

If you don’t know these values already you’ll probably want to read the Google Adwords OAuth 2.0 Authentication documentation.

Other Settings

Other settings can be found in django_google_adwords.settings and can be overridden by putting them in your settings file prepended with GOOGLEADWORDS_.

Celery

Celery installation and configuration is somewhat out of the scope of this document but in order to sync Google Adwords data into models you will need a working Celery.

Essentially the syncing of data is a two step process, as follows;

1. Reports are downloaded from Adwords using the Celery queue specified in the setting GOOGLEADWORDS_REPORT_RETRIEVAL_CELERY_QUEUE. 2. Downloaded reports are processed using the Celery queue specified in the setting GOOGLEADWORDS_DATA_IMPORT_CELERY_QUEUE.

By default the above two settings, along with GOOGLEADWORDS_HOUSEKEEPING_CELERY_QUEUE are set to celery however you may want to spilt these up with different workers, as follows;

GOOGLEADWORDS_REPORT_RETRIEVAL_CELERY_QUEUE = 'adwords_retrieval'
GOOGLEADWORDS_DATA_IMPORT_CELERY_QUEUE = 'adwords_import'
GOOGLEADWORDS_HOUSEKEEPING_CELERY_QUEUE = 'adwords_housekeeping'

With the above you could run the following workers;

celery worker --app myapp --queues adwords_retrieval &
celery worker --app myapp --queues adwords_import &
celery worker --app myapp --queues adwords_housekeeping &

Usage

Storing local data

The provided models include methods to sync data from the Google Adwords API to the local models so that it can be queried at a later stage.

account_id = [YOUR GOOGLE ADWORDS ACCOUNT ID]
account = Account.objects.create(account_id=account_id)
result = account.sync() # returns a celery AsyncResult

Depending on the amount of data contained with your Adwords account the above could take quite some time to populate! Advice is to monitor the celery task.

You can control what data is sync’d with the following settings:

GOOGLEADWORDS_SYNC_ACCOUNT = True    # Sync account data
GOOGLEADWORDS_SYNC_CAMPAIGN = True   # Sync campaign data
GOOGLEADWORDS_SYNC_ADGROUP = True    # Sync adgroup data
GOOGLEADWORDS_SYNC_AD = False        # Sync ad data - note this can take a LOOOONNNNG time if you have lots of ads...

Once you have created an account or have multiple accounts, you can, using Celery Beat have the accounts sync’d at regular intervals by setting the CELERYBEAT_SCHEDULE similar to the following;

    from celery.schedules import crontab
CELERYBEAT_SCHEDULE = {
    'sync_google_adwords_data': {
        'task': 'django_google_adwords.tasks.sync_chain',
        'schedule': crontab(minute=5, hour=0),
    },
}

Paged data

To use the API but not store data in the models you can page through yielded data with the following;

selector = {
    'searchParameters': [
        {
            'xsi_type': 'RelatedToQuerySearchParameter',
            'queries': ['seo', 'adwords', 'adwords seo']
        },
        {
            'xsi_type': 'LanguageSearchParameter',
            'languages': [{'id': '1000'}]
        },
        {
            'xsi_type': 'LocationSearchParameter',
            'locations': [{'id': '2036'}]
        },
    ],
    'ideaType': 'KEYWORD',
    'requestType': 'IDEAS',
    'requestedAttributeTypes': ['KEYWORD_TEXT', 'SEARCH_VOLUME'],
}

for (data, selector) in paged_request('TargetingIdeaService', selector):
    print data

Google Adwords API Versions

The intention is to keep in sync with the latest available Google Adwords API versions - currently this is v201506

To do this it’s highly possible we’ll need to break backwards compatibility as the API can potentially do that.

Backwards Incompatibility Changes

v0.6.0

• Changed setting GOOGLEADWORDS_START_FINISH_CELERY_QUEUE to GOOGLEADWORDS_HOUSEKEEPING_CELERY_QUEUE.

• Removed Alert.sync_alerts(), Alert.get_selector() and task sync_alerts as the services that these functions call have been discontinued in the Google API. The Alert model remains in place so that existing alerts can be accessed if required.

v0.4.0

• Now using Django 1.7 migrations.

• Switched from money to djmoney (which itself uses py-moneyed).

Contributing

You are encouraged to contribute - please fork and submit pull requests. To get a development environment up you should be able to do the following;

git clone https://bitbucket.org/alexhayes/django-google-adwords.git
cd django-google-adwords
pip instal -r requirements/default.txt
pip instal -r requirements/test.txt
./runtests.py

And to run the full test suite, you can then run;

tox

Note tox tests for Python 2.7, 3.3, 3.4 and PyPy for Django 1.7 and 1.8. You’ll need to consult the docs for installation of these Python versions on your OS, on Ubuntu you can do the following;

sudo apt-get install python-software-properties
sudo add-apt-repository ppa:fkrull/deadsnakes
sudo apt-get update
sudo apt-get install python2.7 python2.7-dev
sudo apt-get install python3.3 python3.3-dev
sudo apt-get install python3.4 python3.4-dev
sudo apt-get install pypy pypy-dev

Note that django-nose issue #133 and #197 cause issues with some tests thus the reason for alexhayes/django-nose being used in the requirements/test.py and requirements/test3.py.

Thanks

Thank-you to roi.com.au for supporting this project.

Authors

• Jeremy Storer <[e-mail]>

• Alex Hayes <[e-mail]>