Python Atomx Api

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('user@example.com', '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]