dataforseo-client 2.1.7__tar.gz → 2.1.8__tar.gz

dataforseo_client-2.1.8/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: dataforseo-client
+Version: 2.1.8
+Summary: DataForSEO API documentation
+Home-page: https://github.com/dataforseo/PythonClient
+Author: DataForSeo
+Author-email: info@dataforseo.com
+Keywords: OpenAPI,DataForSEO,DataForSEO API documentation
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3<2.2.3,>=1.25.3
+Requires-Dist: python-dateutil
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.7.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+## OVERVIEW
+
+This is a Python client providing you, as a developer, with a tool for obtaining the necessary data from DataForSEO APIs. You don't have to figure out how to make a request and process a response - all that is readily available in this client.
+
+[![GitHub issues](https://img.shields.io/github/issues/dataforseo/PythonClient.svg)](https://github.com/dataforseo/PythonClient/issues)
+[![GitHub license](https://img.shields.io/github/license/dataforseo/PythonClient.svg)](https://github.com/dataforseo/PythonClient)
+
+DataForSEO API uses REST technology for interchanging data between your application and our service. The data exchange is made through the widely used HTTP protocol, which allows using our API with almost any programming language.
+
+Client contains 12 sections (aka APIs):
+
+- AI Optimization API ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/ai_optimization_api.md) | [api docs](https://docs.dataforseo.com/v3/ai_optimization/overview/))
+- SERP ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/serp_api.md) | [api docs](https://docs.dataforseo.com/v3/serp/overview/?bash))
+- Keywords Data ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/keywords_data_api.md) | [api docs](https://docs.dataforseo.com/v3/keywords_data/overview/?bash))
+- Domain Analytics ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/domain_analytics_api.md) | [api docs](https://docs.dataforseo.com/v3/domain_analytics/overview/?bash))
+- DataForSEO Labs ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/dataforseo_labs_api.md) | [api docs](https://docs.dataforseo.com/v3/dataforseo_labs/overview/?bash))
+- Backlinks ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/backlinks_api.md) | [api docs](https://docs.dataforseo.com/v3/backlinks/overview/?bash))
+- OnPage ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/on_page_api.md) | [api docs](https://docs.dataforseo.com/v3/on_page/overview/?bash))
+- Content Analysis ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/content_analysis_api.md) | [api docs](https://docs.dataforseo.com/v3/content_analysis/overview/?bash))
+- Merchant ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/merchant_api.md) | [api docs](https://docs.dataforseo.com/v3/merchant/overview/?bash))
+- AppData ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/app_data_api.md) | [api docs](https://docs.dataforseo.com/v3/app_data/overview/?bash))
+- Business Data ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/business_data_api.md) | [api docs](https://docs.dataforseo.com/v3/business_data/overview/?bash))
+- Appendix ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/appendix_api.md) | [api docs](https://docs.dataforseo.com/v3/appendix/user_data/?bash))
+
+API Contains 2 types of requests:
+
+1) Live (Simple HTTP request/response message)
+2) Task-based (Requires sending a 'Task' entity to execute, waiting until the 'Task' status is ready, and getting the 'Task' result in a special endpoint. Usually, it is represented by 3 types of endpoints: 'TaskPost', 'TaskReady', and 'TaskGet')
+   For more details - please follow [here](https://docs.dataforseo.com/v3/?bash)
+
+## YAML Spec
+
+Our API description is based on the OpenAPI [syntax](https://spec.openapis.org/oas/v3.1.0) in YAML format. The YAML file attached to the project [here](https://github.com/dataforseo/OpenApiDocumentation)
+
+## Documentation
+The documentation for code objects, formatted in Markdown (.md) is available [here](https://github.com/dataforseo/PythonClient/blob/master/docs/). Official documentation for DataForSEO API is available [here](https://docs.dataforseo.com/v3/?bash).
+
+## Code generation
+
+Code generated using the [openapi generator cli](https://openapi-generator.tech/docs/installation/)
+
+## Install package from nuget.org
+
+```bash
+pip install dataforseo-client 
+```
+
+## Examples of usage
+
+Example of live request
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_live_advanced_request_info import SerpGoogleOrganicLiveAdvancedRequestInfo
+from pprint import pprint
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        api_response = serp_api.google_organic_live_advanced([SerpGoogleOrganicLiveAdvancedRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```
+
+Example of Task-Based request
+
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_task_post_request_info import SerpGoogleOrganicTaskPostRequestInfo
+from pprint import pprint
+import time
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+
+def GoogleOrganicTaskReady(id):
+    result = serp_api.google_organic_tasks_ready()
+    return any(any(xx.id == id for xx in (x.result or [])) for x in (result.tasks or []))
+
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        task_post = serp_api.google_organic_task_post([SerpGoogleOrganicTaskPostRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+
+        task_id = task_post.tasks[0].id
+
+        start_time = time.time()
+
+        while GoogleOrganicTaskReady(task_id) is not True and (time.time() - start_time) < 60:
+            time.sleep(1)
+
+        api_response = serp_api.google_organic_task_get_advanced(id=task_id)
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```

dataforseo_client-2.1.8/README.md

@@ -0,0 +1,120 @@
+## OVERVIEW
+
+This is a Python client providing you, as a developer, with a tool for obtaining the necessary data from DataForSEO APIs. You don't have to figure out how to make a request and process a response - all that is readily available in this client.
+
+[![GitHub issues](https://img.shields.io/github/issues/dataforseo/PythonClient.svg)](https://github.com/dataforseo/PythonClient/issues)
+[![GitHub license](https://img.shields.io/github/license/dataforseo/PythonClient.svg)](https://github.com/dataforseo/PythonClient)
+
+DataForSEO API uses REST technology for interchanging data between your application and our service. The data exchange is made through the widely used HTTP protocol, which allows using our API with almost any programming language.
+
+Client contains 12 sections (aka APIs):
+
+- AI Optimization API ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/ai_optimization_api.md) | [api docs](https://docs.dataforseo.com/v3/ai_optimization/overview/))
+- SERP ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/serp_api.md) | [api docs](https://docs.dataforseo.com/v3/serp/overview/?bash))
+- Keywords Data ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/keywords_data_api.md) | [api docs](https://docs.dataforseo.com/v3/keywords_data/overview/?bash))
+- Domain Analytics ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/domain_analytics_api.md) | [api docs](https://docs.dataforseo.com/v3/domain_analytics/overview/?bash))
+- DataForSEO Labs ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/dataforseo_labs_api.md) | [api docs](https://docs.dataforseo.com/v3/dataforseo_labs/overview/?bash))
+- Backlinks ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/backlinks_api.md) | [api docs](https://docs.dataforseo.com/v3/backlinks/overview/?bash))
+- OnPage ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/on_page_api.md) | [api docs](https://docs.dataforseo.com/v3/on_page/overview/?bash))
+- Content Analysis ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/content_analysis_api.md) | [api docs](https://docs.dataforseo.com/v3/content_analysis/overview/?bash))
+- Merchant ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/merchant_api.md) | [api docs](https://docs.dataforseo.com/v3/merchant/overview/?bash))
+- AppData ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/app_data_api.md) | [api docs](https://docs.dataforseo.com/v3/app_data/overview/?bash))
+- Business Data ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/business_data_api.md) | [api docs](https://docs.dataforseo.com/v3/business_data/overview/?bash))
+- Appendix ([source docs](https://github.com/dataforseo/PythonClient/blob/master/docs/appendix_api.md) | [api docs](https://docs.dataforseo.com/v3/appendix/user_data/?bash))
+
+API Contains 2 types of requests:
+
+1) Live (Simple HTTP request/response message)
+2) Task-based (Requires sending a 'Task' entity to execute, waiting until the 'Task' status is ready, and getting the 'Task' result in a special endpoint. Usually, it is represented by 3 types of endpoints: 'TaskPost', 'TaskReady', and 'TaskGet')
+   For more details - please follow [here](https://docs.dataforseo.com/v3/?bash)
+
+## YAML Spec
+
+Our API description is based on the OpenAPI [syntax](https://spec.openapis.org/oas/v3.1.0) in YAML format. The YAML file attached to the project [here](https://github.com/dataforseo/OpenApiDocumentation)
+
+## Documentation
+The documentation for code objects, formatted in Markdown (.md) is available [here](https://github.com/dataforseo/PythonClient/blob/master/docs/). Official documentation for DataForSEO API is available [here](https://docs.dataforseo.com/v3/?bash).
+
+## Code generation
+
+Code generated using the [openapi generator cli](https://openapi-generator.tech/docs/installation/)
+
+## Install package from nuget.org
+
+```bash
+pip install dataforseo-client 
+```
+
+## Examples of usage
+
+Example of live request
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_live_advanced_request_info import SerpGoogleOrganicLiveAdvancedRequestInfo
+from pprint import pprint
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        api_response = serp_api.google_organic_live_advanced([SerpGoogleOrganicLiveAdvancedRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```
+
+Example of Task-Based request
+
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_task_post_request_info import SerpGoogleOrganicTaskPostRequestInfo
+from pprint import pprint
+import time
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+
+def GoogleOrganicTaskReady(id):
+    result = serp_api.google_organic_tasks_ready()
+    return any(any(xx.id == id for xx in (x.result or [])) for x in (result.tasks or []))
+
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        task_post = serp_api.google_organic_task_post([SerpGoogleOrganicTaskPostRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+
+        task_id = task_post.tasks[0].id
+
+        start_time = time.time()
+
+        while GoogleOrganicTaskReady(task_id) is not True and (time.time() - start_time) < 60:
+            time.sleep(1)
+
+        api_response = serp_api.google_organic_task_get_advanced(id=task_id)
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```

dataforseo_client-2.1.8/dataforseo_client/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: dataforseo-python-client
+description: Use the DataForSEO Python client (pip package dataforseo-client, module dataforseo_client) to call DataForSEO API v3 (SERP, Keywords Data, DataForSEO Labs, Backlinks, OnPage, AI Optimization, etc.). Read this before exploring the code; it explains the layout, naming rules and how to find an endpoint without reading the huge generated files.
+---
+
+# DataForSEO Python client
+
+Generated, typed (pydantic v2) Python client for DataForSEO API v3.
+Every API endpoint is one method; every request/response body is one model class.
+
+- Package: `pip install dataforseo-client`, import as `dataforseo_client`
+- HTTP: `urllib3`, synchronous
+- Base URL: `https://api.dataforseo.com` (sandbox with free dummy data: `https://sandbox.dataforseo.com`)
+- Auth: HTTP Basic with the DataForSEO API login and password (not the dashboard password)
+
+## Do not read generated code in full
+
+The client is generated from an OpenAPI spec and is very large (thousands of model files, `api/*_api.py` files up to ~1 MB, very long field descriptions in every model). Never open files whole. Derive names with the rules below and use targeted search (grep) only to confirm them.
+
+## Layout
+
+Paths are relative to the `dataforseo_client` package (a top-level folder in the repository; after `pip install` it is `site-packages/dataforseo_client/`, where a copy of this file also lives):
+
+```
+configuration.py           Configuration (credentials, host, proxy, ssl, retries)
+api_client.py              ApiClient (HTTP transport, context manager)
+exceptions.py              ApiException and subclasses
+api/<section>_api.py       one class per API section, one method per endpoint
+models/<class_name>.py     one pydantic model per file (snake_case file, PascalCase class)
+```
+
+Sections (the `api/` folder is the source of truth): `SerpApi`, `KeywordsDataApi`, `DataforseoLabsApi`, `DomainAnalyticsApi`, `BacklinksApi`, `OnPageApi`, `ContentAnalysisApi`, `AiOptimizationApi`, `MerchantApi`, `AppDataApi`, `BusinessDataApi`, `AppendixApi`.
+
+## Naming rules (derive names instead of searching)
+
+Endpoint path `/v3/<section>/<rest>` maps to:
+
+| What | Rule | Example for `/v3/serp/google/organic/live/advanced` |
+|---|---|---|
+| API class / module | `<Section>Api` in `api/<section>_api.py` | `SerpApi` in `dataforseo_client.api.serp_api` |
+| Method | snake_case of `<rest>` (usually) | `google_organic_live_advanced` |
+| Request model | `<Section><Rest>RequestInfo` | `SerpGoogleOrganicLiveAdvancedRequestInfo` |
+| Response model | `<Section><Rest>ResponseInfo` | `SerpGoogleOrganicLiveAdvancedResponseInfo` |
+| Task item | `<Section><Rest>TaskInfo` | `SerpGoogleOrganicLiveAdvancedTaskInfo` |
+| Result item | `<Section><Rest>ResultInfo` | `SerpGoogleOrganicLiveAdvancedResultInfo` |
+| Model module | snake_case of class name | `dataforseo_client.models.serp_google_organic_live_advanced_request_info` |
+
+Model names follow the rule strictly. Method names sometimes keep the section prefix (e.g. `dataforseo_labs_id_list`), so confirm the method with one search (the pattern also matches a prefixed name):
+
+```bash
+grep -n "def [a-z_]*google_organic_live_advanced(" api/serp_api.py
+```
+
+Model fields and their descriptions (required/optional, allowed values, limits) are in `Field(description=...)`. The lines are very long, so list field names first and then grep only the fields you need:
+
+```bash
+grep -oE "^    [a-z_0-9]+:" models/serp_google_organic_live_advanced_request_info.py   # field names
+grep -n "^    location_code:" models/serp_google_organic_live_advanced_request_info.py  # one field with description
+```
+
+## Method shapes
+
+- `POST` endpoints: `x(list_optional_x_request_info: List[XRequestInfo]) -> XResponseInfo`, the body is always a list of tasks. Pass it positionally.
+- `GET` endpoints: `x() -> XResponseInfo` or `x(id)` (task id for `task_get_*`, `country` for locations etc.).
+- Every method also has `x_with_http_info(...)` (returns `ApiResponse` with `status_code`, `headers`, `data`) and `x_without_preload_content(...)` (raw urllib3 response).
+- Every method accepts `_request_timeout` (seconds or `(connect, read)` tuple) and `_headers`.
+
+## Setup
+
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+
+configuration = dfs_config.Configuration(username="API_LOGIN", password="API_PASSWORD")
+# sandbox: dfs_config.Configuration(host="https://sandbox.dataforseo.com", username=..., password=...)
+
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    serp_api = SerpApi(api_client)
+    ...
+```
+
+Create one `ApiClient` and reuse it for all section classes.
+
+## Live request (result in the same call)
+
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_live_advanced_request_info import SerpGoogleOrganicLiveAdvancedRequestInfo
+from pprint import pprint
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        api_response = serp_api.google_organic_live_advanced([SerpGoogleOrganicLiveAdvancedRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```
+
+## Task-based request (post -> wait -> get)
+
+```python
+from dataforseo_client import configuration as dfs_config, api_client as dfs_api_provider
+from dataforseo_client.api.serp_api import SerpApi
+from dataforseo_client.rest import ApiException
+from dataforseo_client.models.serp_google_organic_task_post_request_info import SerpGoogleOrganicTaskPostRequestInfo
+from pprint import pprint
+import time
+
+# Configure HTTP basic authorization: basicAuth
+configuration = dfs_config.Configuration(username='USERNAME',password='PASSWORD')
+
+def GoogleOrganicTaskReady(id):
+    result = serp_api.google_organic_tasks_ready()
+    return any(any(xx.id == id for xx in (x.result or [])) for x in (result.tasks or []))
+
+with dfs_api_provider.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    serp_api = SerpApi(api_client)
+
+    try:
+
+        task_post = serp_api.google_organic_task_post([SerpGoogleOrganicTaskPostRequestInfo(
+            language_name="English",
+            location_name="United States",
+            keyword="albert einstein"
+        )])
+
+        task_id = task_post.tasks[0].id
+
+        start_time = time.time()
+
+        while GoogleOrganicTaskReady(task_id) is not True and (time.time() - start_time) < 60:
+            time.sleep(1)
+
+        api_response = serp_api.google_organic_task_get_advanced(id=task_id)
+        
+        pprint(api_response)
+    
+    except ApiException as e:
+        print("Exception: %s\n" % e)
+```
+
+Instead of polling you can set `postback_url` / `pingback_url` in the task request.
+
+## Response envelope (same for every endpoint)
+
+```
+XResponseInfo
+  version, status_code, status_message, time, cost, tasks_count, tasks_error
+  tasks: List[XTaskInfo]
+    XTaskInfo
+      id, status_code, status_message, time, cost, result_count, path, data (echo of the request)
+      result: List[XResultInfo]   # endpoint specific payload, often with items
+```
+
+- `status_code == 20000` means OK (both top-level and per task); `20100` = task created; `4xxxx`/`5xxxx` = errors. Always check the per-task `status_code`: the HTTP status is usually 200 even when a task failed.
+- All fields are `Optional`; guard lists with `or []`.
+- Models are pydantic: `to_dict()`, `to_json()`, `from_dict()`, `from_json()` are available.
+
+## Polymorphic items
+
+Lists like `items` are typed as a base class (e.g. `BaseSerpApiElementItem`) and deserialized into concrete subclasses by the JSON `type` field (`organic` -> `OrganicSerpElementItem`, `paid` -> `PaidSerpElementItem`, `featured_snippet` -> `FeaturedSnippetSerpElementItem`, ...). Use `isinstance`. The mapping is in `__discriminator_value_class_map` of the base model file; grep there instead of reading it.
+
+## Errors
+
+`dataforseo_client.exceptions` (also re-exported from `dataforseo_client.rest`): `ApiException` with `status`, `reason`, `body`, `headers`; subclasses `BadRequestException` (400), `UnauthorizedException` (401), `ForbiddenException` (403), `NotFoundException` (404), `ServiceException` (5xx). Client-side validation errors raise pydantic `ValidationError`.
+
+## Useful facts
+
+- Location / language codes: `location_code=2840` (United States), `language_code="en"`. Full lists come from endpoints like `SerpApi.google_locations()` / `google_languages()` (and similar per section).
+- Most Live endpoints accept one task per request; Task POST endpoints accept many tasks (up to 100) in one call.
+- `task_get_*` has several variants (`regular`, `advanced`, `html`); use the one matching the data you need.
+- Field semantics, allowed values and limits: the `description` of the model field (it comes from the official API docs).
+
+## External documentation (last resort)
+
+Use https://dataforseo.com/llms.txt only when this file or generated code do not answer the question (for example pricing, account limits or endpoint behaviour that is not described locally). Everything needed to write client code is already in this library.
+
+`llms.txt` is a large (~200 KB) index of links to per-endpoint Markdown pages (`https://docs.dataforseo.com/v3/...md`). Do not read it whole: search it for the endpoint path or name and fetch only the linked page.