Usage

API method request example

Several types of APIs are implemented in this module. Each of them is needed for certain purposes, but they are all united by the way of accessing the VK API. After initializing the class, you can call any method. Let’s try to figure out what’s going on here:

>>> import vk
>>> api = vk.API(access_token='...', v='5.131')
>>> print(api.users.get(user_ids=1))
[{'id': 1, 'first_name': 'Павел', 'last_name': 'Дуров', ... }]

It gets user info with user id equal to 1. vk.api.APINamespace object is used to create API request and send it via original vk.session.API class object (or another), which in turn, manages access token, sends API request, gets JSON response, parses and returns it.

More formally, this forms the following POST request to the VK API:

https://api.vk.com/method/users.get?user_ids=1&access_token=…&v=5.131

vk.API

class vk.session.API(*args, **kwargs)[source]

The simplest VK API implementation. Can process any API method that can be called from the server

Parameters

access_token (Optional[str]) – Access token for API requests obtained by any means (see documentation). Optional when using InteractiveMixin
**kwargs (any) – Additional parameters, which will be passed to each request. The most useful is v - API version and lang - language of responses (see documentation)

Example

>>> import vk
>>> api = vk.API(access_token='...', v='5.131')
>>> print(api.users.get(user_ids=1))
[{'id': 1, 'first_name': 'Павел', 'last_name': 'Дуров', ... }]

vk.UserAPI

class vk.session.UserAPI(*args, **kwargs)[source]

Subclass of vk.session.API. It differs only in that it can get access token using user credentials (Implicit flow authorization).

Warning

This implementation uses the web version of VK to log in and receive cookies, and then obtains an access token through Implicit flow authorization. In the future, VK may change the approach to authorization (for example, replace it with VK ID) and maintaining operability will become quite a difficult task, and most likely it will be deprecated. Use vk.session.DirectUserAPI instead

Parameters

user_login (Optional[str]) – User login, optional when using InteractiveMixin
user_password (Optional[str]) – User password, optional when using InteractiveMixin
client_id (Optional[int]) – ID of the application to authorize with, defaults to “VK Admin” app ID
scope (Optional[Union[str, int]]) – Access rights you need. Can be passed comma-separated list of scopes, or bitmask sum all of them (see official documentation). Defaults to ‘offline’
**kwargs (any) – Additional parameters, which will be passed to each request. The most useful is v - API version and lang - language of responses (see documentation)

Example

>>> import vk
>>> api = vk.UserAPI(
...     user_login='...',
...     user_password='...',
...     scope='offline,wall',
...     v='5.131'
... )
>>> print(api.users.get(user_ids=1))
[{'id': 1, 'first_name': 'Павел', 'last_name': 'Дуров', ... }]

get_auth_check_code()[source]

Callback to retrieve authentication check code (if account supports 2FA). Default behavior is to raise exception, redefine in a subclass

Returns: The authentication check code can be obtained in the sent SMS, using Google Authenticator (or another authenticator), or it can be one of ten backup codes

vk.DirectUserAPI

class vk.session.DirectUserAPI(*args, **kwargs)[source]

Subclass of vk.session.UserAPI. Can get access token using user credentials (through Direct authorization).

vk.CommunityAPI

class vk.session.CommunityAPI(*args, **kwargs)[source]

Subclass of vk.session.UserAPI. Can get community access token using user credentials (Implicit flow authorization for communities). To select a community on behalf of which to make request to the API method, you can pass the group_id param (defaults to the first community from the passed list)

Warning

This implementation uses the web version of VK to log in and receive cookies, and then obtains an access tokens through Implicit flow authorization for communities. In the future, VK may change the approach to authorization (for example, replace it with VK ID) and maintaining operability will become quite a difficult task, and most likely it will be deprecated.

You can create a group token on the management page: Community -> Management -> Working with API -> Access Tokens -> Create a token (bonus - the token has no expiration date)

Parameters

user_login (Optional[str]) – User login, optional when using InteractiveMixin
user_password (Optional[str]) – User password, optional when using InteractiveMixin
group_ids (List[int]) – List of community IDs to be authorized
client_id (Optional[int]) – ID of the application to authorize with, defaults to “VK Admin” app ID
scope (Optional[Union[str, int]]) – Access rights you need. Can be passed comma-separated list of scopes, or bitmask sum all of them (see official documentation). Defaults to None. Be careful, only manage, messages, photos, docs, wall and stories are available for communities
**kwargs (any) – Additional parameters, which will be passed to each request. The most useful is v - API version and lang - language of responses (see documentation)

Example

>>> import vk
>>> api = vk.CommunityAPI(
...     user_login='...',
...     user_password='...',
...     group_ids=[123456, 654321],
...     scope='messages',
...     v='5.131'
... )
>>> print(api.users.get(user_ids=1))
[{'id': 1, 'first_name': 'Павел', 'last_name': 'Дуров', ... }]
>>> print(api.users.get(group_id=654321, user_ids=1))
[{'id': 1, 'first_name': 'Павел', 'last_name': 'Дуров', ... }]