atomx 1.5

python interface for the atomx api on https://api.atomx.com

Interface for the atomx rest api.

For more information read the full documentation online, report bugs in github or see the atomx wiki

Example Usage

from atomx import Atomx

# create atomx session
atomx = Atomx('[e-mail]', 'password')

# get 10 creatives
creatives = atomx.get('Creatives', limit=10)
# the result is a list of `atomx.models.Creative` models
# that you can easily inspect, manipulate and update
for creative in creatives:
    print('Creative ID: {c.id}, state: {c.state}, '
          'name: {c.name}, title: {c.title}'.format(c=creative))

# update title for the first creative in list
creative = creatives[0]
creative.title = 'shiny new title'
# the session is inherited from `atomx` that made the get request
creative.save()


# create a new profile
from atomx.models import Profile
profile = Profile(advertiser_id=23, name='test profile')
# Note that you have to pass it a valid `Atomx` session for create
# or use `atomx.create(profile)`
profile.create(atomx)

# now you could alter and update it like the creative above
profile.name = 'changed name'
profile.save()


# you can also get attributes
profiles = atomx.get('advertiser', 88, 'profiles')
# equivalent is to pass the complete resource path as string instead of arguments
profiles = atomx.get('advertiser/88/profiles')  # same as above
# profiles is now a list of `atomx.models.Profile` that you can
# read, update, etc again.
profiles[0].click_frequency_cap_per = 86400
profiles[0].save()


# working with search
s = atomx.search('mini*')
# s is now a dict with lists of search results for the different models
# with the model id and name

publisher = s['publisher'][0]  # get the first publisher..
publisher.reload()  # .. and load all the data
print(publisher)  # now all publisher data is there
publisher.history()  # gets all changes made to this publisher


# reporting example
# get a report for a specific publisher
report = atomx.report(scope='publisher', groups=['hour'], metrics=['impressions', 'clicks'], where=[['publisher_id', '==', 42]], from_='2015-02-08 00:00:00', to='2015-02-09 00:00:00', timezone='America/Los_Angeles')
# check if report is ready
print(report.is_ready)
# if pandas is installed you can get the pandas dataframe with `report.pandas`
# you can also get the report csv in `report.content` without pandas
df = report.pandas  # A datetime index is automatically set when group by a hour/day/month.
# calculate mean, median, std per hour
means = df.resample('H', how=['mean', 'median', 'std'])
# and plot impression and clicks per day
means['impressions'].plot()
means['clicks'].plot()

Installation

To install the python atomx api, simply:

$ pip install atomx

or if you want to use ipython notebook and reporting functionality:

$ pip install atomx[report]