Metadata-Version: 2.1
Name: tapi-yandex-direct
Version: 2021.5.25
Summary: Python client for API Yandex Direct
Home-page: https://github.com/pavelmaksimov/tapi-yandex-direct
Author: Pavel Maksimov
Author-email: vur21@ya.ru
License: MIT
Description: # Python client for [API Yandex Direct](https://yandex.ru/dev/metrika/doc/api2/concept/about-docpage/)
        
        ![Supported Python Versions](https://img.shields.io/static/v1?label=python&message=>=3.6&color=green)
        [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/vintasoftware/tapioca-wrapper/master/LICENSE)
        [![Downloads](https://pepy.tech/badge/tapi-yandex-direct)](https://pepy.tech/project/tapi-yandex-direct)
        <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
        
        ## Installation
        
        Prev version
        
            pip install --upgrade tapi-yandex-direct==2020.12.15
        
        Last version. Has backward incompatible changes.
        
            pip install --upgrade tapi-yandex-direct==2021.5.25
        
        ## Examples
        
        [Ipython Notebook](https://github.com/pavelmaksimov/tapi-yandex-direct/blob/master/examples.ipynb)
        
        
        ## Documentation
        [Справка](https://yandex.ru/dev/direct/) Api Яндекс Директ
        
        
        ### Client params
        ```python
        from tapi_yandex_direct import YandexDirect
        
        ACCESS_TOKEN = "{your_access_token}"
        
        client = YandexDirect(
            # Required parameters:
        
            access_token=ACCESS_TOKEN,
            # If you are making inquiries from an agent account, you must be sure to specify the account login.
            login="{login}",
        
            # Optional parameters:
        
            # Enable sandbox.
            is_sandbox=False,
            # Repeat request when units run out
            retry_if_not_enough_units=False,
            # The language in which the data for directories and errors will be returned.
            language="ru",
            # Repeat the request if the limits on the number of reports or requests are exceeded.
            retry_if_exceeded_limit=True,
            # Number of retries when server errors occur.
            retries_if_server_error=5
        )
        ```
        
        ### Resource methods
        ```python
        print(dir(client))
        [
            "adextensions",
            "adgroups",
            "adimages",
            "ads",
            "agencyclients",
            "audiencetargets",
            "bidmodifiers",
            "bids",
            "businesses",
            "campaigns",
            "changes",
            "clients",
            "creatives",
            "debugtoken",
            "dictionaries",
            "dynamicads",
            "feeds",
            "keywordbids",
            "keywords",
            "keywordsresearch",
            "leads",
            "negativekeywordsharedsets",
            "reports",
            "retargeting",
            "sitelinks",
            "smartadtargets",
            "turbopages",
            "vcards",
        ]
        ```
        or look into [resource mapping](tapi_yandex_direct/resource_mapping.py)
        
        ### Request
        
        API requests are made over HTTPS using the POST method.
        Input data structures are passed in the body of the request.
        
        ```python
        import datetime as dt
        
        # Get campaigns.
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
            },
        }
        campaigns = client.campaigns().post(data=body)
        print(campaigns)
        # <TapiClient object
        # {   'result': {   'Campaigns': [   {   'Id': 338157,
        #                                        'Name': 'Test API Sandbox campaign 1'},
        #                                    {   'Id': 338158,
        #                                        'Name': 'Test API Sandbox campaign 2'}],
        #                   'LimitedBy': 2}}>
        
        
        # Extract raw data.
        data = campaigns.data
        assert isinstance(data, dict)
        
        
        # Create a campaign.
        body = {
            "method": "add",
            "params": {
                "Campaigns": [
                    {
                        "Name": "MyCampaignTest",
                        "StartDate": str(dt.datetime.now().date()),
                        "TextCampaign": {
                            "BiddingStrategy": {
                                "Search": {
                                    "BiddingStrategyType": "HIGHEST_POSITION"
                                },
                                "Network": {
                                    "BiddingStrategyType": "SERVING_OFF"
                                }
                            },
                            "Settings": []
                        }
                    }
                ]
            }
        }
        result = client.campaigns().post(data=body)
        print(result)
        # <TapiClient object
        # {'result': {'AddResults': [{'Id': 417065}]}}>
        
        # Extract raw data.
        data = campaigns.data
        assert isinstance(data, dict)
        print(result)
        # {'result': {'AddResults': [{'Id': 417066}]}}
        ```
        
        
        ### Client methods
        
        Result extraction method.
        
        ```python
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
            },
        }
        campaigns = client.campaigns().post(data=body)
        
        # Request response.
        print(campaigns.response)
        print(campaigns.request_kwargs)
        print(campaigns.status_code)
        print(campaigns.data)
        ```
        
        ### .extract()
        
        Result extraction method.
        
        ```python
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
            },
        }
        campaigns = client.campaigns().post(data=body)
        campaigns_list = campaigns().extract()
        assert isinstance(campaigns_list, list)
        print(campaigns_list)
        # [{'Id': 338157, 'Name': 'Test API Sandbox campaign 1'},
        #  {'Id': 338158, 'Name': 'Test API Sandbox campaign 2'}]
        ```
        
        
        ### .items()
        
        Iterating result items.
        
        ```python
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
            },
        }
        campaigns = client.campaigns().post(data=body)
        
        for item in campaigns().items():
            print(item)
            # {'Id': 338157, 'Name': 'Test API Sandbox campaign 1'}
            assert isinstance(item, dict)
        ```
        
        
        ### .pages()
        
        Iterating to get all the data.
        
        ```python
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
                "Page": {"Limit": 2}
            },
        }
        campaigns = client.campaigns().post(data=body)
        
        # Iterating requests data.
        for page in campaigns().pages():
            assert isinstance(page.data, list)
            print(page.data)
            # [{'Id': 338157, 'Name': 'Test API Sandbox campaign 1'},
            #  {'Name': 'Test API Sandbox campaign 2', 'Id': 338158}]
        
            # Iterating items of page data.
            for item in page().items():
                print(item)
                # {'Id': 338157, 'Name': 'Test API Sandbox campaign 1'}
                assert isinstance(item, dict)
        ```
        
        
        ### .iter_items()
        
        After each request, iterates over the items of the request data.
        
        ```python
        body = {
            "method": "get",
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Id","Name"],
                "Page": {"Limit": 2}
            },
        }
        campaigns = client.campaigns().post(data=body)
        
        # Iterates through the elements of all data.
        for item in campaigns().iter_items():
            assert isinstance(item, dict)
            print(item)
        
        # {'Name': 'MyCampaignTest', 'Id': 417065}
        # {'Name': 'MyCampaignTest', 'Id': 417066}
        # {'Id': 338157, 'Name': 'Test API Sandbox campaign 1'}
        # {'Name': 'Test API Sandbox campaign 2', 'Id': 338158}
        # {'Id': 338159, 'Name': 'Test API Sandbox campaign 3'}
        # {'Name': 'MyCampaignTest', 'Id': 415805}
        # {'Id': 416524, 'Name': 'MyCampaignTest'}
        # {'Id': 417056, 'Name': 'MyCampaignTest'}
        # {'Id': 417057, 'Name': 'MyCampaignTest'}
        # {'Id': 417058, 'Name': 'MyCampaignTest'}
        # {'Id': 417065, 'Name': 'MyCampaignTest'}
        # {'Name': 'MyCampaignTest', 'Id': 417066}
        ```
        
        
        ## Reports
        
        ```python
        from tapi_yandex_direct import YandexDirect
        
        ACCESS_TOKEN = "{ваш токен доступа}"
        
        client = YandexDirect(
            # Required parameters:
        
            access_token=ACCESS_TOKEN,
            # If you are making inquiries from an agent account, you must be sure to specify the account login.
            login="{login}",
        
            # Optional parameters:
        
            # Enable sandbox.
            is_sandbox=False,
            # Repeat request when units run out
            retry_if_not_enough_units=False,
            # The language in which the data for directories and errors will be returned.
            language="ru",
            # Repeat the request if the limits on the number of reports or requests are exceeded.
            retry_if_exceeded_limit=True,
            # Number of retries when server errors occur.
            retries_if_server_error=5,
        
            # Report resource parameters:
        
            # Report generation mode: online, offline or auto.
            processing_mode="offline",
            # When requesting a report, it will wait until the report is prepared and download it.
            wait_report=True,
            # Monetary values in the report are returned in currency with an accuracy of two decimal places.
            return_money_in_micros=False,
            # Do not display a line with the report name and date range in the report.
            skip_report_header=True,
            # Do not display a line with field names in the report.
            skip_column_header=False,
            # Do not display a line with the number of statistics lines in the report.
            skip_report_summary=True,
        )
        
        body = {
            "params": {
                "SelectionCriteria": {},
                "FieldNames": ["Date", "CampaignId", "Clicks", "Cost"],
                "OrderBy": [{
                    "Field": "Date"
                }],
                "ReportName": "Actual Data",
                "ReportType": "CAMPAIGN_PERFORMANCE_REPORT",
                "DateRangeType": "LAST_WEEK",
                "Format": "TSV",
                "IncludeVAT": "YES",
                "IncludeDiscount": "YES"
            }
        }
        report = client.reports().post(data=body)
        print(report.data)
        # 'Date\tCampaignId\tClicks\tCost\n'
        # '2019-09-02\t338151\t12578\t9210750000\n'
        ```
        
        
        ### .columns
        
        Extract column names.
        ```python
        report = client.reports().post(data=body)
        print(report.columns)
        # ['Date', 'CampaignId', 'Clicks', 'Cost']
        ```
        
        
        ### .to_lines()
        
        ```python
        report = client.reports().post(data=body)
        print(report().to_lines())
        # list[str]
        # [..., '2019-09-02\t338151\t12578\t9210750000']
        ```
        
        
        ### .to_values()
        
        ```python
        report = client.reports().post(data=body)
        print(report().to_values())
        # list[list[str]]
        # [..., ['2019-09-02', '338151', '12578', '9210750000']]
        ```
        
        
        ### .to_dict()
        
        ```python
        report = client.reports().post(data=body)
        print(report().to_dict())
        # list[dict]
        # [..., {'Date': '2019-09-02', 'CampaignId': '338151', 'Clicks': '12578', 'Cost': 9210750000'}]
        ```
        
        
        ### .to_columns()
        
        ```python
        report = client.reports().post(data=body)
        print(report().to_columns())
        # list[list[str], list[str], list[str], list[str]]
        # [[..., '2019-09-02'], [..., '338151'], [..., '12578'], [..., '9210750000']]
        ```
        
        
        ## Features
        
        Information about the resource.
        ```python
        client.campaigns().help()
        ```
        
        Open resource documentation
        ```python
        client.campaigns().open_docs()
        ```
        
        Send a request in the browser.
        ```python
        client.campaigns().open_in_browser()
        ```
        
        
        ## Dependences
        - requests
        - [tapi_wrapper](https://github.com/pavelmaksimov/tapi-wrapper)
        
        
        ## CHANGELOG
        v2021.5.25
        - Add stub file (syntax highlighting)
        - Add methods 'iter_dicts', 'to_dicts'
        
        
        ## Автор
        Павел Максимов
        
        Связаться со мной можно в
        [Телеграм](https://t.me/pavel_maksimow)
        и в
        [Facebook](https://www.facebook.com/pavel.maksimow)
        
        Удачи тебе, друг! Поставь звездочку ;)
        
Keywords: tapi,wrapper,yandex,metrika,api,direct,яндекс,директ,апи
Platform: UNKNOWN
Description-Content-Type: text/markdown
