Usage¶
Basic¶
PyOffers provide HasOffersAPI
class to interact with HasOffers API.
from pyoffers.api import HasOffersAPI
hasoffers = HasOffersAPI(
endpoint='https://api.hasoffers.com/Apiv3/json',
network_token='<your_network_token>',
network_id='<your_network_id>',
verify=True,
retries=4,
retry_timeout=4,
verbosity=3
)
Possible options:
endpoint
- URL, which points to HasOffers server.
It may contain your subdomain as well -
https://<your_subdomain>.api.hasoffers.com/Apiv3/json
network_token
- Your NetworkToken.
network_id
- Your NetworkId.
verify
- Whether to verify SSL certificate or not. HasOffers SSL cert doesn’t cover subdomains like mentioned above.
Only
*.hasoffers.com
andhasoffers.com
. retries
- Number of retries to make a request in case of exceeding HasOffers API rate limit.
retry_timeout
- Seconds to wait between retries.
verbosity
- Controls library’s verbosity level. With 3 the request params and raw response will be printed to console.
With this class instance you can perform requests to the API.
Models¶
The core idea of interaction with model is based on managers. To work with HasOffers data model you should use appropriate manager. For now only very limited part of models are presented.
Core managers methods¶
-
create
(self, **kwargs)¶
Just pass model data as kwargs
to create new instance of model. The new instance will be returned.
-
update
(self, id, **kwargs)¶
Takes id
of existing model instance and new data as kwargs
. Updated instance will be returned.
-
find_by_id
(self, id, contain=None)¶
If you pass related models names to contain
argument, then if related model exists it will be attached to the
returned object as its attribute.
>>> offer = hasoffers.offers.find_by_id(id=62, contain=['Country'])
>>> print(offer.country)
<Country: 724>
-
find_all
(self, sort=(), limit=None, page=None, contain=None, **kwargs)¶
sort
can be a single field name or list of them. To sort in descending order put -
before the field name.
>>> hasoffers.offers.find_all(sort='-id')
[<Offer: 9>,
<Offer: 7>,
<Offer: 5>,
<Offer: 3>,
<Offer: 1>]
There are some extra features to make advanced queries.
To use different operators you should append its name to the end of the field_name.
Example. To get all offers with id
greater than 100:
>>> hasoffers.offers.find_all(id__gt=100, sort='id')
[<Offer: 102>,
<Offer: 104>,
<Offer: 106>,
<Offer: 108>,
<Offer: 110>,
<Offer: 112>]
PyOffers supports the following operators:
ne
-NOT_EQUAL_TO
lt
-LESS_THAN
lte
-LESS_THAN_OR_EQUAL_TO
gt
-GREATER_THAN
gte
-GREATER_THAN_OR_EQUAL_TO
like
-LIKE
not_like
-NOT_LIKE
null
-NULL
not_null
-NOT_NULL
true
-TRUE
false
-FALSE
To perform OR
queries pass connector='OR'
as filter.
To get all offers with active status OR with USD currency:
>>> hasoffers.offers.find_all(status='active', currency='USD', connector='OR')
To skip models instantiation you can pass raw=True
to underlying _call
method.
This makes it possible to perform queries without instantiation of model instances.
>>> hasoffers.advertisers._call('findAllIds', raw=True)
['1', '2', '3', '4']
Managers¶
- Advertiser -
hasoffers.advertisers
- Conversion -
hasoffers.conversions
- Country - As the model has no methods then
hasoffers.countries
manager has no methods too. - Goal -
hasoffers.goals
- Offer -
hasoffers.offers
- Affiliate -
hasoffers.affiliates
- AffiliateUser -
hasoffers.affiliate_users
- OfferFile -
hasoffers.offer_files
Raw logs¶
pyoffers
provides RawLog
model with 3 managers for different types of logs. They behave identically:
hasoffers.raw_logs.clicks
- logs about clicks.hasoffers.raw_logs.conversions
- about conversions.hasoffers.raw_logs.impressions
- about impressions.
To get all logs directories:
>>> hasoffers.raw_logs.clicks.list_date_dirs()
[<DateDir: Sep 20, 2016 (20160920)>, <DateDir: Sep 19, 2016 (20160919)>, ...]
Every directory has 2 attributes:
displayName
dirName
And list_logs
method:
>>> directory = hasoffers.raw_logs.clicks.list_date_dirs()[0]
>>> directory.list_logs()
[<LogFile: Sep 20, 2016 - 11:00 am (20160920/clicks-1474369200-ewU6Y1.zip)>, ...]
Each log file has:
download_link
- link to ZIP archive at Amazon S3.content
- raw CSV content of this archive.records
- all data from CSV wrapped asLogRecord
instances.
All these attributes are cached on LogFile
instance level.
For convenience it is possible to get all records for some date:
>>> hasoffers.raw_logs.clicks.find_all('20160920')
[<LogRecord: 7 (1027a606128bd067105f0b0921840f)>, ...]
Also it is possible to get records for month or even for year. But it will take some time to download all data.
>>> september_clicks = hasoffers.raw_logs.clicks.find_all('201609')
>>> year_clicks = hasoffers.raw_logs.clicks.find_all('2016')
Offer files (Creatives)¶
OfferFile
provides and ability to upload offer file (aka “Creative” in Hasoffers terms). To do so, you can use
create
method:
>>>hasoffers.offer_files.create('/relative/or/absolute/path/test.png', display='TEST_FILE',
type='offer thumbnail', width=200,height=100, offer_id=438, filename='custom_filename.png')
<OfferFile: 98>