axioapi 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- axioapi-1.0.0/LICENSE +21 -0
- axioapi-1.0.0/PKG-INFO +130 -0
- axioapi-1.0.0/README.md +117 -0
- axioapi-1.0.0/pyproject.toml +23 -0
- axioapi-1.0.0/setup.cfg +4 -0
- axioapi-1.0.0/src/axioapi/__init__.py +6 -0
- axioapi-1.0.0/src/axioapi/client.py +84 -0
- axioapi-1.0.0/src/axioapi/errors.py +57 -0
- axioapi-1.0.0/src/axioapi/groups.py +21 -0
- axioapi-1.0.0/src/axioapi/naming.py +6 -0
- axioapi-1.0.0/src/axioapi/operations.json +1961 -0
- axioapi-1.0.0/src/axioapi/registry.py +65 -0
- axioapi-1.0.0/src/axioapi/request_builder.py +56 -0
- axioapi-1.0.0/src/axioapi/responses.py +56 -0
- axioapi-1.0.0/src/axioapi/retry.py +31 -0
- axioapi-1.0.0/src/axioapi/transport.py +39 -0
- axioapi-1.0.0/src/axioapi.egg-info/PKG-INFO +130 -0
- axioapi-1.0.0/src/axioapi.egg-info/SOURCES.txt +19 -0
- axioapi-1.0.0/src/axioapi.egg-info/dependency_links.txt +1 -0
- axioapi-1.0.0/src/axioapi.egg-info/top_level.txt +1 -0
- axioapi-1.0.0/tests/test_client.py +107 -0
axioapi-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AxioAPI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
axioapi-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: axioapi
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Python SDK for the AxioAPI REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API), search API and social scraper APIs. One API key.
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://axioapi.com
|
|
7
|
+
Project-URL: Documentation, https://axioapi.com/docs
|
|
8
|
+
Keywords: api,sdk,seo api,backlink api,keyword api,temp mail api,sms verification api,otp api,email validation api,proxy api,scraper api,search api,serp api,scholar api,translation api,python,axioapi
|
|
9
|
+
Requires-Python: >=3.9
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Dynamic: license-file
|
|
13
|
+
|
|
14
|
+
# AxioAPI Python SDK: temp mail, SMS OTP, email validation, proxy, SEO and backlink API
|
|
15
|
+
|
|
16
|
+
Python client for the [AxioAPI](https://axioapi.com) REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API) and social scraper APIs. One API key, pay per request. No dependencies.
|
|
17
|
+
|
|
18
|
+
<!-- start:begin -->
|
|
19
|
+
## Get started in 3 steps
|
|
20
|
+
|
|
21
|
+
### 1. Get an API key
|
|
22
|
+
|
|
23
|
+
[Create a free account](https://axioapi.com/portal/register), then open [API keys](https://axioapi.com/account/tokens), create a key and copy it. New accounts receive free credits after verification, enough to try every endpoint.
|
|
24
|
+
|
|
25
|
+
Set it as an environment variable (the SDK reads `AXIOAPI_KEY`):
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
export AXIOAPI_KEY=ak_your_key # macOS / Linux
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
```powershell
|
|
32
|
+
$env:AXIOAPI_KEY = "ak_your_key" # Windows PowerShell
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### 2. Install
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install git+https://github.com/axioapi/axioapi-python.git
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Requires Python 3.9+. No dependencies. Once released on PyPI: `pip install axioapi`.
|
|
42
|
+
|
|
43
|
+
### 3. Make your first call
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from axioapi import AxioAPI
|
|
47
|
+
|
|
48
|
+
client = AxioAPI() # reads AXIOAPI_KEY
|
|
49
|
+
print(client.account.limits()) # your plan and rate limits
|
|
50
|
+
print(client.seo.keyword_metrics(keywords=["api gateway"], country="us"))
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Every endpoint works the same way: `client.<group>.<operation>(params)`. See the examples below and the [full reference](https://axioapi.com/docs).
|
|
54
|
+
<!-- start:end -->
|
|
55
|
+
|
|
56
|
+
## More examples
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from axioapi import AxioAPI, RateLimitError, InsufficientCreditsError
|
|
60
|
+
|
|
61
|
+
client = AxioAPI() # or AxioAPI("ak_...")
|
|
62
|
+
|
|
63
|
+
# Keyword data API: volume, CPC and competition for up to 10 keywords per request
|
|
64
|
+
rows = client.seo.keyword_metrics(keywords=["api gateway", "proxy scraper"], country="us")
|
|
65
|
+
|
|
66
|
+
# Backlink API: summary with every data source that answered
|
|
67
|
+
backlinks = client.seo.backlinks_summary(domain="example.com")
|
|
68
|
+
print(backlinks["partial"], backlinks["missing"], list(backlinks["sources"]))
|
|
69
|
+
|
|
70
|
+
# Temp mail API: one inbox per test
|
|
71
|
+
inbox = client.temporary_email.create_inbox(ttl_minutes=10)
|
|
72
|
+
messages = client.temporary_email.list_messages(inbox=inbox["id"])
|
|
73
|
+
|
|
74
|
+
try:
|
|
75
|
+
client.verify.wait(number="+12025550192")
|
|
76
|
+
except RateLimitError as e:
|
|
77
|
+
print("retry in", e.retry_after, "request", e.request_id)
|
|
78
|
+
except InsufficientCreditsError:
|
|
79
|
+
print("top up credits")
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
- `client.<group>.<operation>(**params)` for every endpoint; `client.call("seo.keyword-metrics", ...)` works by capability key. `client.operations()` lists all of them with method, path and credit cost.
|
|
83
|
+
- Returns the `data` field. `client.request("GET", "/api/v1/account/limits", raw=True)` returns the whole envelope.
|
|
84
|
+
- Image and audio endpoints return `bytes`.
|
|
85
|
+
- Options: `AxioAPI(api_key, base_url=..., timeout=30, max_retries=2)`. 429 is retried for all methods; 502/503/504 and network errors only for GET and DELETE.
|
|
86
|
+
|
|
87
|
+
Docs: https://axioapi.com/docs · Guides: https://axioapi.com/guides · License: MIT
|
|
88
|
+
|
|
89
|
+
<!-- seo:start -->
|
|
90
|
+
## What you can build with the Python SDK
|
|
91
|
+
|
|
92
|
+
| Use case | API page | Typical call |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| [Temp mail API](https://axioapi.com/apis/temporary-email): disposable inboxes for signup and password-reset tests | `temporary-email` | create inbox, list messages, read message |
|
|
95
|
+
| [Receive SMS API](https://axioapi.com/apis/sms) and [OTP API](https://axioapi.com/apis/verify): public numbers and "wait for the code" | `sms`, `verify` | list numbers, wait for OTP |
|
|
96
|
+
| [Email validation API](https://axioapi.com/apis/email-validation): syntax, MX and disposable-address checks, plus transactional and outreach email sending | `email` | validate, batch validate, send |
|
|
97
|
+
| [Proxy API](https://axioapi.com/apis/proxy-vpn): sticky and rotating proxy sessions by country | `proxy` | create session, rotate, close |
|
|
98
|
+
| [SEO API](https://axioapi.com/apis/seo): keyword data API (volume, CPC), backlink API, domain overview, on-page audit | `seo` | keyword metrics, backlinks summary |
|
|
99
|
+
| [Search API](https://axioapi.com/apis/search): web, image, news, video, maps and shopping results, AI Overview and autocomplete | `search` | web search, news search |
|
|
100
|
+
| Scholar API: Google Scholar paper search, author profiles and citation formats | `scholar` | search papers, author profile |
|
|
101
|
+
| Text AI: neural translation, text generation and grammar check | `text`, `grammar` | translate, generate, check grammar |
|
|
102
|
+
| Audio and video AI: speech-to-text, text-to-speech, AI image generation, video transcripts and tags | `audio`, `tts`, `ai-image`, `video` | transcribe, text to speech, generate image |
|
|
103
|
+
| YouTube AI summarizer and webpage content extraction | `youtube`, `webpage` | summarize video, extract page |
|
|
104
|
+
| [Coupon API](https://axioapi.com/apis/coupons) and product price history: store promo codes and historical prices | `coupons`, `products`, `ecommerce` | search coupons, price history |
|
|
105
|
+
| DNS, BIN, technology and local lead APIs: DNS records, card BIN lookup, website tech stack, Google Maps business leads | `dns`, `bin`, `tech`, `local` | resolve DNS, BIN lookup, tech profile |
|
|
106
|
+
| [TikTok](https://axioapi.com/apis/social-tiktok), [Facebook](https://axioapi.com/apis/social-facebook), [Instagram](https://axioapi.com/apis/social-instagram), [YouTube](https://axioapi.com/apis/social-youtube), [X (Twitter)](https://axioapi.com/apis/social-twitter), [LinkedIn](https://axioapi.com/apis/social-linkedin) and [Reddit](https://axioapi.com/apis/social-reddit) scraper APIs | `social` | profiles, posts, comments, transcripts |
|
|
107
|
+
|
|
108
|
+
## Guides with working code
|
|
109
|
+
|
|
110
|
+
- [Backlink API: check a domain's backlinks in Python](https://axioapi.com/guides/backlink-api-check-domain-python)
|
|
111
|
+
- [Keyword data API: get search volume and CPC in code](https://axioapi.com/guides/keyword-data-api-volume-cpc)
|
|
112
|
+
- [SEO report API: build a domain ranking report](https://axioapi.com/guides/seo-report-api-domain-ranking)
|
|
113
|
+
- [Test signup emails with Playwright and a temp mail API](https://axioapi.com/guides/playwright-temp-mail-signup-test)
|
|
114
|
+
- [Test OTP flows with a receive SMS API](https://axioapi.com/guides/otp-testing-with-sms-api)
|
|
115
|
+
- [Sticky vs rotating proxy: which one to use](https://axioapi.com/guides/sticky-vs-rotating-proxy)
|
|
116
|
+
|
|
117
|
+
Free tools that need no account: [backlink checker](https://axioapi.com/tools/backlink-checker), [email validator](https://axioapi.com/tools/email-validator), [DNS lookup](https://axioapi.com/tools/dns-lookup), [BIN checker](https://axioapi.com/tools/bin-checker).
|
|
118
|
+
|
|
119
|
+
## FAQ
|
|
120
|
+
|
|
121
|
+
**Is there a Python client for the AxioAPI backlink API and keyword data API?** Yes, this package. `seo.backlinks_summary` returns the backlink summary of a domain with the figures of every data source, and `seo.keyword_metrics` returns search volume, CPC and competition for up to 10 keywords per request.
|
|
122
|
+
|
|
123
|
+
**How do I test signup emails and OTP codes from Python?** Create a disposable inbox with the temp mail API, submit its address in your form and read the message. For SMS codes, call the verify endpoint, which waits for the OTP on a public number and returns it.
|
|
124
|
+
|
|
125
|
+
**How much does it cost?** You pay per request with credits, and each endpoint lists its price on its [API page](https://axioapi.com/apis) and in the OpenAPI spec (`x-credit-cost`). New accounts receive free credits after verification. See [pricing](https://axioapi.com/pricing).
|
|
126
|
+
|
|
127
|
+
**Where is the full reference?** [axioapi.com/docs](https://axioapi.com/docs), the [OpenAPI 3.1 spec](https://axioapi.com/api/v1/openapi.json) and [llms.txt](https://axioapi.com/llms.txt) for AI agents.
|
|
128
|
+
|
|
129
|
+
Vietnamese: [AxioAPI tiếng Việt](https://axioapi.com/vi), [API SEO và API backlink](https://axioapi.com/vi/apis/seo).
|
|
130
|
+
<!-- seo:end -->
|
axioapi-1.0.0/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# AxioAPI Python SDK: temp mail, SMS OTP, email validation, proxy, SEO and backlink API
|
|
2
|
+
|
|
3
|
+
Python client for the [AxioAPI](https://axioapi.com) REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API) and social scraper APIs. One API key, pay per request. No dependencies.
|
|
4
|
+
|
|
5
|
+
<!-- start:begin -->
|
|
6
|
+
## Get started in 3 steps
|
|
7
|
+
|
|
8
|
+
### 1. Get an API key
|
|
9
|
+
|
|
10
|
+
[Create a free account](https://axioapi.com/portal/register), then open [API keys](https://axioapi.com/account/tokens), create a key and copy it. New accounts receive free credits after verification, enough to try every endpoint.
|
|
11
|
+
|
|
12
|
+
Set it as an environment variable (the SDK reads `AXIOAPI_KEY`):
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
export AXIOAPI_KEY=ak_your_key # macOS / Linux
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
```powershell
|
|
19
|
+
$env:AXIOAPI_KEY = "ak_your_key" # Windows PowerShell
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### 2. Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install git+https://github.com/axioapi/axioapi-python.git
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Requires Python 3.9+. No dependencies. Once released on PyPI: `pip install axioapi`.
|
|
29
|
+
|
|
30
|
+
### 3. Make your first call
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
from axioapi import AxioAPI
|
|
34
|
+
|
|
35
|
+
client = AxioAPI() # reads AXIOAPI_KEY
|
|
36
|
+
print(client.account.limits()) # your plan and rate limits
|
|
37
|
+
print(client.seo.keyword_metrics(keywords=["api gateway"], country="us"))
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Every endpoint works the same way: `client.<group>.<operation>(params)`. See the examples below and the [full reference](https://axioapi.com/docs).
|
|
41
|
+
<!-- start:end -->
|
|
42
|
+
|
|
43
|
+
## More examples
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from axioapi import AxioAPI, RateLimitError, InsufficientCreditsError
|
|
47
|
+
|
|
48
|
+
client = AxioAPI() # or AxioAPI("ak_...")
|
|
49
|
+
|
|
50
|
+
# Keyword data API: volume, CPC and competition for up to 10 keywords per request
|
|
51
|
+
rows = client.seo.keyword_metrics(keywords=["api gateway", "proxy scraper"], country="us")
|
|
52
|
+
|
|
53
|
+
# Backlink API: summary with every data source that answered
|
|
54
|
+
backlinks = client.seo.backlinks_summary(domain="example.com")
|
|
55
|
+
print(backlinks["partial"], backlinks["missing"], list(backlinks["sources"]))
|
|
56
|
+
|
|
57
|
+
# Temp mail API: one inbox per test
|
|
58
|
+
inbox = client.temporary_email.create_inbox(ttl_minutes=10)
|
|
59
|
+
messages = client.temporary_email.list_messages(inbox=inbox["id"])
|
|
60
|
+
|
|
61
|
+
try:
|
|
62
|
+
client.verify.wait(number="+12025550192")
|
|
63
|
+
except RateLimitError as e:
|
|
64
|
+
print("retry in", e.retry_after, "request", e.request_id)
|
|
65
|
+
except InsufficientCreditsError:
|
|
66
|
+
print("top up credits")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- `client.<group>.<operation>(**params)` for every endpoint; `client.call("seo.keyword-metrics", ...)` works by capability key. `client.operations()` lists all of them with method, path and credit cost.
|
|
70
|
+
- Returns the `data` field. `client.request("GET", "/api/v1/account/limits", raw=True)` returns the whole envelope.
|
|
71
|
+
- Image and audio endpoints return `bytes`.
|
|
72
|
+
- Options: `AxioAPI(api_key, base_url=..., timeout=30, max_retries=2)`. 429 is retried for all methods; 502/503/504 and network errors only for GET and DELETE.
|
|
73
|
+
|
|
74
|
+
Docs: https://axioapi.com/docs · Guides: https://axioapi.com/guides · License: MIT
|
|
75
|
+
|
|
76
|
+
<!-- seo:start -->
|
|
77
|
+
## What you can build with the Python SDK
|
|
78
|
+
|
|
79
|
+
| Use case | API page | Typical call |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| [Temp mail API](https://axioapi.com/apis/temporary-email): disposable inboxes for signup and password-reset tests | `temporary-email` | create inbox, list messages, read message |
|
|
82
|
+
| [Receive SMS API](https://axioapi.com/apis/sms) and [OTP API](https://axioapi.com/apis/verify): public numbers and "wait for the code" | `sms`, `verify` | list numbers, wait for OTP |
|
|
83
|
+
| [Email validation API](https://axioapi.com/apis/email-validation): syntax, MX and disposable-address checks, plus transactional and outreach email sending | `email` | validate, batch validate, send |
|
|
84
|
+
| [Proxy API](https://axioapi.com/apis/proxy-vpn): sticky and rotating proxy sessions by country | `proxy` | create session, rotate, close |
|
|
85
|
+
| [SEO API](https://axioapi.com/apis/seo): keyword data API (volume, CPC), backlink API, domain overview, on-page audit | `seo` | keyword metrics, backlinks summary |
|
|
86
|
+
| [Search API](https://axioapi.com/apis/search): web, image, news, video, maps and shopping results, AI Overview and autocomplete | `search` | web search, news search |
|
|
87
|
+
| Scholar API: Google Scholar paper search, author profiles and citation formats | `scholar` | search papers, author profile |
|
|
88
|
+
| Text AI: neural translation, text generation and grammar check | `text`, `grammar` | translate, generate, check grammar |
|
|
89
|
+
| Audio and video AI: speech-to-text, text-to-speech, AI image generation, video transcripts and tags | `audio`, `tts`, `ai-image`, `video` | transcribe, text to speech, generate image |
|
|
90
|
+
| YouTube AI summarizer and webpage content extraction | `youtube`, `webpage` | summarize video, extract page |
|
|
91
|
+
| [Coupon API](https://axioapi.com/apis/coupons) and product price history: store promo codes and historical prices | `coupons`, `products`, `ecommerce` | search coupons, price history |
|
|
92
|
+
| DNS, BIN, technology and local lead APIs: DNS records, card BIN lookup, website tech stack, Google Maps business leads | `dns`, `bin`, `tech`, `local` | resolve DNS, BIN lookup, tech profile |
|
|
93
|
+
| [TikTok](https://axioapi.com/apis/social-tiktok), [Facebook](https://axioapi.com/apis/social-facebook), [Instagram](https://axioapi.com/apis/social-instagram), [YouTube](https://axioapi.com/apis/social-youtube), [X (Twitter)](https://axioapi.com/apis/social-twitter), [LinkedIn](https://axioapi.com/apis/social-linkedin) and [Reddit](https://axioapi.com/apis/social-reddit) scraper APIs | `social` | profiles, posts, comments, transcripts |
|
|
94
|
+
|
|
95
|
+
## Guides with working code
|
|
96
|
+
|
|
97
|
+
- [Backlink API: check a domain's backlinks in Python](https://axioapi.com/guides/backlink-api-check-domain-python)
|
|
98
|
+
- [Keyword data API: get search volume and CPC in code](https://axioapi.com/guides/keyword-data-api-volume-cpc)
|
|
99
|
+
- [SEO report API: build a domain ranking report](https://axioapi.com/guides/seo-report-api-domain-ranking)
|
|
100
|
+
- [Test signup emails with Playwright and a temp mail API](https://axioapi.com/guides/playwright-temp-mail-signup-test)
|
|
101
|
+
- [Test OTP flows with a receive SMS API](https://axioapi.com/guides/otp-testing-with-sms-api)
|
|
102
|
+
- [Sticky vs rotating proxy: which one to use](https://axioapi.com/guides/sticky-vs-rotating-proxy)
|
|
103
|
+
|
|
104
|
+
Free tools that need no account: [backlink checker](https://axioapi.com/tools/backlink-checker), [email validator](https://axioapi.com/tools/email-validator), [DNS lookup](https://axioapi.com/tools/dns-lookup), [BIN checker](https://axioapi.com/tools/bin-checker).
|
|
105
|
+
|
|
106
|
+
## FAQ
|
|
107
|
+
|
|
108
|
+
**Is there a Python client for the AxioAPI backlink API and keyword data API?** Yes, this package. `seo.backlinks_summary` returns the backlink summary of a domain with the figures of every data source, and `seo.keyword_metrics` returns search volume, CPC and competition for up to 10 keywords per request.
|
|
109
|
+
|
|
110
|
+
**How do I test signup emails and OTP codes from Python?** Create a disposable inbox with the temp mail API, submit its address in your form and read the message. For SMS codes, call the verify endpoint, which waits for the OTP on a public number and returns it.
|
|
111
|
+
|
|
112
|
+
**How much does it cost?** You pay per request with credits, and each endpoint lists its price on its [API page](https://axioapi.com/apis) and in the OpenAPI spec (`x-credit-cost`). New accounts receive free credits after verification. See [pricing](https://axioapi.com/pricing).
|
|
113
|
+
|
|
114
|
+
**Where is the full reference?** [axioapi.com/docs](https://axioapi.com/docs), the [OpenAPI 3.1 spec](https://axioapi.com/api/v1/openapi.json) and [llms.txt](https://axioapi.com/llms.txt) for AI agents.
|
|
115
|
+
|
|
116
|
+
Vietnamese: [AxioAPI tiếng Việt](https://axioapi.com/vi), [API SEO và API backlink](https://axioapi.com/vi/apis/seo).
|
|
117
|
+
<!-- seo:end -->
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "axioapi"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Official Python SDK for the AxioAPI REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API), search API and social scraper APIs. One API key."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
keywords = ["api", "sdk", "seo api", "backlink api", "keyword api", "temp mail api", "sms verification api", "otp api", "email validation api", "proxy api", "scraper api", "search api", "serp api", "scholar api", "translation api", "python", "axioapi"]
|
|
13
|
+
dependencies = []
|
|
14
|
+
|
|
15
|
+
[project.urls]
|
|
16
|
+
Homepage = "https://axioapi.com"
|
|
17
|
+
Documentation = "https://axioapi.com/docs"
|
|
18
|
+
|
|
19
|
+
[tool.setuptools.packages.find]
|
|
20
|
+
where = ["src"]
|
|
21
|
+
|
|
22
|
+
[tool.setuptools.package-data]
|
|
23
|
+
axioapi = ["operations.json"]
|
axioapi-1.0.0/setup.cfg
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
from .client import VERSION as __version__, AxioAPI
|
|
2
|
+
from .errors import (APIConnectionError, AuthenticationError, AxioAPIError, InsufficientCreditsError,
|
|
3
|
+
NotFoundError, RateLimitError, ValidationError)
|
|
4
|
+
|
|
5
|
+
__all__ = ["AxioAPI", "AxioAPIError", "AuthenticationError", "InsufficientCreditsError", "NotFoundError",
|
|
6
|
+
"RateLimitError", "ValidationError", "APIConnectionError", "__version__"]
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import os
|
|
3
|
+
import time
|
|
4
|
+
from typing import Any, Callable, Dict, Optional
|
|
5
|
+
|
|
6
|
+
from .errors import APIConnectionError
|
|
7
|
+
from .groups import OperationGroup
|
|
8
|
+
from .registry import Operation, Registry
|
|
9
|
+
from .request_builder import build_request, encode_query
|
|
10
|
+
from .responses import build_error, parse_success
|
|
11
|
+
from .retry import RetryPolicy
|
|
12
|
+
from .transport import ConnectionFailure, UrllibTransport
|
|
13
|
+
|
|
14
|
+
DEFAULT_BASE_URL = "https://axioapi.com"
|
|
15
|
+
VERSION = "1.0.0"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class AxioAPI:
|
|
19
|
+
"""Client for https://axioapi.com.
|
|
20
|
+
|
|
21
|
+
client = AxioAPI("ak_...")
|
|
22
|
+
client.seo.keyword_metrics(keywords=["api gateway"], country="us")
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 30.0,
|
|
26
|
+
max_retries: int = 2, user_agent: Optional[str] = None,
|
|
27
|
+
sleep: Callable[[float], None] = time.sleep):
|
|
28
|
+
self.api_key = api_key or os.environ.get("AXIOAPI_KEY")
|
|
29
|
+
if not self.api_key:
|
|
30
|
+
raise ValueError("Pass api_key or set the AXIOAPI_KEY environment variable.")
|
|
31
|
+
self.base_url = (base_url or os.environ.get("AXIOAPI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
|
|
32
|
+
self.user_agent = user_agent or f"axioapi-python/{VERSION}"
|
|
33
|
+
self.registry = Registry.load()
|
|
34
|
+
self._retry = RetryPolicy(max_retries, sleep)
|
|
35
|
+
self._transport = UrllibTransport(timeout)
|
|
36
|
+
|
|
37
|
+
def operations(self) -> Dict[str, Operation]:
|
|
38
|
+
return self.registry.all()
|
|
39
|
+
|
|
40
|
+
def __getattr__(self, name: str) -> OperationGroup:
|
|
41
|
+
if name.startswith("_") or "registry" not in self.__dict__ or not self.registry.has_group(name):
|
|
42
|
+
raise AttributeError(name)
|
|
43
|
+
return OperationGroup(self, name)
|
|
44
|
+
|
|
45
|
+
def call(self, operation: str, **params: Any) -> Any:
|
|
46
|
+
"""Calls an operation by capability key (for example "seo.keyword-metrics") and returns `data`."""
|
|
47
|
+
found = self.registry.find(operation)
|
|
48
|
+
if found is None:
|
|
49
|
+
raise ValueError(f"Unknown operation '{operation}'. See client.operations().")
|
|
50
|
+
prepared = build_request(found, params)
|
|
51
|
+
return self.request(prepared.method, prepared.path, params=prepared.query or None, json_body=prepared.body)
|
|
52
|
+
|
|
53
|
+
def request(self, method: str, path: str, *, params: Optional[dict] = None, json_body: Any = None,
|
|
54
|
+
raw: bool = False) -> Any:
|
|
55
|
+
"""Sends a request with retries; returns `data`, the envelope with raw=True, or bytes for files."""
|
|
56
|
+
method = method.upper()
|
|
57
|
+
url = self._url(path, params)
|
|
58
|
+
payload = json.dumps(json_body).encode("utf-8") if json_body is not None else None
|
|
59
|
+
headers = self._headers(has_body=payload is not None)
|
|
60
|
+
|
|
61
|
+
for attempt in range(self._retry.max_retries + 1):
|
|
62
|
+
try:
|
|
63
|
+
response = self._transport.send(method, url, headers, payload)
|
|
64
|
+
except ConnectionFailure as failure:
|
|
65
|
+
if self._retry.should_retry_connection(method, attempt):
|
|
66
|
+
self._retry.wait(attempt)
|
|
67
|
+
continue
|
|
68
|
+
raise APIConnectionError(f"Could not reach {self.base_url}: {failure}") from None
|
|
69
|
+
if response.ok:
|
|
70
|
+
return parse_success(response, raw)
|
|
71
|
+
if self._retry.should_retry_status(response.status, method, attempt):
|
|
72
|
+
self._retry.wait(attempt, response.header("Retry-After"))
|
|
73
|
+
continue
|
|
74
|
+
raise build_error(response)
|
|
75
|
+
|
|
76
|
+
def _url(self, path: str, params: Optional[dict]) -> str:
|
|
77
|
+
url = self.base_url + (path if path.startswith("/") else "/" + path)
|
|
78
|
+
return f"{url}?{encode_query(params)}" if params else url
|
|
79
|
+
|
|
80
|
+
def _headers(self, has_body: bool) -> Dict[str, str]:
|
|
81
|
+
headers = {"Authorization": f"Bearer {self.api_key}", "Accept": "application/json", "User-Agent": self.user_agent}
|
|
82
|
+
if has_body:
|
|
83
|
+
headers["Content-Type"] = "application/json"
|
|
84
|
+
return headers
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Exceptions raised by the AxioAPI client."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any, Optional
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class AxioAPIError(Exception):
|
|
9
|
+
"""Base class. Every API error carries the HTTP status, error code and request_id for support."""
|
|
10
|
+
|
|
11
|
+
def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None,
|
|
12
|
+
request_id: Optional[str] = None, fields: Optional[dict] = None, body: Any = None):
|
|
13
|
+
super().__init__(message)
|
|
14
|
+
self.message = message
|
|
15
|
+
self.status = status
|
|
16
|
+
self.code = code
|
|
17
|
+
self.request_id = request_id
|
|
18
|
+
self.fields = fields or {}
|
|
19
|
+
self.body = body
|
|
20
|
+
|
|
21
|
+
def __str__(self) -> str:
|
|
22
|
+
parts = [self.message]
|
|
23
|
+
if self.status:
|
|
24
|
+
parts.append(f"status={self.status}")
|
|
25
|
+
if self.code:
|
|
26
|
+
parts.append(f"code={self.code}")
|
|
27
|
+
if self.request_id:
|
|
28
|
+
parts.append(f"request_id={self.request_id}")
|
|
29
|
+
return " | ".join(parts)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class AuthenticationError(AxioAPIError):
|
|
33
|
+
"""401: the API key is missing or invalid."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class InsufficientCreditsError(AxioAPIError):
|
|
37
|
+
"""402: not enough credits for this call."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class NotFoundError(AxioAPIError):
|
|
41
|
+
"""404: the resource does not exist, expired or is not yours."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class ValidationError(AxioAPIError):
|
|
45
|
+
"""422: invalid parameters. See `fields` for per-field messages."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class RateLimitError(AxioAPIError):
|
|
49
|
+
"""429: request limit reached. `retry_after` is in seconds when the server sent it."""
|
|
50
|
+
|
|
51
|
+
def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any):
|
|
52
|
+
super().__init__(message, **kwargs)
|
|
53
|
+
self.retry_after = retry_after
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class APIConnectionError(AxioAPIError):
|
|
57
|
+
"""The request never produced an HTTP response (DNS, TLS, timeout)."""
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
from typing import TYPE_CHECKING, Any, Callable
|
|
2
|
+
|
|
3
|
+
if TYPE_CHECKING:
|
|
4
|
+
from .client import AxioAPI
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class OperationGroup:
|
|
8
|
+
"""`client.seo`: attribute access to the operations of one API group."""
|
|
9
|
+
|
|
10
|
+
def __init__(self, client: "AxioAPI", group: str):
|
|
11
|
+
self._client = client
|
|
12
|
+
self._group = group
|
|
13
|
+
|
|
14
|
+
def __getattr__(self, name: str) -> Callable[..., Any]:
|
|
15
|
+
key = self._client.registry.resolve(self._group, name)
|
|
16
|
+
if key is None:
|
|
17
|
+
raise AttributeError(f"AxioAPI has no operation '{self._group}.{name}'")
|
|
18
|
+
return lambda **params: self._client.call(key, **params)
|
|
19
|
+
|
|
20
|
+
def __dir__(self):
|
|
21
|
+
return self._client.registry.group_names(self._group)
|