Python client for Taboola API
Project description
pytaboola
Python client for Taboola API (https://github.com/taboola/Backstage-API). Before any use of this client, you must have gotten your API client ID and client secret from your Taboola account manager.
Client ID is required for any usage.
Authentication and authorization
This client supports both access_token/refresh_token and client_id/client_secret OAuth2 authorization methods.
The access_token/refresh_token method is the recommended one, but following examples will use the other one as it is easier to implement.
Simple Connection
Example of a simple connection using client_id/client_secret.
CLIENT_ID = 'XXXXX'
CLIENT_SECRET = 'YYYYY'
from pytaboola import TaboolaClient
client = TaboolaClient(CLIENT_ID, client_secret=CLIENT_SECRET)
client.token_details
> {'account_id': 'my-taboola-account',
'expires_in': 43189,
'full_name': 'User Name',
'username': 'user@mail.me'}
Services
Here is a quick description of the services provided by this client.
Account listing
A service with only one method, allowing to list advertiser accounts linked to your main Taboola account. This service is read-only.
CLIENT_ID = 'XXXXX'
CLIENT_SECRET = 'YYYYY'
from pytaboola import TaboolaClient
from pytaboola.services import AccountService
client = TaboolaClient(CLIENT_ID, client_secret=CLIENT_SECRET)
service = AccountService(client)
service.list()
>>> {'results': [{'account_id': 'my-first-acount',
'campaign_types': ['PAID'],
'id': 1111111,
'name': 'My First Taboola Account',
'partner_types': ['ADVERTISER'],
'type': 'PARTNER'},
{'account_id': 'my-other-account',
'campaign_types': ['PAID'],
'id': 2222222,
'name': 'My Other Taboola Account',
'partner_types': ['ADVERTISER'],
'type': 'PARTNER'}]}
Campaign CRUD
Simple CRUD service implementing listing, access, creation, edition. All requests are scoped by account. So, it is impossible to list campaigns cross accounts.
Service is instanciated as follow.
CLIENT_ID = 'XXXXX'
CLIENT_SECRET = 'YYYYY'
from pytaboola import TaboolaClient
from pytaboola.services import CampaignService
client = TaboolaClient(CLIENT_ID, client_secret=CLIENT_SECRET)
service = CampaignService(client, 'my-account-id')
Methods
List all campaigns for an account :
service.list()
Get a campaign :
service.get('my-campaign-id')
Update a campaign :
service.get('my-campaign-id', **attrs)
Please note that update is partial. To delete a field, you will have to set it at None explicitly (if this attribute is nullable obviously).
Create a campaign :
service.create(**attrs)
In these last examples, attrs
is a dict containing attributes of the campaign.
For more information on campaign attributes, please see the Backstage API documentation at
https://github.com/taboola/Backstage-API/blob/master/Backstage%20API%20-%20Campaigns.pdf
Campaign Item CRUD
As with Campaign CRUD service, this is a simple CRUD service implementing listing, access, creation, edition. All requests are scoped by campaign.
CLIENT_ID = 'XXXXX'
CLIENT_SECRET = 'YYYYY'
from pytaboola import TaboolaClient
client = TaboolaClient(CLIENT_ID, client_secret=CLIENT_SECRET)
service = CampaignItemService(client, 'my-account-id', 'my-campaign-id')
service.list()
Methods
Basic CRUD methods have the same signature as the ones of the campaign service.
List all RSS Children for this campaign :
service.children()
Get a child item by its ID :
service.child('my-child-id')
Update a child :
service.child('my-child-id', **attrs)
For more information on campaign item attributes and what RSS Children are, please see the Backstage API documentation at https://github.com/taboola/Backstage-API/blob/master/Backstage%20API%20-%20Campaign%20Items.pdf
Reports
All report services have only a fetch method, with the following signature :
def fetch(self, dimension, start_date, end_date, **filters)
where dimension is the aggregation view of the report, start_date and end_date delimitate the period to fetch the report on, and filters are ways to narrow down your report data.
For more information, please refer to the Backstage API documentation : https://github.com/taboola/Backstage-API/blob/master/Backstage%20API%20-%20Reports.pdf
Available services are :
- CampaignSummaryReport
- TopCampaignContentReport
- RevenueSummaryReport
- VisitValueReport
- RecirculationSummaryReport
Todo:
Resource services
Resource services are available in this client, but not all endpoints are available. Also, they are not properly documented.
Testing
There is not much intelligence in this wrapper, but all utility functions (such as response parsing) and authentication / refresh workflow should be tested to avoid regressions.
Data validators
As for now, all data validation is delegated to the Taboola API. It may be useful to had a small bit of data type checking before any call.
Authentication
user/password authentication method is not implemented. It should be useless in any production environment, but may be used as a fast POC/testing authentication system.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pytaboola-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7def813f1ca3900f395df09f869bf52a5a70d342faba148fe7f5c909188e1ec3 |
|
MD5 | a14b8c5ef8943904e7cf0421e29a21b7 |
|
BLAKE2b-256 | ef998e4dd4250ce53573a4f3890a9890da6ed58cae7ea539bf74787ed1b679f8 |