| Name | ya-business-api JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | Yandex business API client |
| upload_time | 2024-07-25 18:10:21 |
| maintainer | None |
| docs_url | None |
| author | Kirill_Lekhov |
| requires_python | <4.0.0,>=3.8.1 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Yandex business (sprav) API client [](https://codecov.io/gh/Kirill-Lekhov/ya-business-api)
## Installation
```sh
# Sync only mode
pip install ya_business_api[sync]
# Async only mode
pip install ya_business_api[async]
# All modes
pip install ya_business_api[all]
```
## Instantiating
There are several ways to work with the API (synchronous and asynchronous).
Both interfaces have the same signatures, the only difference is the need to use async/await keywords.
```python
from ya_business_api.sync_api import SyncAPI # Sync mode
from ya_business_api.async_api import AsyncAPI # Async mode
def main() -> None:
api = SyncAPI.build(
session_id=...,
session_id2=...,
csrf_token=..., # Optional
)
# Do things here...
async def main() -> None:
api = await AsyncAPI.build(
session_id=...,
session_id2=...,
csrf_token=..., # Optional
)
# Do things here...
await api.session.close()
```
### Where can I get the data for the client?
On the reviews page (https://yandex.ru/sprav/.../edit/reviews), open the developer console (usually `F12`) from the first request, copy values of cookies (`Session_id` and `sessionid2`).
In the console, run the following script:
```JS
function getData() {
console.info({
"CSRFToken": window?.__PRELOAD_DATA?.initialState?.env?.csrf,
"PermanentId": window?.__PRELOAD_DATA?.initialState?.edit?.company?.permanent_id,
})
}
getData()
/**
* {CSRFToken: "...", PermanentId: 00000000000}
*/
```
### ⚠️WARNING⚠️
1. The `PermanentId` belong to certain companies and cannot be used to respond to reviews from another company.
2. The `CSRFToken` can be fetched automatically if it is not explicitly specified when calling the build method.
## Reviews
### Reviews fetching
* Async mode support: ✅;
* Validation disabling: ✅.
```python
# Sync mode
from ya_business_api.sync_api import SyncAPI
from ya_business_api.reviews.dataclasses.requests import ReviewsRequest
api = SyncAPI.build(...)
request = ReviewsRequest(
permanent_id=<permanent_id>,
ranking=Ranking.BY_RATING_DESC, # Optional
unread=True, # Optional
page=5, # Optional
)
response = api.reviews.get_reviews(
request,
raw=False, # Optional
)
```
### Answering to reviews
* Async mode support: ✅;
* Validation disabling: ❌.
```python
from ya_business_api.sync_api import SyncAPI
from ya_business_api.reviews.dataclasses.requests import AnswerRequest
api = SyncAPI.build(...)
reviews = api.reviews.get_reviews()
request = AnswerRequest(
review_id=reviews.list.items[0].id,
text="Thank you!",
reviews_csrf_token=reviews.list.csrf_token,
answer_csrf_token=reviews.list.items[0].business_answer_csrf_token,
)
response = api.reviews.send_answer(request)
```
## Companies
### Receiving companies
* Async mode support: ✅;
* Validation disabling: ✅.
```python
from ya_business_api.sync_api import SyncAPI
from ya_business_api.companies.dataclasses.requests import CompaniesRequest
api = SyncAPI.build(...)
request = CompaniesRequest(filter="My Company", page=5)
response = api.companies.get_companies(
request, # Optional
raw=False, # Optional
)
```
### Receiving company chains
Some companies have several branches, in such cases the company will have the "chain" type.
This method will allow you to get a list of all branches.
* Async mode support: ✅;
* Validation disabling: ✅.
```python
from ya_business_api.sync_api import SyncAPI
from ya_business_api.companies.dataclasses.request import ChainListRequest
api = SyncAPI.build(...)
request = ChainListRequest(
tycoon_id=<tycoon_id>, # Can be found in the Company dataclass.
geo_id=0, # Optional.
page=1, # Optional
)
response = api.companies.get_chain_list(
request, # Optional
raw=False, # Optional
)
```
#### ⚠️WARNING⚠️
Raw response of this method is HTML text.
## Service
### Receiving CSRF token
* Async mode support: ✅;
* Validation disabling: ❌.
```python
from ya_business_api.sync_api import SyncAPI
api = SyncAPI.build(...)
csrf_token = api.service.get_csrf_token()
```
## Shortcuts
### Answers deleting
```python
api.reviews.send_answer(AnswerRequest(text="", ...))
```
### Automatic closing of the session (async mode)
```python
async with await AsyncAPI.make_session(session_id=..., session_id2=...) as session:
api = AsyncAPI(permanent_id=..., csrf_token=..., session=session)
...
```
## Examples
### Getting the number of reviews asynchronously
```python
from ya_business_api.async_api import AsyncAPI
from ya_business_api.companies.dataclasses.requests import ChainListRequest
from ya_business_api.companies.dataclasses.chain_list import CompanyCardWithPhoto
from ya_business_api.reviews.dataclasses.requests import ReviewsRequest
api = await AsyncAPI.build(...)
try:
companies_response = await api.companies.get_companies()
open_companies = filter(lambda x: x.publishing_status != "closed", companies_response.list_companies)
for company in open_companies:
page = 1
chain_list_request = ChainListRequest(tycoon_id=company.tycoon_id, page=page)
chain_list_response = await api.companies.get_chain_list(chain_list_request)
while len(chain_list_response.company_cards):
company_cards = [i for i in chain_list_response.company_cards if isinstance(i, CompanyCardWithPhoto)]
# Only company cards with photo contains permalink
# It is possible that the branch also contains branches, but this is not taken into account in this guide
for card in company_cards:
reviews_request = ReviewsRequest(permanent_id=card.permalink)
reviews_response = await api.reviews.get_reviews(reviews_request)
print(company.permanent_id, card.permalink, reviews_response.list.pager.total)
page += 1
chain_list_request = ChainListRequest(tycoon_id=company.tycoon_id, page=page)
chain_list_response = await api.companies.get_chain_list(chain_list_request)
finally:
await api.session.close()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ya-business-api",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": null,
"keywords": null,
"author": "Kirill_Lekhov",
"author_email": "kirill.lekhov@mail.ru",
"download_url": "https://files.pythonhosted.org/packages/49/34/02813d5b8f5382de79b57ab66e9e0ef5e775078d5fbd399d5420fb7f6857/ya_business_api-1.3.0.tar.gz",
"platform": null,
"description": "# Yandex business (sprav) API client [](https://codecov.io/gh/Kirill-Lekhov/ya-business-api)\n\n## Installation\n```sh\n# Sync only mode\npip install ya_business_api[sync]\n# Async only mode\npip install ya_business_api[async]\n# All modes\npip install ya_business_api[all]\n```\n\n## Instantiating\nThere are several ways to work with the API (synchronous and asynchronous).\nBoth interfaces have the same signatures, the only difference is the need to use async/await keywords.\n\n```python\nfrom ya_business_api.sync_api import SyncAPI\t\t# Sync mode\nfrom ya_business_api.async_api import AsyncAPI\t\t# Async mode\n\n\ndef main() -> None:\n\tapi = SyncAPI.build(\n\t\tsession_id=...,\n\t\tsession_id2=...,\n\t\tcsrf_token=...,\t\t# Optional\n\t)\n\n\t# Do things here...\n\n\nasync def main() -> None:\n\tapi = await AsyncAPI.build(\n\t\tsession_id=...,\n\t\tsession_id2=...,\n\t\tcsrf_token=...,\t\t# Optional\n\t)\n\n\t# Do things here...\n\n\tawait api.session.close()\n```\n\n### Where can I get the data for the client?\nOn the reviews page (https://yandex.ru/sprav/.../edit/reviews), open the developer console (usually `F12`) from the first request, copy values of cookies (`Session_id` and `sessionid2`).\n\nIn the console, run the following script:\n```JS\nfunction getData() {\n\tconsole.info({\n\t\t\"CSRFToken\": window?.__PRELOAD_DATA?.initialState?.env?.csrf,\n\t\t\"PermanentId\": window?.__PRELOAD_DATA?.initialState?.edit?.company?.permanent_id,\n\t})\n}\n\ngetData()\n\n/**\n * {CSRFToken: \"...\", PermanentId: 00000000000}\n*/\n```\n\n### \u26a0\ufe0fWARNING\u26a0\ufe0f\n1. The `PermanentId` belong to certain companies and cannot be used to respond to reviews from another company.\n2. The `CSRFToken` can be fetched automatically if it is not explicitly specified when calling the build method.\n\n## Reviews\n### Reviews fetching\n* Async mode support: \u2705;\n* Validation disabling: \u2705.\n```python\n# Sync mode\nfrom ya_business_api.sync_api import SyncAPI\nfrom ya_business_api.reviews.dataclasses.requests import ReviewsRequest\n\n\napi = SyncAPI.build(...)\nrequest = ReviewsRequest(\n\tpermanent_id=<permanent_id>,\n\tranking=Ranking.BY_RATING_DESC,\t\t# Optional\n\tunread=True,\t\t\t\t\t\t# Optional\n\tpage=5,\t\t\t\t\t\t\t\t# Optional\n)\nresponse = api.reviews.get_reviews(\n\trequest,\n\traw=False,\t\t# Optional\n)\n```\n\n### Answering to reviews\n* Async mode support: \u2705;\n* Validation disabling: \u274c.\n```python\nfrom ya_business_api.sync_api import SyncAPI\nfrom ya_business_api.reviews.dataclasses.requests import AnswerRequest\n\n\napi = SyncAPI.build(...)\nreviews = api.reviews.get_reviews()\nrequest = AnswerRequest(\n\treview_id=reviews.list.items[0].id,\n\ttext=\"Thank you!\",\n\treviews_csrf_token=reviews.list.csrf_token,\n\tanswer_csrf_token=reviews.list.items[0].business_answer_csrf_token,\n)\nresponse = api.reviews.send_answer(request)\n```\n\n## Companies\n### Receiving companies\n* Async mode support: \u2705;\n* Validation disabling: \u2705.\n```python\nfrom ya_business_api.sync_api import SyncAPI\nfrom ya_business_api.companies.dataclasses.requests import CompaniesRequest\n\n\napi = SyncAPI.build(...)\nrequest = CompaniesRequest(filter=\"My Company\", page=5)\nresponse = api.companies.get_companies(\n\trequest,\t\t# Optional\n\traw=False,\t\t# Optional\n)\n```\n\n### Receiving company chains\nSome companies have several branches, in such cases the company will have the \"chain\" type.\nThis method will allow you to get a list of all branches.\n\n\n\n* Async mode support: \u2705;\n* Validation disabling: \u2705.\n```python\nfrom ya_business_api.sync_api import SyncAPI\nfrom ya_business_api.companies.dataclasses.request import ChainListRequest\n\n\napi = SyncAPI.build(...)\nrequest = ChainListRequest(\n\ttycoon_id=<tycoon_id>,\t\t# Can be found in the Company dataclass.\n\tgeo_id=0,\t\t\t\t\t# Optional.\n\tpage=1,\t\t\t\t\t\t# Optional\n)\nresponse = api.companies.get_chain_list(\n\trequest,\t\t# Optional\n\traw=False,\t\t# Optional\n)\n```\n\n#### \u26a0\ufe0fWARNING\u26a0\ufe0f\nRaw response of this method is HTML text.\n\n## Service\n### Receiving CSRF token\n* Async mode support: \u2705;\n* Validation disabling: \u274c.\n```python\nfrom ya_business_api.sync_api import SyncAPI\n\n\napi = SyncAPI.build(...)\ncsrf_token = api.service.get_csrf_token()\n```\n\n## Shortcuts\n### Answers deleting\n```python\napi.reviews.send_answer(AnswerRequest(text=\"\", ...))\n```\n\n### Automatic closing of the session (async mode)\n```python\nasync with await AsyncAPI.make_session(session_id=..., session_id2=...) as session:\n\tapi = AsyncAPI(permanent_id=..., csrf_token=..., session=session)\n\t...\n```\n\n## Examples\n### Getting the number of reviews asynchronously\n```python\nfrom ya_business_api.async_api import AsyncAPI\nfrom ya_business_api.companies.dataclasses.requests import ChainListRequest\nfrom ya_business_api.companies.dataclasses.chain_list import CompanyCardWithPhoto\nfrom ya_business_api.reviews.dataclasses.requests import ReviewsRequest\n\n\napi = await AsyncAPI.build(...)\n\ntry:\n\tcompanies_response = await api.companies.get_companies()\n\topen_companies = filter(lambda x: x.publishing_status != \"closed\", companies_response.list_companies)\n\n\tfor company in open_companies:\n\t\tpage = 1\n\t\tchain_list_request = ChainListRequest(tycoon_id=company.tycoon_id, page=page)\n\t\tchain_list_response = await api.companies.get_chain_list(chain_list_request)\n\n\t\twhile len(chain_list_response.company_cards):\n\t\t\tcompany_cards = [i for i in chain_list_response.company_cards if isinstance(i, CompanyCardWithPhoto)]\n\t\t\t# Only company cards with photo contains permalink\n\t\t\t# It is possible that the branch also contains branches, but this is not taken into account in this guide\n\n\t\t\tfor card in company_cards:\n\t\t\t\treviews_request = ReviewsRequest(permanent_id=card.permalink)\n\t\t\t\treviews_response = await api.reviews.get_reviews(reviews_request)\n\t\t\t\tprint(company.permanent_id, card.permalink, reviews_response.list.pager.total)\n\n\t\t\tpage += 1\n\t\t\tchain_list_request = ChainListRequest(tycoon_id=company.tycoon_id, page=page)\n\t\t\tchain_list_response = await api.companies.get_chain_list(chain_list_request)\n\nfinally:\n\tawait api.session.close()\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yandex business API client",
"version": "1.3.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b73ee5d0ecaca24c0a04981d4e06b4fe64cd2387145b0a0f65ade9c59cd81b8",
"md5": "06d2db1f8ae36946ee2a11a2fa2cd3af",
"sha256": "a91287dd0a48471d159690e8043ed5a7ca95e1c26cfc1faab16e63bdb8737d89"
},
"downloads": -1,
"filename": "ya_business_api-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06d2db1f8ae36946ee2a11a2fa2cd3af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 24959,
"upload_time": "2024-07-25T18:10:19",
"upload_time_iso_8601": "2024-07-25T18:10:19.557027Z",
"url": "https://files.pythonhosted.org/packages/8b/73/ee5d0ecaca24c0a04981d4e06b4fe64cd2387145b0a0f65ade9c59cd81b8/ya_business_api-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "493402813d5b8f5382de79b57ab66e9e0ef5e775078d5fbd399d5420fb7f6857",
"md5": "a0959b4a82ed37764451ae4dbede016e",
"sha256": "f405219539e03ba6f102d1e52da41a1bda490e7668de87ee3f060e628bc5a15b"
},
"downloads": -1,
"filename": "ya_business_api-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a0959b4a82ed37764451ae4dbede016e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 14235,
"upload_time": "2024-07-25T18:10:21",
"upload_time_iso_8601": "2024-07-25T18:10:21.105368Z",
"url": "https://files.pythonhosted.org/packages/49/34/02813d5b8f5382de79b57ab66e9e0ef5e775078d5fbd399d5420fb7f6857/ya_business_api-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-25 18:10:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ya-business-api"
}
