<jupyter_start><jupyter_text>Starting with the API This tutorial explains how to use the `api` module. The `RadarlyApi` object is defined in this module and is used by `radarly` in order to handle communications with the API. For example, it simplifies the OAuth2 authorization system and can also refresh your access token when it has expired.<jupyter_code>from radarly import RadarlyApi
from requests.exceptions import ProxyError
from pprint import pprint<jupyter_output><empty_output><jupyter_text>Initialization The `RadarlyApi` object must be initialized with at least two arguments : the `client_id` and the `client_secret`. These credentials are given by Linkfluence and must not be shared because they are used in order to authentify each request to our APIs. If you don't have these credentials to start with the client, please contact us at <EMAIL>.<jupyter_code>credentials = {
    "client_id": ":my_client_id:",
    "client_secret": ":my_client_secret:"
}
api = RadarlyApi(**credentials, scope=['listening', 'social-performance'])
api<jupyter_output><empty_output><jupyter_text>Some additional parameters can be set directly during the initialization of the API and will be used each time a request is made. For example, you can set  proxies and timeout for your requests. The proxies object must have the same template of the proxies object defined in `requests` module.<jupyter_code>proxies = {
    'http': 'http://127.0.0.1:9000',
    'https': 'https://127.0.0.1:9000'
}
timeout = 120

try:
    RadarlyApi(**credentials, proxies=proxies, timeout=timeout)
except ProxyError:
    print('Warning: This will not work without a valid proxy.')<jupyter_output>Warning: This will not work without a valid proxy.<jupyter_text>Given that some requests in the API can take tens of seconds to process, you should consider setting a high enough value for the `timeout` argument. Otherwise, some requests can be stopped purely because the timeout has expired. Each optional argument can be set after initialization.<jupyter_code>api.proxies = None
api.timeout = 2<jupyter_output><empty_output><jupyter_text>In order to avoid having to specify the API object in each request, you can set a default API. This API will be used each time you make a request to the ``RadarlyApi``  if no API object is specified.<jupyter_code>RadarlyApi.set_default_api(api)
# You can also retrieve the default API
api = RadarlyApi.get_default_api()
api<jupyter_output><empty_output><jupyter_text>In order to initialize a new API and set it as the default API, yon can use the ``init`` class method. This method uses the same arguments as the ``__init__``method.<jupyter_code>api = RadarlyApi.init(**credentials, timeout=200, proxies=None)
api == RadarlyApi.get_default_api()<jupyter_output><empty_output><jupyter_text>Notice that rather than specifying the ``client_id`` and  ``client_secret`` argument during the initialization of the API, you can set the ``RADARLY_CLIENT_ID`` and ``RADARLY_CLIENT_SECRET`` environment variables. ``RadarlyApi`` will automatically retrieve these variables if ``client_id`` and ``client_secret`` is set to ``None``.<jupyter_code>%%bash
export RADARLY_CLIENT_ID=:my_client_id:
export RADARLY_CLIENT_SECRET=:my_client_secret:
!export RADARLY_CLIENT_ID=:my_client_id:
!export RADARLY_CLIENT_SECRET=:my_client_secret:
RadarlyApi.init(scope=['listening', 'social-performance'])<jupyter_output><empty_output><jupyter_text>run some requests The ``RadarlyApi`` object can now be used in order to run all requests to the Radarly API. The `request` method defined in `RadarlyApi` uses the same arguments as the `request` function of the `requests` module, but some behaviours are different. For example, if the pattern `{API_Host}/{version}` is not present in the URL of your request, it will be automatically added at the beginning of your URL.The root url and the version of the API are class variable of the `RadarlyApi` object.<jupyter_code>print('Host of the API:', api.root_url)
print('Current version of the API:', api.version)<jupyter_output>Host of the API: https://radarly.linkfluence.com
Current version of the API: 1.0<jupyter_text>You can now perform a request, using any relative path exposed in our API. For example, to get information about the current user.<jupyter_code>current_user = api.request('GET', 'https://radarly.linkfluence.com/1.1/users.json')<jupyter_output><empty_output><jupyter_text>As in the ``requests`` module, you can use the ``get`` method to perform a request with ``GET``.<jupyter_code>current_user = api.get('/users.json')
pprint(current_user, depth=1)<jupyter_output>{'account_id': 1,
 'apps': [...],
 'can_create_project': True,
 'connected': 1526635380515,
 'connection_count': 102,
 'created': datetime.datetime(2018, 2, 12, 17, 59, 55, 105000, tzinfo=tzutc()),
 'current_project_id': 3740,
 'email': '<EMAIL>',
 'engagement': {...},
 'id': 16246,
 'is_disabled': False,
 'is_internal': True,
 'is_manager': True,
 'is_pending': False,
 'is_root': True,
 'level': 'root',
 'locale': 'en_GB',
 'name': '<NAME>',
 'picture_id': None,
 'projects': [...],
 'theme': 'dark',
 'timezone': <DstTzInfo 'Europe/Paris' LMT+0:09:00 STD>,
 'updated': datetime.datetime(2018, 2, 15, 15, 19, 54, 834000, tzinfo=tzutc())}<jupyter_text>The result is a JSON file, as in any standard request. If you want to have more interactive objects as response, you can use our special methods (they are explained in the next steps of the tutorial). To help you get all relative paths in the API, you can use the ``Router`` object defined in ``radarly.utils.router``. This object stores, as attibutes, all the paths relative to a category.<jupyter_code>from radarly.utils.router import Router
