Usage¶

Creating a session¶

To work with the api you need to get a user from atomx and create a atomx.Atomx session using your email and password:

from atomx import Atomx

# create atomx session
atomx = Atomx('user@example.com', 'password')

optionally you can specify a different api endpoint for testing:

# create atomx session with sandbox endpoint
atomx = Atomx('user@example.com', 'password',
              api_endpoint='https://sandbox.api.atomx.com/v2')

Fetching resources¶

Use atomx.Atomx.get() to fetch any resource from the api. The first parameter is the resource you want to query and can be any string that the atomx api accepts. All additional keyword arguments are used to build the query string.

If the returned resource (or list of resources) is any of the atomx.models then that model instance will be returned so you can easily work with it.

For example to get 10 creatives and then print some information about it:

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

Or query all profiles of advertiser 42 ordered by last updated:

profiles = atomx.get('advertiser/42/profiles', order_by='updated_at.desc')

All non-keyword arguments that you pass atomx.Atomx.get() will get used to compute the resource. This makes it easier if you have the id (and/or attribute) stored in a variable.

E.g.

advertiser_id = 42
attribute = 'profiles'
profiles = atomx.get('advertiser', advertiser_id, attribute)
# is equivalent to atomx.get('advertiser/42/profiles')

You can also use a class or instance of atomx.models in a get requests. E.g. all of those api calls request the same resource:

from atomx.models import Advertiser

atomx.get('advertiser/42')  # all in 1 string
atomx.get('advertiser', 42)  # model, id split up
atomx.get(Advertiser, 42)  # using :class:`atomx.models.Advertiser`
atomx.get(Advertiser(42))  # using instance of :class:`atomx.models.Advertiser`

Or get all domains where the hostname contains atom:

domains = atomx.get('domains', name='*atom*')

Attributes that are not loaded in the model will be lazy loaded once you try to access them. E.g. if you want to access the quickstats for the creative we fetched earlier you don’t have to to anything special, just access the quickstats attribute:

creative = creatives[0]
print(creative.quickstats)

Or to get the advertiser for a profile, just:

advertiser = profiles[0].advertiser

You can get a list of all changes with atomx.models.AtomxModel.history().

advertiser.history()

Updating models¶

To change a atomx.models model you just change any attribute you want and call atomx.models.AtomxModel.save().

E.g.

# update title for the first creative in list
creative = creatives[0]
creative.title = 'shiny new title'
creative.save()

# update profile click frequency
profiles[0].click_frequency_cap_per = 86400
profiles[0].save()

Creating models¶

To add a new entry in atomx just instantiate any atomx.models model with all attributes you want your newly created model to have and either call atomx.models.AtomxModel.create() with your atomx.Atomx session as parameter or use atomx.Atomx.save().

E.g. create a new profile entry:

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

Search¶

Use atomx.Atomx.search() to search fast for anything.

atomx.Atomx.search() returns a dict with all found results for: ‘Advertisers’, ‘Campaigns’, ‘Creatives’, ‘Placements’, ‘Publishers’, ‘Sites’.

The resulting models have only id and name loaded since that’s what’s returned from the api /search call, but attributes will be lazy loaded once you try to accessed them. Or you can just fetch everything with one api call with AtomxModel.reload().

Example:

search_result = atomx.search('atomx')

campaign = search_result['campaigns'][0]
assert isinstance(campaign, models.Campaign)

# campaign has only `id` and `name` loaded but you
# can still access (lazy load) all attributes
print(campaign.budget)
print(campaign.profile)

# or reload all attributes with one api call
campaign.reload()

Reports¶

See atomx.Atomx.report() for a description of available parameters to create a report.

from datetime import datetime, timedelta

now = datetime.utcnow()
last_week = now - timedelta(days=7)

# get a report for a specific publisher
report = atomx.report(scope='publisher', groups=['hour'], metrics=['impressions', 'clicks'], where=[['publisher_id', '==', 42]], from_=last_week, to=now, timezone='America/Los_Angeles')

report.length  # get the number of rows returned
report.totals  # get the total values

# 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').apply(['mean', 'median', 'std'])
# and plot impression and clicks per day
means['impressions'].plot()
means['clicks'].plot()

For more general information about atomx reporting visit the reporting atomx knowledge base entry.