blitz-api-py 3.0.0__tar.gz → 4.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.
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/CHANGELOG.md +33 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/PKG-INFO +41 -13
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/README.md +40 -12
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/__init__.py +2 -3
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_async.py +11 -2
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_sync.py +11 -2
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_constants.py +5 -2
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_exceptions.py +0 -21
- blitz_api_py-4.0.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/changelog.py +5 -8
- blitz_api_py-4.0.0/src/blitz_api/resources/_async/company.py +89 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/enrichment.py +19 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/jobs.py +8 -13
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/search.py +23 -52
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/changelog.py +5 -8
- blitz_api_py-4.0.0/src/blitz_api/resources/_sync/company.py +91 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/enrichment.py +19 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/jobs.py +8 -13
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/search.py +23 -52
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/__init__.py +8 -1
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/_models.py +26 -2
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/changelog.py +4 -13
- blitz_api_py-4.0.0/src/blitz_api/types/company.py +49 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enrichment.py +12 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enums.py +1 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/filters.py +93 -23
- blitz_api_py-4.0.0/src/blitz_api/types/shared.py +152 -0
- blitz_api_py-3.0.0/src/blitz_api/_version.py +0 -1
- blitz_api_py-3.0.0/src/blitz_api/resources/_async/company.py +0 -55
- blitz_api_py-3.0.0/src/blitz_api/resources/_sync/company.py +0 -57
- blitz_api_py-3.0.0/src/blitz_api/types/company.py +0 -31
- blitz_api_py-3.0.0/src/blitz_api/types/shared.py +0 -120
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/.gitignore +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/LICENSE +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/pyproject.toml +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_base_client.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_async.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_base.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_sync.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/__init__.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/account.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/account.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/account.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/jobs.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/search.py +0 -0
- {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/utils.py +0 -0
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [4.0.0](https://github.com/api-blitz/blitz-api-py/compare/v3.0.0...v4.0.0) (2026-09-22)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* `search.companies(company=...)` no longer type-checks a dict literal containing `linkedin_url`. The endpoint never honoured it, so drop the key. On `search.people` and `company.tam_by_people` it keeps working, now typed as `PeopleCompanyFilter` (exported from `blitz_api` and `blitz_api.types`).
|
|
9
|
+
* `Company.slogan`, `Company.revenue` and `Company.employee_growth` are removed, as is the `EmployeeGrowth` model and its `blitz_api.types` export -- the API never returned any of them. `Company.specialties` is now `list[str]` defaulting to `[]` rather than `list[str] | None`; code branching on `specialties is None` should check for an empty list instead.
|
|
10
|
+
* `InsufficientCreditsError` is removed. Catch `InsufficientRecordsError` instead.
|
|
11
|
+
* `Education.field_of_study` is removed — the API folded it into `degree` ("Bachelor of Science, Industrial Engineering").
|
|
12
|
+
|
|
13
|
+
### Features
|
|
14
|
+
|
|
15
|
+
* add the Industry.UNKNOWN bucket and document the range-filter 422 ([5f2d944](https://github.com/api-blitz/blitz-api-py/commit/5f2d944427b631b4b668af0bc99f614161b00425))
|
|
16
|
+
* remove the deprecated InsufficientCreditsError alias ([0c9be23](https://github.com/api-blitz/blitz-api-py/commit/0c9be232268cb68cfa36d7352e1304608bed32cc))
|
|
17
|
+
* split PeopleCompanyFilter out of the shared CompanyFilter ([fc6983e](https://github.com/api-blitz/blitz-api-py/commit/fc6983eef696c058620a799ec4b4f476ed32701d)), closes [#25](https://github.com/api-blitz/blitz-api-py/issues/25)
|
|
18
|
+
* sync SDK to the 2026-09-11 / 2026-09-15 API releases ([81460ed](https://github.com/api-blitz/blitz-api-py/commit/81460edbcff5f985fd3e1498d70b282ce11d7550))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Bug Fixes
|
|
22
|
+
|
|
23
|
+
* remove phantom Company fields and the redundant _drop_none layer ([52b5ec5](https://github.com/api-blitz/blitz-api-py/commit/52b5ec5ec7241d2ea7dd6aacf2a3d0bbcc73dec2))
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
### Documentation
|
|
27
|
+
|
|
28
|
+
* correct the profile_min_connections default to 0, not 200 ([6ee2893](https://github.com/api-blitz/blitz-api-py/commit/6ee2893c7082b075f9d83ab5dc68943a8126a965)), closes [#26](https://github.com/api-blitz/blitz-api-py/issues/26)
|
|
29
|
+
* correct the README headline example and route to enrichment.person ([7051afb](https://github.com/api-blitz/blitz-api-py/commit/7051afb1fa362621e23ae8ed25f2ae20a842006e)), closes [#30](https://github.com/api-blitz/blitz-api-py/issues/30)
|
|
30
|
+
* correct the stale rate-limit and spec-version facts ([10615d5](https://github.com/api-blitz/blitz-api-py/commit/10615d58b6f6d4905e1f00033032fd5fbf13a350))
|
|
31
|
+
* correct the stale response-schema rule and link the JS mirror PR ([1f1381f](https://github.com/api-blitz/blitz-api-py/commit/1f1381f164c0bc02b46a20ec94cec4c079375f44))
|
|
32
|
+
* guard the optional linkedin_url in the README enrichment example ([cdcfb71](https://github.com/api-blitz/blitz-api-py/commit/cdcfb71171131bf9400e99737b455ef7676c4b70))
|
|
33
|
+
* name the legacy 50 req/s rate limit instead of "more on legacy ones" ([f4974a1](https://github.com/api-blitz/blitz-api-py/commit/f4974a123ad869f3f1e9aa28293dede6ce24648b)), closes [#29](https://github.com/api-blitz/blitz-api-py/issues/29)
|
|
34
|
+
* the /changelog/ trailing slash is not load-bearing ([891d5b7](https://github.com/api-blitz/blitz-api-py/commit/891d5b7e1c04583c14997ff9ad7fc39e3f8d4245)), closes [#28](https://github.com/api-blitz/blitz-api-py/issues/28)
|
|
35
|
+
|
|
3
36
|
## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
|
|
4
37
|
|
|
5
38
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: blitz-api-py
|
|
3
|
-
Version:
|
|
3
|
+
Version: 4.0.0
|
|
4
4
|
Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
|
|
5
5
|
Project-URL: Homepage, https://blitz-api.ai
|
|
6
6
|
Project-URL: Documentation, https://docs.blitz-api.ai
|
|
@@ -162,14 +162,33 @@ later are preserved):
|
|
|
162
162
|
```python
|
|
163
163
|
Person(
|
|
164
164
|
full_name="Jordan Lee",
|
|
165
|
-
|
|
165
|
+
# Derived from the first position as "<job title> | @<employer>" — not the
|
|
166
|
+
# free-text headline written on the LinkedIn profile.
|
|
167
|
+
headline="VP of Engineering | @Acme",
|
|
166
168
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
167
169
|
location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
|
|
170
|
+
# Positions from the profile, in profile order — read `job_is_current` for the
|
|
171
|
+
# current role rather than assuming index 0.
|
|
168
172
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
169
173
|
# first_name, last_name, skills, education, certifications, … also present
|
|
170
174
|
)
|
|
171
175
|
```
|
|
172
176
|
|
|
177
|
+
**How many positions land in `experiences[]` depends on the endpoint** — and upstream
|
|
178
|
+
currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
|
|
179
|
+
it returns only the position that matched your filters, while the API reference still
|
|
180
|
+
says it returns the full position history. Don't rely on either from a search result. If
|
|
181
|
+
you need the person's whole career in profile order, `enrichment.person` returns it
|
|
182
|
+
unambiguously (1 record on success, free on a miss):
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
if person.linkedin_url: # optional on Person; the call requires a str
|
|
186
|
+
result = client.enrichment.person(person_linkedin_url=person.linkedin_url)
|
|
187
|
+
if result.found and result.person:
|
|
188
|
+
for exp in result.person.experiences: # every position held, in profile order
|
|
189
|
+
print(exp.job_title, exp.company_name, exp.job_is_current)
|
|
190
|
+
```
|
|
191
|
+
|
|
173
192
|
And `enrichment.email(...)` returns:
|
|
174
193
|
|
|
175
194
|
```python
|
|
@@ -201,8 +220,8 @@ All methods are grouped into seven namespaces:
|
|
|
201
220
|
| `client.account` | `key_info()` |
|
|
202
221
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
203
222
|
| `client.jobs` | `search()`, `company()` |
|
|
204
|
-
| `client.company` | `tam_by_jobs()` |
|
|
205
|
-
| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
223
|
+
| `client.company` | `tam_by_jobs()`, `tam_by_people()` |
|
|
224
|
+
| `client.enrichment` | `person()`, `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
206
225
|
| `client.utils` | `current_date()` |
|
|
207
226
|
| `client.changelog` | `list()` |
|
|
208
227
|
|
|
@@ -212,10 +231,10 @@ member or a raw string.
|
|
|
212
231
|
|
|
213
232
|
## Pagination
|
|
214
233
|
|
|
215
|
-
The search and
|
|
216
|
-
fetches each subsequent page for you. `search.people`/`search.companies
|
|
217
|
-
`jobs.search`/`jobs.company`
|
|
218
|
-
all behave identically here.
|
|
234
|
+
The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
|
|
235
|
+
SDK fetches each subsequent page for you. `search.people`/`search.companies`,
|
|
236
|
+
`jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
|
|
237
|
+
cursor-based; `search.employee_finder` is page-based — all behave identically here.
|
|
219
238
|
|
|
220
239
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
221
240
|
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
@@ -248,6 +267,13 @@ for job in client.jobs.search(
|
|
|
248
267
|
).auto_paging_iter(max_items=200):
|
|
249
268
|
print(job.company_name, job.title, job.location.city if job.location else None)
|
|
250
269
|
|
|
270
|
+
# The TAM builders page the same way — distinct companies, each with its match count.
|
|
271
|
+
for match in client.company.tam_by_people(
|
|
272
|
+
company={"industry": {"include": ["Software Development"]}},
|
|
273
|
+
people={"job_level": ["VP"], "min_per_company": 3},
|
|
274
|
+
).auto_paging_iter(max_items=200):
|
|
275
|
+
print(match.company.name if match.company else None, match.matched_people)
|
|
276
|
+
|
|
251
277
|
# Or page manually.
|
|
252
278
|
page = client.search.people(people={...}, max_results=50)
|
|
253
279
|
print(page.results, page.cursor)
|
|
@@ -303,11 +329,13 @@ client = BlitzAPI(
|
|
|
303
329
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
304
330
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
305
331
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
306
|
-
endpoint (
|
|
307
|
-
`client.account.key_info().max_requests_per_seconds`).
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
332
|
+
endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
|
|
333
|
+
via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
|
|
334
|
+
deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
|
|
335
|
+
full budget. A single
|
|
336
|
+
client instance therefore stays under the limit on every endpoint, so a burst on one
|
|
337
|
+
never blocks another. Across multiple processes — which share an endpoint's budget — you
|
|
338
|
+
may still hit `429`; the retry path handles that.
|
|
311
339
|
|
|
312
340
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
313
341
|
endpoint needs longer than the client default:
|
|
@@ -131,14 +131,33 @@ later are preserved):
|
|
|
131
131
|
```python
|
|
132
132
|
Person(
|
|
133
133
|
full_name="Jordan Lee",
|
|
134
|
-
|
|
134
|
+
# Derived from the first position as "<job title> | @<employer>" — not the
|
|
135
|
+
# free-text headline written on the LinkedIn profile.
|
|
136
|
+
headline="VP of Engineering | @Acme",
|
|
135
137
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
136
138
|
location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
|
|
139
|
+
# Positions from the profile, in profile order — read `job_is_current` for the
|
|
140
|
+
# current role rather than assuming index 0.
|
|
137
141
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
138
142
|
# first_name, last_name, skills, education, certifications, … also present
|
|
139
143
|
)
|
|
140
144
|
```
|
|
141
145
|
|
|
146
|
+
**How many positions land in `experiences[]` depends on the endpoint** — and upstream
|
|
147
|
+
currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
|
|
148
|
+
it returns only the position that matched your filters, while the API reference still
|
|
149
|
+
says it returns the full position history. Don't rely on either from a search result. If
|
|
150
|
+
you need the person's whole career in profile order, `enrichment.person` returns it
|
|
151
|
+
unambiguously (1 record on success, free on a miss):
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
if person.linkedin_url: # optional on Person; the call requires a str
|
|
155
|
+
result = client.enrichment.person(person_linkedin_url=person.linkedin_url)
|
|
156
|
+
if result.found and result.person:
|
|
157
|
+
for exp in result.person.experiences: # every position held, in profile order
|
|
158
|
+
print(exp.job_title, exp.company_name, exp.job_is_current)
|
|
159
|
+
```
|
|
160
|
+
|
|
142
161
|
And `enrichment.email(...)` returns:
|
|
143
162
|
|
|
144
163
|
```python
|
|
@@ -170,8 +189,8 @@ All methods are grouped into seven namespaces:
|
|
|
170
189
|
| `client.account` | `key_info()` |
|
|
171
190
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
172
191
|
| `client.jobs` | `search()`, `company()` |
|
|
173
|
-
| `client.company` | `tam_by_jobs()` |
|
|
174
|
-
| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
192
|
+
| `client.company` | `tam_by_jobs()`, `tam_by_people()` |
|
|
193
|
+
| `client.enrichment` | `person()`, `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
175
194
|
| `client.utils` | `current_date()` |
|
|
176
195
|
| `client.changelog` | `list()` |
|
|
177
196
|
|
|
@@ -181,10 +200,10 @@ member or a raw string.
|
|
|
181
200
|
|
|
182
201
|
## Pagination
|
|
183
202
|
|
|
184
|
-
The search and
|
|
185
|
-
fetches each subsequent page for you. `search.people`/`search.companies
|
|
186
|
-
`jobs.search`/`jobs.company`
|
|
187
|
-
all behave identically here.
|
|
203
|
+
The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
|
|
204
|
+
SDK fetches each subsequent page for you. `search.people`/`search.companies`,
|
|
205
|
+
`jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
|
|
206
|
+
cursor-based; `search.employee_finder` is page-based — all behave identically here.
|
|
188
207
|
|
|
189
208
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
190
209
|
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
@@ -217,6 +236,13 @@ for job in client.jobs.search(
|
|
|
217
236
|
).auto_paging_iter(max_items=200):
|
|
218
237
|
print(job.company_name, job.title, job.location.city if job.location else None)
|
|
219
238
|
|
|
239
|
+
# The TAM builders page the same way — distinct companies, each with its match count.
|
|
240
|
+
for match in client.company.tam_by_people(
|
|
241
|
+
company={"industry": {"include": ["Software Development"]}},
|
|
242
|
+
people={"job_level": ["VP"], "min_per_company": 3},
|
|
243
|
+
).auto_paging_iter(max_items=200):
|
|
244
|
+
print(match.company.name if match.company else None, match.matched_people)
|
|
245
|
+
|
|
220
246
|
# Or page manually.
|
|
221
247
|
page = client.search.people(people={...}, max_results=50)
|
|
222
248
|
print(page.results, page.cursor)
|
|
@@ -272,11 +298,13 @@ client = BlitzAPI(
|
|
|
272
298
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
273
299
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
274
300
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
275
|
-
endpoint (
|
|
276
|
-
`client.account.key_info().max_requests_per_seconds`).
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
301
|
+
endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
|
|
302
|
+
via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
|
|
303
|
+
deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
|
|
304
|
+
full budget. A single
|
|
305
|
+
client instance therefore stays under the limit on every endpoint, so a burst on one
|
|
306
|
+
never blocks another. Across multiple processes — which share an endpoint's budget — you
|
|
307
|
+
may still hit `429`; the retry path handles that.
|
|
280
308
|
|
|
281
309
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
282
310
|
endpoint needs longer than the client default:
|
|
@@ -23,7 +23,6 @@ from ._exceptions import (
|
|
|
23
23
|
APITimeoutError,
|
|
24
24
|
AuthenticationError,
|
|
25
25
|
BlitzError,
|
|
26
|
-
InsufficientCreditsError, # pyright: ignore[reportDeprecated]
|
|
27
26
|
InsufficientRecordsError,
|
|
28
27
|
NotFoundError,
|
|
29
28
|
RateLimitError,
|
|
@@ -35,6 +34,7 @@ from ._version import __version__
|
|
|
35
34
|
from .types import (
|
|
36
35
|
CompanyFilter,
|
|
37
36
|
Industry,
|
|
37
|
+
PeopleCompanyFilter,
|
|
38
38
|
PeopleFilter,
|
|
39
39
|
)
|
|
40
40
|
|
|
@@ -59,10 +59,9 @@ __all__ = [
|
|
|
59
59
|
"NotFoundError",
|
|
60
60
|
"RateLimitError",
|
|
61
61
|
"ServerError",
|
|
62
|
-
# deprecated alias (removed in 3.0.0)
|
|
63
|
-
"InsufficientCreditsError",
|
|
64
62
|
# commonly-used types (full set under blitz_api.types)
|
|
65
63
|
"Industry",
|
|
66
64
|
"CompanyFilter",
|
|
65
|
+
"PeopleCompanyFilter",
|
|
67
66
|
"PeopleFilter",
|
|
68
67
|
]
|
|
@@ -93,7 +93,11 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
93
93
|
) -> ResponseT:
|
|
94
94
|
url = self._build_url(path)
|
|
95
95
|
headers = self._build_headers()
|
|
96
|
+
# ``to_jsonable`` resolves enums and drops ``None`` at every depth, so resources
|
|
97
|
+
# build their body/params straight from their keyword arguments and never filter.
|
|
98
|
+
# Params need it as much as bodies do: httpx renders ``days=None`` as ``days=``.
|
|
96
99
|
json_body = to_jsonable(body) if body is not None else None
|
|
100
|
+
query_params = to_jsonable(params) if params is not None else None
|
|
97
101
|
|
|
98
102
|
attempt = 0
|
|
99
103
|
while True:
|
|
@@ -101,11 +105,16 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
101
105
|
try:
|
|
102
106
|
if timeout is None:
|
|
103
107
|
response = await self._http_client.request(
|
|
104
|
-
method, url, headers=headers, json=json_body, params=
|
|
108
|
+
method, url, headers=headers, json=json_body, params=query_params
|
|
105
109
|
)
|
|
106
110
|
else:
|
|
107
111
|
response = await self._http_client.request(
|
|
108
|
-
method,
|
|
112
|
+
method,
|
|
113
|
+
url,
|
|
114
|
+
headers=headers,
|
|
115
|
+
json=json_body,
|
|
116
|
+
params=query_params,
|
|
117
|
+
timeout=timeout,
|
|
109
118
|
)
|
|
110
119
|
except httpx.TimeoutException as exc:
|
|
111
120
|
if self._should_retry_exception(exc) and attempt < self.max_retries:
|
|
@@ -95,7 +95,11 @@ class BlitzAPI(BaseClient):
|
|
|
95
95
|
) -> ResponseT:
|
|
96
96
|
url = self._build_url(path)
|
|
97
97
|
headers = self._build_headers()
|
|
98
|
+
# ``to_jsonable`` resolves enums and drops ``None`` at every depth, so resources
|
|
99
|
+
# build their body/params straight from their keyword arguments and never filter.
|
|
100
|
+
# Params need it as much as bodies do: httpx renders ``days=None`` as ``days=``.
|
|
98
101
|
json_body = to_jsonable(body) if body is not None else None
|
|
102
|
+
query_params = to_jsonable(params) if params is not None else None
|
|
99
103
|
|
|
100
104
|
attempt = 0
|
|
101
105
|
while True:
|
|
@@ -103,11 +107,16 @@ class BlitzAPI(BaseClient):
|
|
|
103
107
|
try:
|
|
104
108
|
if timeout is None:
|
|
105
109
|
response = self._http_client.request(
|
|
106
|
-
method, url, headers=headers, json=json_body, params=
|
|
110
|
+
method, url, headers=headers, json=json_body, params=query_params
|
|
107
111
|
)
|
|
108
112
|
else:
|
|
109
113
|
response = self._http_client.request(
|
|
110
|
-
method,
|
|
114
|
+
method,
|
|
115
|
+
url,
|
|
116
|
+
headers=headers,
|
|
117
|
+
json=json_body,
|
|
118
|
+
params=query_params,
|
|
119
|
+
timeout=timeout,
|
|
111
120
|
)
|
|
112
121
|
except httpx.TimeoutException as exc:
|
|
113
122
|
if self._should_retry_exception(exc) and attempt < self.max_retries:
|
|
@@ -19,8 +19,11 @@ DEFAULT_TIMEOUT = 30.0
|
|
|
19
19
|
#: Number of retries (in addition to the first attempt) for transient failures.
|
|
20
20
|
DEFAULT_MAX_RETRIES = 3
|
|
21
21
|
|
|
22
|
-
#: Default client-side rate limit
|
|
23
|
-
#:
|
|
22
|
+
#: Default client-side rate limit, applied **per endpoint** (one sliding window each).
|
|
23
|
+
#: The API limits each endpoint to 10 req/s independently — 50 on plans created before
|
|
24
|
+
#: 2026-09-30 — so this default deliberately sits at half the *lowest* cap. It therefore
|
|
25
|
+
#: leaves throughput on the table by design: raise it to your key's actual per-endpoint
|
|
26
|
+
#: value, discoverable via ``client.account.key_info().max_requests_per_seconds``.
|
|
24
27
|
DEFAULT_RATE_LIMIT_RPS = 5.0
|
|
25
28
|
|
|
26
29
|
#: Seconds to wait after a 429 when the response has no ``Retry-After`` header.
|
|
@@ -14,9 +14,6 @@
|
|
|
14
14
|
└── ServerError # 5xx (after retries are exhausted)
|
|
15
15
|
|
|
16
16
|
Catch :class:`BlitzError` to handle anything this SDK raises.
|
|
17
|
-
|
|
18
|
-
``InsufficientCreditsError`` remains available as a deprecated alias of
|
|
19
|
-
:class:`InsufficientRecordsError`; it is scheduled for removal in 3.0.0.
|
|
20
17
|
"""
|
|
21
18
|
|
|
22
19
|
from __future__ import annotations
|
|
@@ -29,7 +26,6 @@ from .types._models import FairUsage
|
|
|
29
26
|
|
|
30
27
|
if TYPE_CHECKING:
|
|
31
28
|
import httpx
|
|
32
|
-
from typing_extensions import deprecated
|
|
33
29
|
|
|
34
30
|
|
|
35
31
|
def _parse_fair_usage(body: Any) -> FairUsage | None:
|
|
@@ -144,20 +140,3 @@ class RateLimitError(APIStatusError):
|
|
|
144
140
|
|
|
145
141
|
class ServerError(APIStatusError):
|
|
146
142
|
"""5xx — the API failed (raised only after retries are exhausted)."""
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
# --- Deprecated aliases ------------------------------------------------------
|
|
150
|
-
|
|
151
|
-
if TYPE_CHECKING:
|
|
152
|
-
|
|
153
|
-
@deprecated(
|
|
154
|
-
"InsufficientCreditsError is renamed to InsufficientRecordsError and will be "
|
|
155
|
-
"removed in 3.0.0."
|
|
156
|
-
)
|
|
157
|
-
class InsufficientCreditsError(InsufficientRecordsError):
|
|
158
|
-
"""Deprecated alias for :class:`InsufficientRecordsError`."""
|
|
159
|
-
|
|
160
|
-
else:
|
|
161
|
-
# A true alias, not a subclass: the client raises ``InsufficientRecordsError``, so a
|
|
162
|
-
# subclass here would stop ``except InsufficientCreditsError`` from catching it.
|
|
163
|
-
InsufficientCreditsError = InsufficientRecordsError
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "4.0.0" # x-release-please-version
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
from typing import TYPE_CHECKING
|
|
5
|
+
from typing import TYPE_CHECKING
|
|
6
6
|
|
|
7
7
|
from ..._compat import TimeoutParam
|
|
8
8
|
from ...types.changelog import ChangelogEntry, ChangelogResponse
|
|
@@ -10,15 +10,12 @@ from ...types.changelog import ChangelogEntry, ChangelogResponse
|
|
|
10
10
|
if TYPE_CHECKING:
|
|
11
11
|
from ..._client import AsyncBlitzAPI
|
|
12
12
|
|
|
13
|
-
# Public endpoint: NO ``/v2`` prefix
|
|
13
|
+
# Public endpoint: NO ``/v2`` prefix. The trailing slash is what the spec declares;
|
|
14
|
+
# the API also answers ``/changelog`` (re-verified 2026-09-22 — both 200, no redirect),
|
|
15
|
+
# so it is not load-bearing, but keep it to match the spec.
|
|
14
16
|
_CHANGELOG = "/changelog/"
|
|
15
17
|
|
|
16
18
|
|
|
17
|
-
def _drop_none(**kwargs: Any) -> dict[str, Any]:
|
|
18
|
-
"""Build a query-param mapping keeping only the arguments the caller provided."""
|
|
19
|
-
return {key: value for key, value in kwargs.items() if value is not None}
|
|
20
|
-
|
|
21
|
-
|
|
22
19
|
class AsyncChangelogResource:
|
|
23
20
|
def __init__(self, client: AsyncBlitzAPI) -> None:
|
|
24
21
|
self._client = client
|
|
@@ -41,7 +38,7 @@ class AsyncChangelogResource:
|
|
|
41
38
|
**not paginated**: it returns a plain list filtered by the ``days`` / ``limit``
|
|
42
39
|
query parameters.
|
|
43
40
|
"""
|
|
44
|
-
params =
|
|
41
|
+
params = {"days": days, "limit": limit}
|
|
45
42
|
result = await self._client._request(
|
|
46
43
|
"GET",
|
|
47
44
|
_CHANGELOG,
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""The Company resource: ``client.company``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import TYPE_CHECKING
|
|
6
|
+
|
|
7
|
+
from ..._compat import TimeoutParam
|
|
8
|
+
from ..._pagination_async import AsyncCursorPage
|
|
9
|
+
from ...types.company import TamByJobsMatch, TamByPeopleMatch
|
|
10
|
+
from ...types.filters import (
|
|
11
|
+
JobCompanyFilter,
|
|
12
|
+
PeopleCompanyFilter,
|
|
13
|
+
TamJobFilter,
|
|
14
|
+
TamPeopleFilter,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from ..._client import AsyncBlitzAPI
|
|
19
|
+
|
|
20
|
+
_TAM_BY_JOBS = "/v2/company/tam-by-jobs"
|
|
21
|
+
_TAM_BY_PEOPLE = "/v2/company/tam-by-people"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class AsyncCompanyResource:
|
|
25
|
+
def __init__(self, client: AsyncBlitzAPI) -> None:
|
|
26
|
+
self._client = client
|
|
27
|
+
|
|
28
|
+
async def tam_by_jobs(
|
|
29
|
+
self,
|
|
30
|
+
*,
|
|
31
|
+
job: TamJobFilter | None = None,
|
|
32
|
+
company: JobCompanyFilter | None = None,
|
|
33
|
+
max_results: int | None = None,
|
|
34
|
+
cursor: str | None = None,
|
|
35
|
+
timeout: TimeoutParam = None,
|
|
36
|
+
) -> AsyncCursorPage[TamByJobsMatch]:
|
|
37
|
+
"""Build a Total Addressable Market of companies from live hiring signals.
|
|
38
|
+
|
|
39
|
+
Combine job-level filters (title, description, seniority, ...) with company
|
|
40
|
+
firmographics, and get back each matching company plus how many of its current
|
|
41
|
+
postings matched (``matched_jobs``). Use ``job["min_per_company"]`` to require a
|
|
42
|
+
minimum number of matching postings per company.
|
|
43
|
+
|
|
44
|
+
Cursor-paginated: auto-paginates over every ``{company, matched_jobs}`` match when
|
|
45
|
+
the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for manual
|
|
46
|
+
control. The API bills **1 record per result returned**; bound spend with
|
|
47
|
+
``max_items`` on ``.collect()`` / ``.auto_paging_iter()``.
|
|
48
|
+
"""
|
|
49
|
+
body = {"job": job, "company": company, "max_results": max_results, "cursor": cursor}
|
|
50
|
+
return await self._client._request(
|
|
51
|
+
"POST",
|
|
52
|
+
_TAM_BY_JOBS,
|
|
53
|
+
body=body,
|
|
54
|
+
cast_to=AsyncCursorPage[TamByJobsMatch],
|
|
55
|
+
timeout=timeout,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
async def tam_by_people(
|
|
59
|
+
self,
|
|
60
|
+
*,
|
|
61
|
+
company: PeopleCompanyFilter | None = None,
|
|
62
|
+
people: TamPeopleFilter | None = None,
|
|
63
|
+
max_results: int | None = None,
|
|
64
|
+
cursor: str | None = None,
|
|
65
|
+
timeout: TimeoutParam = None,
|
|
66
|
+
) -> AsyncCursorPage[TamByPeopleMatch]:
|
|
67
|
+
"""Build a Total Addressable Market of companies from headcount signals.
|
|
68
|
+
|
|
69
|
+
Takes the same filters as ``search.people`` — company firmographics plus a
|
|
70
|
+
persona — but returns the **distinct companies** employing the matching people
|
|
71
|
+
(deduplicated), each with its ``matched_people`` count. Use
|
|
72
|
+
``people["min_per_company"]`` to require a minimum number of matching employees
|
|
73
|
+
per company.
|
|
74
|
+
|
|
75
|
+
Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
|
|
76
|
+
when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
|
|
77
|
+
manual control. When ``min_per_company`` filters heavily a page may come back
|
|
78
|
+
partial — keep paging until the cursor is exhausted. The API bills **1 record per
|
|
79
|
+
result returned**; bound spend with ``max_items`` on ``.collect()`` /
|
|
80
|
+
``.auto_paging_iter()``.
|
|
81
|
+
"""
|
|
82
|
+
body = {"company": company, "people": people, "max_results": max_results, "cursor": cursor}
|
|
83
|
+
return await self._client._request(
|
|
84
|
+
"POST",
|
|
85
|
+
_TAM_BY_PEOPLE,
|
|
86
|
+
body=body,
|
|
87
|
+
cast_to=AsyncCursorPage[TamByPeopleMatch],
|
|
88
|
+
timeout=timeout,
|
|
89
|
+
)
|
|
@@ -13,6 +13,7 @@ from ...types.enrichment import (
|
|
|
13
13
|
EmailEnrichmentResponse,
|
|
14
14
|
EmailToPersonResponse,
|
|
15
15
|
LinkedinToDomainResponse,
|
|
16
|
+
PersonEnrichmentResponse,
|
|
16
17
|
PhoneEnrichmentResponse,
|
|
17
18
|
PhoneToPersonResponse,
|
|
18
19
|
)
|
|
@@ -20,6 +21,7 @@ from ...types.enrichment import (
|
|
|
20
21
|
if TYPE_CHECKING:
|
|
21
22
|
from ..._client import AsyncBlitzAPI
|
|
22
23
|
|
|
24
|
+
_PERSON = "/v2/enrichment/person"
|
|
23
25
|
_EMAIL = "/v2/enrichment/email"
|
|
24
26
|
_PHONE = "/v2/enrichment/phone"
|
|
25
27
|
_EMAIL_TO_PERSON = "/v2/enrichment/email-to-person"
|
|
@@ -35,6 +37,23 @@ class AsyncEnrichmentResource:
|
|
|
35
37
|
def __init__(self, client: AsyncBlitzAPI) -> None:
|
|
36
38
|
self._client = client
|
|
37
39
|
|
|
40
|
+
async def person(
|
|
41
|
+
self, *, person_linkedin_url: str, timeout: TimeoutParam = None
|
|
42
|
+
) -> PersonEnrichmentResponse:
|
|
43
|
+
"""Enrich a person from their LinkedIn profile URL.
|
|
44
|
+
|
|
45
|
+
Returns their whole career in ``person.experiences`` (every position held, in
|
|
46
|
+
profile order), plus education, skills and certifications. The API bills
|
|
47
|
+
**1 record on success**.
|
|
48
|
+
"""
|
|
49
|
+
return await self._client._request(
|
|
50
|
+
"POST",
|
|
51
|
+
_PERSON,
|
|
52
|
+
body={"person_linkedin_url": person_linkedin_url},
|
|
53
|
+
cast_to=PersonEnrichmentResponse,
|
|
54
|
+
timeout=timeout,
|
|
55
|
+
)
|
|
56
|
+
|
|
38
57
|
async def email(
|
|
39
58
|
self, *, person_linkedin_url: str, timeout: TimeoutParam = None
|
|
40
59
|
) -> EmailEnrichmentResponse:
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
-
from typing import TYPE_CHECKING
|
|
5
|
+
from typing import TYPE_CHECKING
|
|
6
6
|
|
|
7
7
|
from ..._compat import TimeoutParam
|
|
8
8
|
from ..._pagination_async import AsyncCursorPage
|
|
@@ -16,11 +16,6 @@ _SEARCH = "/v2/jobs/search"
|
|
|
16
16
|
_COMPANY = "/v2/jobs/company"
|
|
17
17
|
|
|
18
18
|
|
|
19
|
-
def _drop_none(**kwargs: Any) -> dict[str, Any]:
|
|
20
|
-
"""Build a request body keeping only the arguments the caller provided."""
|
|
21
|
-
return {key: value for key, value in kwargs.items() if value is not None}
|
|
22
|
-
|
|
23
|
-
|
|
24
19
|
class AsyncJobsResource:
|
|
25
20
|
def __init__(self, client: AsyncBlitzAPI) -> None:
|
|
26
21
|
self._client = client
|
|
@@ -40,7 +35,7 @@ class AsyncJobsResource:
|
|
|
40
35
|
Auto-paginates over every matching job when the result is iterated; use
|
|
41
36
|
``.iter_pages()`` or the ``cursor=`` arg for manual control.
|
|
42
37
|
"""
|
|
43
|
-
body =
|
|
38
|
+
body = {"job": job, "company": company, "max_results": max_results, "cursor": cursor}
|
|
44
39
|
return await self._client._request(
|
|
45
40
|
"POST", _SEARCH, body=body, cast_to=AsyncCursorPage[Job], timeout=timeout
|
|
46
41
|
)
|
|
@@ -59,12 +54,12 @@ class AsyncJobsResource:
|
|
|
59
54
|
Auto-paginates over every matching job; use ``.iter_pages()`` or ``cursor=``
|
|
60
55
|
for manual control.
|
|
61
56
|
"""
|
|
62
|
-
body =
|
|
63
|
-
company_linkedin_url
|
|
64
|
-
job
|
|
65
|
-
max_results
|
|
66
|
-
cursor
|
|
67
|
-
|
|
57
|
+
body = {
|
|
58
|
+
"company_linkedin_url": company_linkedin_url,
|
|
59
|
+
"job": job,
|
|
60
|
+
"max_results": max_results,
|
|
61
|
+
"cursor": cursor,
|
|
62
|
+
}
|
|
68
63
|
return await self._client._request(
|
|
69
64
|
"POST", _COMPANY, body=body, cast_to=AsyncCursorPage[Job], timeout=timeout
|
|
70
65
|
)
|