print('Routes relative to user'), pprint(Router.user)
print('\nRoutes relative to analytics details'), pprint(Router.analytics)
print('\nRoutes relative to publications'), pprint(Router.publication)<jupyter_output>Routes relative to user
{'me': '/users.json'}

Routes relative to analytics details
{'global': '/projects/{project_id}/insights.json',
 'occupation': '/projects/{project_id}/insights/occupation.json'}

Routes relative to publications
{'metadata': '/projects/{project_id}/documents.json',
 'raw': '/projects/{project_id}/documents/raw.json',
 'search': '/projects/{project_id}/inbox/search.json'}<jupyter_text>As you can see, most of the routes are just patterns and some path arguments must be specified (in most cases, the ``project_id``).<jupyter_code>url = Router.publication['search'].format(project_id=2)
print('URL to search publication in the project 2:', url)
response = api.post(url, data={'platforms': ['instagram'], 'start': 0, 'limit': 15})
print('Response:')
pprint(response, depth=1)<jupyter_output>URL to search publication in the project 2: /projects/2/inbox/search.json
Response:
{'hits': [...], 'stats': {}, 'took': 1546, 'total': 6568}<jupyter_text>Check the rates Some limitations on the number of requests you can made to our API have been defined. You can find out more about these limitations by checking the ``rates`` attributes of the API. Each road of the API is not subjected to the same limits. There are three categories of rate limits: slow, medium and default (the routes in 'slow' category are routes with the most restrictive limits). Please refer to the official documentation of the API for further information.<jupyter_code>api.rates<jupyter_output><empty_output><jupyter_text>You can then explore each category of rate limits.<jupyter_code>api.rates.slow
api.rates.medium
api.rates.default<jupyter_output><empty_output><jupyter_text>You can check the category of a URL with the ``RateConf`` object, defined in ``radarly.rate``.<jupyter_code>from radarly.rate import RateConf
url = '/users.json'
print(f'Category for the URL {url}:', RateConf.get_category(url))
url = '/projects/2/inbox/search.json'
print(f'Category for the URL {url}:', RateConf.get_category(url))<jupyter_output>Category for the URL /users.json: default
Category for the URL /projects/2/inbox/search.json: medium
{'fraction_non_alphanumeric': 0.10942551604078588, 'fraction_numerical': 0.014921661278288983, 'mean_word_length': 6.086343612334802, 'pattern_counts': {'":': 4, '<': 59, '<?xml version=': 0, '>': 59, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '15', 'dir': 'jupyter-structured-clean-dedup', 'id': '291667', 'license': 'Apache-2.0', 'n_tokens_mistral': 2505, 'n_tokens_neox': 2386, 'n_words': 893, 'path': 'docs/python/quickstart/API.ipynb', 'repo_name': 'gvannest/radarly-py', 'size': '8088'}