API

Session

class atomx.Atomx(email, password, totp=None, api_endpoint='https://api.atomx.com/v3', save_response=True, expiration=None)

Interface for the api on api.atomx.com.

To learn more about the api visit the atomx wiki

Parameters:
  • email (str) – email address of your atomx user
  • password (str) – password of your atomx user
  • totp (str) – 6 digit auth token if the account has 2-factor authentication enabled.
  • api_endpoint (str) – url for connections to the api (defaults to https://api.atomx.com/{API_VERSION})
  • save_response (bool) – If True save the last api response meta info (without the resource payload) in Atomx.last_response. (default: True)
Returns:

Atomx session to interact with the api
create(model)

Alias for models.AtomxModel.create() with session argument.

delete(resource, *args, **kwargs)

Send HTTP DELETE to resource.

Parameters:
  • resource – Name of the resource to DELETE.
  • args – All non-keyword arguments will be used to compute the final resource.
  • kwargs – Optional keyword arguments will be passed as query string to the delete request.
Returns:

message or resource returned by the api.
get(resource, *args, **kwargs)

Returns a list of models from models if you query for multiple models or a single instance of a model from models if you query for a specific id

Parameters:
  • resource (str) –

    Specify the resource to get from the atomx api.

    Examples:

    Query all advertisers:

    >>> atomx = Atomx('apiuser@example.com', 'password')
>>> advertisers = atomx.get('advertisers')
>>> assert isinstance(advertisers, list)
>>> assert isinstance(advertisers[0], atomx.models.Advertiser)

    Get publisher with id 23:

    >>> publisher = atomx.get('publisher/23')
>>>> # or get the same publisher using the id as parameter
>>> publisher = atomx.get('publisher', 23)
>>>> # or use an atomx model
>>> publisher = atomx.get(atomx.models.Publisher(23))
>>> assert publisher.id == 23
>>> assert isinstance(publisher, atomx.models.Publisher)

    Get all profiles for advertiser 42:

    >>> profiles = atomx.get('advertiser/42/profiles')
>>> assert isinstance(profiles, list)
>>> assert isinstance(profiles[0], atomx.models.Profile)
>>> assert profiles[0].advertiser.id == 42
  • args –

    All non-keyword arguments will get used to compute the resource. This makes it easier if you want to work with a variable resource path.

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

    Any argument is passed as URL parameter to the respective api endpoint. See API URL Parameters in the wiki.

    Example: Get the first 20 domains that contain atom:

    >>> atom_domains = atomx.get('domains', hostname='*atom*', limit=20)
>>> assert len(atom_domains) == 20
>>> assert 'atom' in atom_domains[1].hostname
Returns:

a class from models or a list of models depending on param resource
last_response = None

Contains the response of the last api call, if save_response was set True

login(email, password, totp=None, expiration=None)

Gets new authentication token for user email.

This method is automatically called in __init__() so you rarely have to call this method directly.

Parameters:
  • email (str) – Email to use for login.
  • password (str) – Password to use for login.
  • totp (str) – 6 digit auth token if the account has 2-factor authentication enabled.
  • expiration (int) – Number of seconds that the auth token should be valid. (optional)
Returns:

None
Raises:

exceptions.InvalidCredentials if email/password is wrong
logout()

Removes authentication token from session.

post(resource, json, **kwargs)

Send HTTP POST to resource with json content.

Used by models.AtomxModel.create().

Parameters:
  • resource – Name of the resource to POST to.
  • json – Content of the POST request.
  • kwargs – URL Parameters of the request.
Returns:

dict with the newly created resource.
put(resource, id, json, **kwargs)

Send HTTP PUT to resource/id with json content.

Used by models.AtomxModel.save().

Parameters:
  • resource – Name of the resource to PUT to.
  • id – Id of the resource you want to modify
  • json – Content of the PUT request.
  • kwargs – URL Parameters of the request.
Returns:

dict with the modified resource.
remove(model)

Alias for models.AtomxModel.delete() with session argument.

report(scope=None, groups=None, metrics=None, where=None, from_=None, to=None, daterange=None, timezone='UTC', emails=None, when=None, interval=None, name=None, sort=None, limit=None, offset=None, save=True, editable=False)

Create a report.

See the reporting atomx wiki for details about parameters and available groups, metrics.

Parameters:
  • scope (str) – Specifies the report type. Should be one of: ‘advertiser’, ‘publisher’, ‘inventory’, ‘dsp’, ‘network_managed’, ‘network_buy’, ‘network_sell’. If undefined it tries to determine the scope automatically based on the access rights of the api user.
  • groups (list) – columns to group by.
  • metrics (list) – columns to sum on.
  • where (list) –

    is a list of expression lists. An expression list is in the form of [column, op, value]:

    • column can be any of the groups or metrics parameter columns.
    • op can be any of ==, !=, <, >, in or not in as a string.
    • value is either a number or in case of in and not in a list of numbers.
  • from (datetime.datetime) – datetime.datetime where the report should start (inclusive). (Defaults to last week)
  • to (datetime.datetime) – datetime.datetime where the report should end (exclusive). (Defaults to datetime.now() if undefined)
  • daterange (str) – Use :param:`daterange` to automatically set the reports

from and to parameters relativ to the current date. Both :param:`from_` and :param:`to` have to be None for it. Dateranges are: today, yesterday, last7days, last14days, last30days, monthtodate,

lastmonth, yeartodate, lifetime. (Defaults to None)
Parameters:
  • timezone (str) – Timezone used for all times. (Defaults to UTC) For a supported list see https://wiki.atomx.com/timezones
  • emails (str or list) – One or multiple email addresses that should get notified once the report is finished and ready to download.
  • when (str) – When should the scheduled report run. (daily, monthly, monday-sunday)
  • interval (str) – Time period included in the scheduled report (‘N days’ or ‘N month’)
  • name (str) – Optional name for the report.
  • or list sort (str) – List of columns to sort by.
  • limit (int) – Number of rows to return
  • offset (int) – Number of rows to skip.
  • save (bool) – Should the report appear in the users report history (defaults to True).
  • editable (bool) – Should other users be able to change the date range of this report.
Returns:

A atomx.models.Report model
save(model)

Alias for models.AtomxModel.save() with session argument.

search(query, index=None)

Search for query.

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:

>>> atomx = Atomx('apiuser@example.com', 'password')
>>> search_result = atomx.search('atomx')
>>> assert 'campaigns' in search_result
>>> 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
>>> assert isinstance(campaign.budget, float)
>>> # or reload all attributes with one api call
>>> campaign.reload()
Parameters:
  • query (str) – keyword to search for.
  • index (list) – str or list of the indexes you want to get returned. E.g. index=['campaigns', 'domains'].
Returns:

dict with list of models as values

Models

class atomx.models.AtomxModel(id=None, session=None, **attributes)

A generic atomx model that the other models from atomx.models inherit from.

Parameters:
  • id (int) – Optional model ID. Can also be passed in via attributes as id.
  • session (atomx.Atomx) – The atomx.Atomx session to use for the api requests.
  • attributes – model attributes
create(session=None)

POST the model to the api and populates attributes with api response.

Parameters:session – The atomx.Atomx session to use for the api call. (Optional if you specified a session at initialization)
Returns:self
Return type:AtomxModel
delete(session=None)

DELETE the model in the api. A deleted attribute is to True on self so you can check if a AtomxModel is deleted or not.

Warning

Calling this method will permanently remove this model from the API.

Parameters:session – The atomx.Atomx session to use for the api call. (Optional if you specified a session at initialization)
Returns:A dict of all models that the API removed. Keys are the model names and values are a list of IDs.
Return type:dict
history(session=None, offset=0, limit=100, sort='date.asc')

Show the changelog of the model.

Parameters:
  • session – The atomx.Atomx session to use for the api call. (Optional if you specified a session at initialization)
  • offset (int) – Skip first offset history entries. (default: 0)
  • limit (int) – Only return limit history entries. (default: 100)
  • sort (str) – Sort by date.asc or date.desc. (default: ‘date.asc’)
Returns:

list of dict`s with `date, user and the attributes that changed (history).
Return type:

list
json

Returns the model attributes as dict.

reload(session=None, **kwargs)

Reload the model from the api and update attributes with the response.

This is useful if you have not all attributes loaded like when you made an api request with the attributes parameter or you used atomx.Atomx.search().

Parameters:session – The atomx.Atomx session to use for the api call. (Optional if you specified a session at initialization)
Returns:self
Return type:AtomxModel
save(session=None)

PUT the model to the api and update attributes with api response.

Parameters:session – The atomx.Atomx session to use for the api call. (Optional if you specified a session at initialization)
Returns:self
Return type:AtomxModel
update(session=None)

Alias for AtomxModel.save().

class atomx.models.AccountManager(id=None, session=None, **attributes)

AtomxModel for AccountManager

class atomx.models.Advertiser(id=None, session=None, **attributes)

AtomxModel for Advertiser

class atomx.models.App(id=None, session=None, **attributes)

AtomxModel for App

class atomx.models.Appstore(id=None, session=None, **attributes)

AtomxModel for Appstore

class atomx.models.Bidder(id=None, session=None, **attributes)

AtomxModel for Bidder

class atomx.models.Browser(id=None, session=None, **attributes)

AtomxModel for Browser

class atomx.models.CampaignDebugReason(id=None, session=None, **attributes)

AtomxModel for CampaignDebugReason

class atomx.models.Campaign(id=None, session=None, **attributes)

AtomxModel for Campaign

class atomx.models.Category(id=None, session=None, **attributes)

AtomxModel for Category

class atomx.models.ConnectionType(id=None, session=None, **attributes)

AtomxModel for ConnectionType

class atomx.models.City(id=None, session=None, **attributes)

AtomxModel for City

class atomx.models.ConversionPixel(id=None, session=None, **attributes)

AtomxModel for ConversionPixel

class atomx.models.Country(id=None, session=None, **attributes)

AtomxModel for Country

class atomx.models.Creative(id=None, session=None, **attributes)

AtomxModel for Creative

class atomx.models.CreativeAttribute(id=None, session=None, **attributes)

AtomxModel for CreativeAttribute

class atomx.models.Datacenter(id=None, session=None, **attributes)

AtomxModel for Datacenter

class atomx.models.DeviceType(id=None, session=None, **attributes)

AtomxModel for DeviceType

class atomx.models.Domain(id=None, session=None, **attributes)

AtomxModel for Domain

class atomx.models.Dma(id=None, session=None, **attributes)

AtomxModel for Dma

class atomx.models.Dsp(id=None, session=None, **attributes)

AtomxModel for Dsp

class atomx.models.Fallback(id=None, session=None, **attributes)

AtomxModel for Fallback

class atomx.models.Isp(id=None, session=None, **attributes)

AtomxModel for Isp

class atomx.models.Languages(id=None, session=None, **attributes)

AtomxModel for Languages

class atomx.models.Network(id=None, session=None, **attributes)

AtomxModel for Network

class atomx.models.OperatingSystem(id=None, session=None, **attributes)

AtomxModel for OperatingSystem

class atomx.models.Placement(id=None, session=None, **attributes)

AtomxModel for Placement

class atomx.models.PlacementType(id=None, session=None, **attributes)

AtomxModel for PlacementType

class atomx.models.PriceModel(id=None, session=None, **attributes)

AtomxModel for PriceModel

class atomx.models.Profile(id=None, session=None, **attributes)

AtomxModel for Profile

class atomx.models.Publisher(id=None, session=None, **attributes)

AtomxModel for Publisher

class atomx.models.Reason(id=None, session=None, **attributes)

AtomxModel for Reason

class atomx.models.Report(id, query=None, name=None, emails=None, length=None, totals=None, columns=None, created_at=None, data=None, user_id=None, session=None, is_scheduled_report=False, to=None, from_=None, **kwargs)

Represents a report you get back from atomx.Atomx.report().

delete(session=None)

Delete report

pandas

Returns the content of the report as a pandas data frame.

save(session=None)

Update report name and emails

class atomx.models.Segment(id=None, session=None, **attributes)

AtomxModel for Segment

class atomx.models.SellerProfile(id=None, session=None, **attributes)

AtomxModel for SellerProfile

class atomx.models.Site(id=None, session=None, **attributes)

AtomxModel for Site

class atomx.models.Size(id=None, session=None, **attributes)

AtomxModel for Size

class atomx.models.Ssp(id=None, session=None, **attributes)

AtomxModel for Ssp

class atomx.models.SspResultType(id=None, session=None, **attributes)

AtomxModel for SspResultType

class atomx.models.SspSuspicious(id=None, session=None, **attributes)

AtomxModel for SspSuspicious

class atomx.models.Timezone(id=None, session=None, **attributes)

AtomxModel for Timezone

class atomx.models.User(id=None, session=None, **attributes)

AtomxModel for User

class atomx.models.Visibility(id=None, session=None, **attributes)

AtomxModel for Visibility

class atomx.models.Zipcode(id=None, session=None, **attributes)

AtomxModel for Zipcode

class atomx.models.Report(id, query=None, name=None, emails=None, length=None, totals=None, columns=None, created_at=None, data=None, user_id=None, session=None, is_scheduled_report=False, to=None, from_=None, **kwargs)

Represents a report you get back from atomx.Atomx.report().

delete(session=None)

Delete report

pandas

Returns the content of the report as a pandas data frame.

save(session=None)

Update report name and emails

Exceptions

exception atomx.exceptions.APIError

Raised when the atomx api returns an error that is not caught otherwise.

exception atomx.exceptions.InvalidCredentials

Raised when trying to login with the wrong e-mail or password.

exception atomx.exceptions.MissingArgumentError

Raised when argument is missing.

exception atomx.exceptions.ModelNotFoundError

Raised when trying to (re-)load a model that is not in the api.

exception atomx.exceptions.NoPandasInstalledError

Raised when trying to access report.pandas without pandas installed.

exception atomx.exceptions.NoSessionError

Raised when a model from models wants to create/update but it doesn’t have an atomx.Atomx session yet.