blitz-api-py 2.2.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-2.2.0 → blitz_api_py-4.0.0}/CHANGELOG.md +44 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/PKG-INFO +82 -22
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/README.md +81 -21
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/__init__.py +4 -2
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_base_client.py +2 -2
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_async.py +11 -2
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_sync.py +11 -2
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_constants.py +5 -2
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_exceptions.py +33 -4
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_async.py +1 -1
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_base.py +8 -3
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_sync.py +1 -1
- blitz_api_py-4.0.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/account.py +1 -1
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/changelog.py +6 -9
- blitz_api_py-4.0.0/src/blitz_api/resources/_async/company.py +89 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/enrichment.py +19 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/jobs.py +8 -13
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/search.py +23 -52
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/account.py +1 -1
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/changelog.py +6 -9
- blitz_api_py-4.0.0/src/blitz_api/resources/_sync/company.py +91 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/enrichment.py +19 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/jobs.py +8 -13
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/search.py +23 -52
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/__init__.py +12 -1
- blitz_api_py-4.0.0/src/blitz_api/types/_models.py +98 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/account.py +5 -3
- {blitz_api_py-2.2.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-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enrichment.py +22 -10
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enums.py +1 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/filters.py +93 -23
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/search.py +2 -2
- blitz_api_py-4.0.0/src/blitz_api/types/shared.py +152 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/utils.py +2 -2
- blitz_api_py-2.2.0/src/blitz_api/_version.py +0 -1
- blitz_api_py-2.2.0/src/blitz_api/resources/_async/company.py +0 -55
- blitz_api_py-2.2.0/src/blitz_api/resources/_sync/company.py +0 -57
- blitz_api_py-2.2.0/src/blitz_api/types/_models.py +0 -23
- blitz_api_py-2.2.0/src/blitz_api/types/company.py +0 -31
- blitz_api_py-2.2.0/src/blitz_api/types/shared.py +0 -120
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/.gitignore +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/LICENSE +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/pyproject.toml +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/__init__.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/jobs.py +0 -0
|
@@ -1,5 +1,49 @@
|
|
|
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
|
+
|
|
36
|
+
## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
### ⚠ BREAKING CHANGES
|
|
40
|
+
|
|
41
|
+
* `KeyInfo.remaining_credits` is renamed to `KeyInfo.records_remaining`.
|
|
42
|
+
|
|
43
|
+
### Features
|
|
44
|
+
|
|
45
|
+
* records vocabulary rename + fair_usage envelope on every response ([698fd6d](https://github.com/api-blitz/blitz-api-py/commit/698fd6dc95bbe6120c55064255820898b708da42))
|
|
46
|
+
|
|
3
47
|
## [2.2.0](https://github.com/api-blitz/blitz-api-py/compare/v2.1.0...v2.2.0) (2026-08-13)
|
|
4
48
|
|
|
5
49
|
|
|
@@ -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
|
|
@@ -53,7 +53,7 @@ and enrichment.
|
|
|
53
53
|
|
|
54
54
|
> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
|
|
55
55
|
> loop streams every match up to the server-side limit (people: 50k results), which can be
|
|
56
|
-
> a lot of
|
|
56
|
+
> a lot of records. Bound spend with **`max_items`** (a client-side total cap on
|
|
57
57
|
> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
|
|
58
58
|
> [Pagination](#pagination).
|
|
59
59
|
|
|
@@ -65,6 +65,7 @@ and enrichment.
|
|
|
65
65
|
- [Authentication](#authentication)
|
|
66
66
|
- [Endpoints](#endpoints)
|
|
67
67
|
- [Pagination](#pagination)
|
|
68
|
+
- [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
|
|
68
69
|
- [Configuration](#configuration)
|
|
69
70
|
- [Error handling](#error-handling)
|
|
70
71
|
- [Forward compatibility](#forward-compatibility)
|
|
@@ -89,7 +90,7 @@ from blitz_api.types import Industry, JobLevel
|
|
|
89
90
|
with BlitzAPI() as client:
|
|
90
91
|
# Health-check the key before a batch job.
|
|
91
92
|
info = client.account.key_info()
|
|
92
|
-
print(info.valid, info.
|
|
93
|
+
print(info.valid, info.records_remaining, info.max_requests_per_seconds)
|
|
93
94
|
|
|
94
95
|
# LinkedIn profile URL -> verified work email.
|
|
95
96
|
email = client.enrichment.email(
|
|
@@ -127,7 +128,7 @@ asyncio.run(main())
|
|
|
127
128
|
## Example: find, enrich, collect
|
|
128
129
|
|
|
129
130
|
A complete flow — find people, enrich each one's verified work email, collect the
|
|
130
|
-
contacts. `max_items` caps the total fetched so the run can't surprise you with
|
|
131
|
+
contacts. `max_items` caps the total fetched so the run can't surprise you with records.
|
|
131
132
|
|
|
132
133
|
```python
|
|
133
134
|
from blitz_api import BlitzAPI
|
|
@@ -140,7 +141,7 @@ leads = client.search.people(
|
|
|
140
141
|
company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
|
|
141
142
|
people={"job_level": [JobLevel.VP]},
|
|
142
143
|
max_results=25,
|
|
143
|
-
).collect(max_items=25) # client-side total cap — bounds
|
|
144
|
+
).collect(max_items=25) # client-side total cap — bounds record spend
|
|
144
145
|
|
|
145
146
|
# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
|
|
146
147
|
contacts: list[dict[str, str | None]] = []
|
|
@@ -161,14 +162,33 @@ later are preserved):
|
|
|
161
162
|
```python
|
|
162
163
|
Person(
|
|
163
164
|
full_name="Jordan Lee",
|
|
164
|
-
|
|
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",
|
|
165
168
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
166
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.
|
|
167
172
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
168
173
|
# first_name, last_name, skills, education, certifications, … also present
|
|
169
174
|
)
|
|
170
175
|
```
|
|
171
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
|
+
|
|
172
192
|
And `enrichment.email(...)` returns:
|
|
173
193
|
|
|
174
194
|
```python
|
|
@@ -200,8 +220,8 @@ All methods are grouped into seven namespaces:
|
|
|
200
220
|
| `client.account` | `key_info()` |
|
|
201
221
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
202
222
|
| `client.jobs` | `search()`, `company()` |
|
|
203
|
-
| `client.company` | `tam_by_jobs()` |
|
|
204
|
-
| `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()` |
|
|
205
225
|
| `client.utils` | `current_date()` |
|
|
206
226
|
| `client.changelog` | `list()` |
|
|
207
227
|
|
|
@@ -211,15 +231,15 @@ member or a raw string.
|
|
|
211
231
|
|
|
212
232
|
## Pagination
|
|
213
233
|
|
|
214
|
-
The search and
|
|
215
|
-
fetches each subsequent page for you. `search.people`/`search.companies
|
|
216
|
-
`jobs.search`/`jobs.company`
|
|
217
|
-
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.
|
|
218
238
|
|
|
219
239
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
220
|
-
> **bills 1
|
|
240
|
+
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
221
241
|
> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
|
|
222
|
-
> employee finder: 10k; jobs: 5k), which can be a lot of
|
|
242
|
+
> employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
|
|
223
243
|
> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
|
|
224
244
|
> `break` out of the loop, or drive pages manually.
|
|
225
245
|
|
|
@@ -247,6 +267,13 @@ for job in client.jobs.search(
|
|
|
247
267
|
).auto_paging_iter(max_items=200):
|
|
248
268
|
print(job.company_name, job.title, job.location.city if job.location else None)
|
|
249
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
|
+
|
|
250
277
|
# Or page manually.
|
|
251
278
|
page = client.search.people(people={...}, max_results=50)
|
|
252
279
|
print(page.results, page.cursor)
|
|
@@ -256,6 +283,37 @@ nxt = page.get_next_page() # None once exhausted
|
|
|
256
283
|
The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
|
|
257
284
|
exported from `blitz_api`.
|
|
258
285
|
|
|
286
|
+
## Usage & rate limit (`fair_usage`)
|
|
287
|
+
|
|
288
|
+
Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
|
|
289
|
+
the plan, your rate-limit headroom, and a request id to quote to support. It's on every
|
|
290
|
+
response model and on every page, so you can meter a long run without extra `key_info()`
|
|
291
|
+
calls.
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
|
|
295
|
+
if result.fair_usage is not None:
|
|
296
|
+
print(result.fair_usage.records_used) # what this call cost
|
|
297
|
+
print(result.fair_usage.records_remaining) # a number, or "unlimited"
|
|
298
|
+
print(result.fair_usage.next_reset_at) # None on an unlimited plan
|
|
299
|
+
print(result.fair_usage.request_id) # quote this to support
|
|
300
|
+
if result.fair_usage.rate_limit is not None: # absent on account.key_info()
|
|
301
|
+
print(result.fair_usage.rate_limit.remaining_this_second)
|
|
302
|
+
|
|
303
|
+
# Pages carry the block of the request that fetched them.
|
|
304
|
+
for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
|
|
305
|
+
print(page.fair_usage.records_used if page.fair_usage else None)
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
|
|
309
|
+
resets without a second call:
|
|
310
|
+
|
|
311
|
+
```python
|
|
312
|
+
except InsufficientRecordsError as err:
|
|
313
|
+
if err.fair_usage is not None:
|
|
314
|
+
print("resets at", err.fair_usage.next_reset_at)
|
|
315
|
+
```
|
|
316
|
+
|
|
259
317
|
## Configuration
|
|
260
318
|
|
|
261
319
|
```python
|
|
@@ -271,11 +329,13 @@ client = BlitzAPI(
|
|
|
271
329
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
272
330
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
273
331
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
274
|
-
endpoint (
|
|
275
|
-
`client.account.key_info().max_requests_per_seconds`).
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
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.
|
|
279
339
|
|
|
280
340
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
281
341
|
endpoint needs longer than the client default:
|
|
@@ -288,15 +348,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
|
|
|
288
348
|
|
|
289
349
|
```python
|
|
290
350
|
from blitz_api import (
|
|
291
|
-
BlitzError, AuthenticationError,
|
|
351
|
+
BlitzError, AuthenticationError, InsufficientRecordsError,
|
|
292
352
|
NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
|
|
293
353
|
APITimeoutError, APIResponseValidationError,
|
|
294
354
|
)
|
|
295
355
|
|
|
296
356
|
try:
|
|
297
357
|
client.enrichment.email(person_linkedin_url="...")
|
|
298
|
-
except
|
|
299
|
-
... # 402 — out of
|
|
358
|
+
except InsufficientRecordsError as err:
|
|
359
|
+
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
300
360
|
except AuthenticationError:
|
|
301
361
|
... # 401 — bad key
|
|
302
362
|
except APIStatusError as err:
|
|
@@ -22,7 +22,7 @@ and enrichment.
|
|
|
22
22
|
|
|
23
23
|
> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
|
|
24
24
|
> loop streams every match up to the server-side limit (people: 50k results), which can be
|
|
25
|
-
> a lot of
|
|
25
|
+
> a lot of records. Bound spend with **`max_items`** (a client-side total cap on
|
|
26
26
|
> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
|
|
27
27
|
> [Pagination](#pagination).
|
|
28
28
|
|
|
@@ -34,6 +34,7 @@ and enrichment.
|
|
|
34
34
|
- [Authentication](#authentication)
|
|
35
35
|
- [Endpoints](#endpoints)
|
|
36
36
|
- [Pagination](#pagination)
|
|
37
|
+
- [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
|
|
37
38
|
- [Configuration](#configuration)
|
|
38
39
|
- [Error handling](#error-handling)
|
|
39
40
|
- [Forward compatibility](#forward-compatibility)
|
|
@@ -58,7 +59,7 @@ from blitz_api.types import Industry, JobLevel
|
|
|
58
59
|
with BlitzAPI() as client:
|
|
59
60
|
# Health-check the key before a batch job.
|
|
60
61
|
info = client.account.key_info()
|
|
61
|
-
print(info.valid, info.
|
|
62
|
+
print(info.valid, info.records_remaining, info.max_requests_per_seconds)
|
|
62
63
|
|
|
63
64
|
# LinkedIn profile URL -> verified work email.
|
|
64
65
|
email = client.enrichment.email(
|
|
@@ -96,7 +97,7 @@ asyncio.run(main())
|
|
|
96
97
|
## Example: find, enrich, collect
|
|
97
98
|
|
|
98
99
|
A complete flow — find people, enrich each one's verified work email, collect the
|
|
99
|
-
contacts. `max_items` caps the total fetched so the run can't surprise you with
|
|
100
|
+
contacts. `max_items` caps the total fetched so the run can't surprise you with records.
|
|
100
101
|
|
|
101
102
|
```python
|
|
102
103
|
from blitz_api import BlitzAPI
|
|
@@ -109,7 +110,7 @@ leads = client.search.people(
|
|
|
109
110
|
company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
|
|
110
111
|
people={"job_level": [JobLevel.VP]},
|
|
111
112
|
max_results=25,
|
|
112
|
-
).collect(max_items=25) # client-side total cap — bounds
|
|
113
|
+
).collect(max_items=25) # client-side total cap — bounds record spend
|
|
113
114
|
|
|
114
115
|
# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
|
|
115
116
|
contacts: list[dict[str, str | None]] = []
|
|
@@ -130,14 +131,33 @@ later are preserved):
|
|
|
130
131
|
```python
|
|
131
132
|
Person(
|
|
132
133
|
full_name="Jordan Lee",
|
|
133
|
-
|
|
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",
|
|
134
137
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
135
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.
|
|
136
141
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
137
142
|
# first_name, last_name, skills, education, certifications, … also present
|
|
138
143
|
)
|
|
139
144
|
```
|
|
140
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
|
+
|
|
141
161
|
And `enrichment.email(...)` returns:
|
|
142
162
|
|
|
143
163
|
```python
|
|
@@ -169,8 +189,8 @@ All methods are grouped into seven namespaces:
|
|
|
169
189
|
| `client.account` | `key_info()` |
|
|
170
190
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
171
191
|
| `client.jobs` | `search()`, `company()` |
|
|
172
|
-
| `client.company` | `tam_by_jobs()` |
|
|
173
|
-
| `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()` |
|
|
174
194
|
| `client.utils` | `current_date()` |
|
|
175
195
|
| `client.changelog` | `list()` |
|
|
176
196
|
|
|
@@ -180,15 +200,15 @@ member or a raw string.
|
|
|
180
200
|
|
|
181
201
|
## Pagination
|
|
182
202
|
|
|
183
|
-
The search and
|
|
184
|
-
fetches each subsequent page for you. `search.people`/`search.companies
|
|
185
|
-
`jobs.search`/`jobs.company`
|
|
186
|
-
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.
|
|
187
207
|
|
|
188
208
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
189
|
-
> **bills 1
|
|
209
|
+
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
190
210
|
> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
|
|
191
|
-
> employee finder: 10k; jobs: 5k), which can be a lot of
|
|
211
|
+
> employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
|
|
192
212
|
> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
|
|
193
213
|
> `break` out of the loop, or drive pages manually.
|
|
194
214
|
|
|
@@ -216,6 +236,13 @@ for job in client.jobs.search(
|
|
|
216
236
|
).auto_paging_iter(max_items=200):
|
|
217
237
|
print(job.company_name, job.title, job.location.city if job.location else None)
|
|
218
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
|
+
|
|
219
246
|
# Or page manually.
|
|
220
247
|
page = client.search.people(people={...}, max_results=50)
|
|
221
248
|
print(page.results, page.cursor)
|
|
@@ -225,6 +252,37 @@ nxt = page.get_next_page() # None once exhausted
|
|
|
225
252
|
The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
|
|
226
253
|
exported from `blitz_api`.
|
|
227
254
|
|
|
255
|
+
## Usage & rate limit (`fair_usage`)
|
|
256
|
+
|
|
257
|
+
Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
|
|
258
|
+
the plan, your rate-limit headroom, and a request id to quote to support. It's on every
|
|
259
|
+
response model and on every page, so you can meter a long run without extra `key_info()`
|
|
260
|
+
calls.
|
|
261
|
+
|
|
262
|
+
```python
|
|
263
|
+
result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
|
|
264
|
+
if result.fair_usage is not None:
|
|
265
|
+
print(result.fair_usage.records_used) # what this call cost
|
|
266
|
+
print(result.fair_usage.records_remaining) # a number, or "unlimited"
|
|
267
|
+
print(result.fair_usage.next_reset_at) # None on an unlimited plan
|
|
268
|
+
print(result.fair_usage.request_id) # quote this to support
|
|
269
|
+
if result.fair_usage.rate_limit is not None: # absent on account.key_info()
|
|
270
|
+
print(result.fair_usage.rate_limit.remaining_this_second)
|
|
271
|
+
|
|
272
|
+
# Pages carry the block of the request that fetched them.
|
|
273
|
+
for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
|
|
274
|
+
print(page.fair_usage.records_used if page.fair_usage else None)
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
|
|
278
|
+
resets without a second call:
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
except InsufficientRecordsError as err:
|
|
282
|
+
if err.fair_usage is not None:
|
|
283
|
+
print("resets at", err.fair_usage.next_reset_at)
|
|
284
|
+
```
|
|
285
|
+
|
|
228
286
|
## Configuration
|
|
229
287
|
|
|
230
288
|
```python
|
|
@@ -240,11 +298,13 @@ client = BlitzAPI(
|
|
|
240
298
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
241
299
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
242
300
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
243
|
-
endpoint (
|
|
244
|
-
`client.account.key_info().max_requests_per_seconds`).
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
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.
|
|
248
308
|
|
|
249
309
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
250
310
|
endpoint needs longer than the client default:
|
|
@@ -257,15 +317,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
|
|
|
257
317
|
|
|
258
318
|
```python
|
|
259
319
|
from blitz_api import (
|
|
260
|
-
BlitzError, AuthenticationError,
|
|
320
|
+
BlitzError, AuthenticationError, InsufficientRecordsError,
|
|
261
321
|
NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
|
|
262
322
|
APITimeoutError, APIResponseValidationError,
|
|
263
323
|
)
|
|
264
324
|
|
|
265
325
|
try:
|
|
266
326
|
client.enrichment.email(person_linkedin_url="...")
|
|
267
|
-
except
|
|
268
|
-
... # 402 — out of
|
|
327
|
+
except InsufficientRecordsError as err:
|
|
328
|
+
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
269
329
|
except AuthenticationError:
|
|
270
330
|
... # 401 — bad key
|
|
271
331
|
except APIStatusError as err:
|
|
@@ -23,7 +23,7 @@ from ._exceptions import (
|
|
|
23
23
|
APITimeoutError,
|
|
24
24
|
AuthenticationError,
|
|
25
25
|
BlitzError,
|
|
26
|
-
|
|
26
|
+
InsufficientRecordsError,
|
|
27
27
|
NotFoundError,
|
|
28
28
|
RateLimitError,
|
|
29
29
|
ServerError,
|
|
@@ -34,6 +34,7 @@ from ._version import __version__
|
|
|
34
34
|
from .types import (
|
|
35
35
|
CompanyFilter,
|
|
36
36
|
Industry,
|
|
37
|
+
PeopleCompanyFilter,
|
|
37
38
|
PeopleFilter,
|
|
38
39
|
)
|
|
39
40
|
|
|
@@ -54,12 +55,13 @@ __all__ = [
|
|
|
54
55
|
"APIResponseValidationError",
|
|
55
56
|
"APIStatusError",
|
|
56
57
|
"AuthenticationError",
|
|
57
|
-
"
|
|
58
|
+
"InsufficientRecordsError",
|
|
58
59
|
"NotFoundError",
|
|
59
60
|
"RateLimitError",
|
|
60
61
|
"ServerError",
|
|
61
62
|
# commonly-used types (full set under blitz_api.types)
|
|
62
63
|
"Industry",
|
|
63
64
|
"CompanyFilter",
|
|
65
|
+
"PeopleCompanyFilter",
|
|
64
66
|
"PeopleFilter",
|
|
65
67
|
]
|
|
@@ -24,7 +24,7 @@ from ._exceptions import (
|
|
|
24
24
|
APIStatusError,
|
|
25
25
|
AuthenticationError,
|
|
26
26
|
BlitzError,
|
|
27
|
-
|
|
27
|
+
InsufficientRecordsError,
|
|
28
28
|
NotFoundError,
|
|
29
29
|
RateLimitError,
|
|
30
30
|
ServerError,
|
|
@@ -39,7 +39,7 @@ ResponseT = TypeVar("ResponseT", bound=BaseModel)
|
|
|
39
39
|
# falls back to a generic APIStatusError (or ServerError for any 5xx).
|
|
40
40
|
_STATUS_EXCEPTIONS: dict[int, type[APIStatusError]] = {
|
|
41
41
|
401: AuthenticationError,
|
|
42
|
-
402:
|
|
42
|
+
402: InsufficientRecordsError,
|
|
43
43
|
404: NotFoundError,
|
|
44
44
|
429: RateLimitError,
|
|
45
45
|
}
|
|
@@ -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.
|