blitz-api-py 4.1.0__tar.gz → 4.2.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-4.1.0 → blitz_api_py-4.2.0}/CHANGELOG.md +8 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/PKG-INFO +24 -19
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/README.md +22 -17
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/pyproject.toml +1 -1
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_constants.py +5 -4
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_exceptions.py +7 -2
- blitz_api_py-4.2.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/enrichment.py +8 -3
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/search.py +9 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/enrichment.py +8 -3
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/search.py +9 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enrichment.py +7 -1
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/filters.py +25 -16
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/shared.py +7 -8
- blitz_api_py-4.1.0/src/blitz_api/_version.py +0 -1
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/.gitignore +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/LICENSE +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/__init__.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_base_client.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_async.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_sync.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_async.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_base.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_sync.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/__init__.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/account.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/changelog.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/company.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/jobs.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/account.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/company.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/__init__.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/_models.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/account.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/changelog.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/company.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enums.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/jobs.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/search.py +0 -0
- {blitz_api_py-4.1.0 → blitz_api_py-4.2.0}/src/blitz_api/types/utils.py +0 -0
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [4.2.0](https://github.com/api-blitz/blitz-api-py/compare/v4.1.0...v4.2.0) (2026-10-27)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* sync with the 2026-10-20 API release ([00fb319](https://github.com/api-blitz/blitz-api-py/commit/00fb31984488fa64561dd23e136963dd0eaea7e1))
|
|
9
|
+
* sync with the 2026-10-20 API release ([aba0662](https://github.com/api-blitz/blitz-api-py/commit/aba066208f802d07b1a9fc1a44fd1e023c835e2c))
|
|
10
|
+
|
|
3
11
|
## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
|
|
4
12
|
|
|
5
13
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: blitz-api-py
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.2.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
|
|
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/api-blitz/blitz-api-py/blob/main/CHAN
|
|
|
10
10
|
Author-email: Blitz API <founders@blitz-api.ai>
|
|
11
11
|
License-Expression: MIT
|
|
12
12
|
License-File: LICENSE
|
|
13
|
-
Keywords: b2b,blitz,blitz-api,enrichment,gtm,
|
|
13
|
+
Keywords: b2b,blitz,blitz-api,enrichment,gtm,sales,sdk
|
|
14
14
|
Classifier: Development Status :: 4 - Beta
|
|
15
15
|
Classifier: Intended Audience :: Developers
|
|
16
16
|
Classifier: License :: OSI Approved :: MIT License
|
|
@@ -162,24 +162,22 @@ later are preserved):
|
|
|
162
162
|
```python
|
|
163
163
|
Person(
|
|
164
164
|
full_name="Jordan Lee",
|
|
165
|
-
# Derived from the
|
|
165
|
+
# Derived from the matched position as "<job title> | @<employer>" — not the
|
|
166
166
|
# free-text headline written on the LinkedIn profile.
|
|
167
167
|
headline="VP of Engineering | @Acme",
|
|
168
168
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
169
169
|
location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
|
|
170
|
-
#
|
|
171
|
-
# current
|
|
170
|
+
# Only the position that matched your filters — `job_is_current` says whether it
|
|
171
|
+
# is current (past jobs are searched only with `include_past_jobs`).
|
|
172
172
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
173
173
|
# first_name, last_name, skills, education, certifications, … also present
|
|
174
174
|
)
|
|
175
175
|
```
|
|
176
176
|
|
|
177
|
-
**How many positions land in `experiences[]` depends on the endpoint
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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):
|
|
177
|
+
**How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
|
|
178
|
+
`search.employee_finder` and `search.waterfall_icp` return one row per person, with only
|
|
179
|
+
the position that matched. If you need the person's whole career in profile order,
|
|
180
|
+
`enrichment.person` returns it (1 record on success, free on a miss):
|
|
183
181
|
|
|
184
182
|
```python
|
|
185
183
|
if person.linkedin_url: # optional on Person; the call requires a str
|
|
@@ -378,13 +376,14 @@ client = BlitzAPI(
|
|
|
378
376
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
379
377
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
380
378
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
381
|
-
endpoint (
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
379
|
+
endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
|
|
380
|
+
custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
|
|
381
|
+
account, so every API key of the account shares it; check yours via
|
|
382
|
+
`client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
|
|
383
|
+
limit — raise it to your key's limit to use the full budget. A single
|
|
385
384
|
client instance therefore stays under the limit on every endpoint, so a burst on one
|
|
386
|
-
never blocks another. Across multiple processes
|
|
387
|
-
may still hit `429`; the retry path handles that.
|
|
385
|
+
never blocks another. Across multiple processes (or several keys of one account) — which
|
|
386
|
+
share an endpoint's budget — you may still hit `429`; the retry path handles that.
|
|
388
387
|
|
|
389
388
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
390
389
|
endpoint needs longer than the client default:
|
|
@@ -407,7 +406,7 @@ try:
|
|
|
407
406
|
except InsufficientRecordsError as err:
|
|
408
407
|
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
409
408
|
except AuthenticationError:
|
|
410
|
-
... # 401 —
|
|
409
|
+
... # 401 — missing/invalid key, or no access to this endpoint
|
|
411
410
|
except APIStatusError as err:
|
|
412
411
|
print(err.status_code, err.message, err.body)
|
|
413
412
|
except APIResponseValidationError:
|
|
@@ -417,10 +416,16 @@ except BlitzError:
|
|
|
417
416
|
```
|
|
418
417
|
|
|
419
418
|
`429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
|
|
420
|
-
`401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
|
|
419
|
+
`401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
|
|
421
420
|
but a **read timeout is not** — the server may already have processed (and billed) the
|
|
422
421
|
request, so it surfaces as `APITimeoutError` rather than risking a double charge.
|
|
423
422
|
|
|
423
|
+
An invalid request body (including an unknown field at any depth) raises `APIStatusError`
|
|
424
|
+
with `status_code == 422`: `err.message` sums up the first three problems, and
|
|
425
|
+
`err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
|
|
426
|
+
full field path and what to fix. A locked account gets `423`
|
|
427
|
+
(`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
|
|
428
|
+
|
|
424
429
|
## Forward compatibility
|
|
425
430
|
|
|
426
431
|
Response models subclass a base configured with `extra="allow"`, so a field the API adds
|
|
@@ -131,24 +131,22 @@ later are preserved):
|
|
|
131
131
|
```python
|
|
132
132
|
Person(
|
|
133
133
|
full_name="Jordan Lee",
|
|
134
|
-
# Derived from the
|
|
134
|
+
# Derived from the matched position as "<job title> | @<employer>" — not the
|
|
135
135
|
# free-text headline written on the LinkedIn profile.
|
|
136
136
|
headline="VP of Engineering | @Acme",
|
|
137
137
|
linkedin_url="https://www.linkedin.com/in/example-person",
|
|
138
138
|
location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
|
|
139
|
-
#
|
|
140
|
-
# current
|
|
139
|
+
# Only the position that matched your filters — `job_is_current` says whether it
|
|
140
|
+
# is current (past jobs are searched only with `include_past_jobs`).
|
|
141
141
|
experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
|
|
142
142
|
# first_name, last_name, skills, education, certifications, … also present
|
|
143
143
|
)
|
|
144
144
|
```
|
|
145
145
|
|
|
146
|
-
**How many positions land in `experiences[]` depends on the endpoint
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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):
|
|
146
|
+
**How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
|
|
147
|
+
`search.employee_finder` and `search.waterfall_icp` return one row per person, with only
|
|
148
|
+
the position that matched. If you need the person's whole career in profile order,
|
|
149
|
+
`enrichment.person` returns it (1 record on success, free on a miss):
|
|
152
150
|
|
|
153
151
|
```python
|
|
154
152
|
if person.linkedin_url: # optional on Person; the call requires a str
|
|
@@ -347,13 +345,14 @@ client = BlitzAPI(
|
|
|
347
345
|
The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
|
|
348
346
|
in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
|
|
349
347
|
`.phone`) is throttled independently, mirroring the API's own limit, which is also per
|
|
350
|
-
endpoint (
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
348
|
+
endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
|
|
349
|
+
custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
|
|
350
|
+
account, so every API key of the account shares it; check yours via
|
|
351
|
+
`client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
|
|
352
|
+
limit — raise it to your key's limit to use the full budget. A single
|
|
354
353
|
client instance therefore stays under the limit on every endpoint, so a burst on one
|
|
355
|
-
never blocks another. Across multiple processes
|
|
356
|
-
may still hit `429`; the retry path handles that.
|
|
354
|
+
never blocks another. Across multiple processes (or several keys of one account) — which
|
|
355
|
+
share an endpoint's budget — you may still hit `429`; the retry path handles that.
|
|
357
356
|
|
|
358
357
|
Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
|
|
359
358
|
endpoint needs longer than the client default:
|
|
@@ -376,7 +375,7 @@ try:
|
|
|
376
375
|
except InsufficientRecordsError as err:
|
|
377
376
|
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
378
377
|
except AuthenticationError:
|
|
379
|
-
... # 401 —
|
|
378
|
+
... # 401 — missing/invalid key, or no access to this endpoint
|
|
380
379
|
except APIStatusError as err:
|
|
381
380
|
print(err.status_code, err.message, err.body)
|
|
382
381
|
except APIResponseValidationError:
|
|
@@ -386,10 +385,16 @@ except BlitzError:
|
|
|
386
385
|
```
|
|
387
386
|
|
|
388
387
|
`429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
|
|
389
|
-
`401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
|
|
388
|
+
`401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
|
|
390
389
|
but a **read timeout is not** — the server may already have processed (and billed) the
|
|
391
390
|
request, so it surfaces as `APITimeoutError` rather than risking a double charge.
|
|
392
391
|
|
|
392
|
+
An invalid request body (including an unknown field at any depth) raises `APIStatusError`
|
|
393
|
+
with `status_code == 422`: `err.message` sums up the first three problems, and
|
|
394
|
+
`err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
|
|
395
|
+
full field path and what to fix. A locked account gets `423`
|
|
396
|
+
(`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
|
|
397
|
+
|
|
393
398
|
## Forward compatibility
|
|
394
399
|
|
|
395
400
|
Response models subclass a base configured with `extra="allow"`, so a field the API adds
|
|
@@ -11,7 +11,7 @@ requires-python = ">=3.10"
|
|
|
11
11
|
license = "MIT"
|
|
12
12
|
license-files = ["LICENSE"]
|
|
13
13
|
authors = [{ name = "Blitz API", email = "founders@blitz-api.ai" }]
|
|
14
|
-
keywords = ["blitz", "blitz-api", "b2b", "enrichment", "
|
|
14
|
+
keywords = ["blitz", "blitz-api", "b2b", "enrichment", "sales", "gtm", "sdk"]
|
|
15
15
|
classifiers = [
|
|
16
16
|
"Development Status :: 4 - Beta",
|
|
17
17
|
"Intended Audience :: Developers",
|
|
@@ -20,10 +20,11 @@ DEFAULT_TIMEOUT = 30.0
|
|
|
20
20
|
DEFAULT_MAX_RETRIES = 3
|
|
21
21
|
|
|
22
22
|
#: Default client-side rate limit, applied **per endpoint** (one sliding window each).
|
|
23
|
-
#: The API limits each endpoint
|
|
24
|
-
#:
|
|
25
|
-
#:
|
|
26
|
-
#: value, discoverable via
|
|
23
|
+
#: The API limits each endpoint independently, per account, at a rate set by the plan: 5 req/s
|
|
24
|
+
#: on the free trial, 10 on Start, 25 on Scale, custom on Build Your Infra (50 on plans created
|
|
25
|
+
#: before 2026-09-30). This default is the free-trial limit, so it leaves throughput on the
|
|
26
|
+
#: table on paid plans: raise it to your key's actual per-endpoint value, discoverable via
|
|
27
|
+
#: ``client.account.key_info().max_requests_per_seconds``.
|
|
27
28
|
DEFAULT_RATE_LIMIT_RPS = 5.0
|
|
28
29
|
|
|
29
30
|
#: Seconds to wait after a 429 when the response has no ``Retry-After`` header.
|
|
@@ -119,7 +119,11 @@ class APIStatusError(BlitzError):
|
|
|
119
119
|
|
|
120
120
|
|
|
121
121
|
class AuthenticationError(APIStatusError):
|
|
122
|
-
"""401 — the API key is missing or invalid
|
|
122
|
+
"""401 — the API key is missing or invalid, or valid but without access to this endpoint
|
|
123
|
+
(``"You do not have access to this route"``).
|
|
124
|
+
|
|
125
|
+
A locked account gets a ``423`` instead, raised as a plain :class:`APIStatusError`.
|
|
126
|
+
"""
|
|
123
127
|
|
|
124
128
|
|
|
125
129
|
class InsufficientRecordsError(APIStatusError):
|
|
@@ -131,7 +135,8 @@ class InsufficientRecordsError(APIStatusError):
|
|
|
131
135
|
|
|
132
136
|
|
|
133
137
|
class NotFoundError(APIStatusError):
|
|
134
|
-
"""404 —
|
|
138
|
+
"""404 — unknown path, or ``account.key_info`` found no billing account
|
|
139
|
+
(``"Customer not found"``). An unknown key is a ``401``."""
|
|
135
140
|
|
|
136
141
|
|
|
137
142
|
class RateLimitError(APIStatusError):
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "4.2.0" # x-release-please-version
|
|
@@ -173,10 +173,15 @@ class AsyncEnrichmentResource:
|
|
|
173
173
|
) -> CompanyDistributionByDepartmentResponse:
|
|
174
174
|
"""Get a company's employee count broken down by department.
|
|
175
175
|
|
|
176
|
-
|
|
176
|
+
Counts current **jobs** at the company, not people, once per current job: a person with
|
|
177
|
+
two current jobs there counts twice in ``total_employees`` (once in each job's
|
|
178
|
+
department), so ``total_employees`` can exceed the one from
|
|
179
|
+
``company_distribution_by_country``.
|
|
177
180
|
|
|
178
|
-
|
|
179
|
-
|
|
181
|
+
Jobs with no classified department are counted under ``"Other"``.
|
|
182
|
+
|
|
183
|
+
``is_recent_hire=True`` counts only the current jobs at the company that started in the
|
|
184
|
+
last 90 days (a job with no start date is not counted).
|
|
180
185
|
"""
|
|
181
186
|
return await self._client._request(
|
|
182
187
|
"POST",
|
|
@@ -96,6 +96,10 @@ class AsyncSearchResource:
|
|
|
96
96
|
started in the last 90 days (that job must also match ``job_level`` and
|
|
97
97
|
``job_function``; a job with no start date never matches).
|
|
98
98
|
|
|
99
|
+
Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
|
|
100
|
+
defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
|
|
101
|
+
filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
|
|
102
|
+
|
|
99
103
|
Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
|
|
100
104
|
for manual control.
|
|
101
105
|
"""
|
|
@@ -138,6 +142,11 @@ class AsyncSearchResource:
|
|
|
138
142
|
``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
|
|
139
143
|
held *before* at the company; the company and that tier's title filters must then hold
|
|
140
144
|
in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
|
|
145
|
+
|
|
146
|
+
Each tier's ``location`` takes the same object as ``people.location`` on
|
|
147
|
+
``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
|
|
148
|
+
every field you set, and leaving it out searches the whole world. Here each list takes
|
|
149
|
+
at most 10 values (a longer one is a ``422``).
|
|
141
150
|
"""
|
|
142
151
|
body = {
|
|
143
152
|
"company_linkedin_url": company_linkedin_url,
|
|
@@ -175,10 +175,15 @@ class EnrichmentResource:
|
|
|
175
175
|
) -> CompanyDistributionByDepartmentResponse:
|
|
176
176
|
"""Get a company's employee count broken down by department.
|
|
177
177
|
|
|
178
|
-
|
|
178
|
+
Counts current **jobs** at the company, not people, once per current job: a person with
|
|
179
|
+
two current jobs there counts twice in ``total_employees`` (once in each job's
|
|
180
|
+
department), so ``total_employees`` can exceed the one from
|
|
181
|
+
``company_distribution_by_country``.
|
|
179
182
|
|
|
180
|
-
|
|
181
|
-
|
|
183
|
+
Jobs with no classified department are counted under ``"Other"``.
|
|
184
|
+
|
|
185
|
+
``is_recent_hire=True`` counts only the current jobs at the company that started in the
|
|
186
|
+
last 90 days (a job with no start date is not counted).
|
|
182
187
|
"""
|
|
183
188
|
return self._client._request(
|
|
184
189
|
"POST",
|
|
@@ -98,6 +98,10 @@ class SearchResource:
|
|
|
98
98
|
started in the last 90 days (that job must also match ``job_level`` and
|
|
99
99
|
``job_function``; a job with no start date never matches).
|
|
100
100
|
|
|
101
|
+
Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
|
|
102
|
+
defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
|
|
103
|
+
filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
|
|
104
|
+
|
|
101
105
|
Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
|
|
102
106
|
for manual control.
|
|
103
107
|
"""
|
|
@@ -140,6 +144,11 @@ class SearchResource:
|
|
|
140
144
|
``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
|
|
141
145
|
held *before* at the company; the company and that tier's title filters must then hold
|
|
142
146
|
in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
|
|
147
|
+
|
|
148
|
+
Each tier's ``location`` takes the same object as ``people.location`` on
|
|
149
|
+
``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
|
|
150
|
+
every field you set, and leaving it out searches the whole world. Here each list takes
|
|
151
|
+
at most 10 values (a longer one is a ``422``).
|
|
143
152
|
"""
|
|
144
153
|
body = {
|
|
145
154
|
"company_linkedin_url": company_linkedin_url,
|
|
@@ -142,7 +142,9 @@ class CompanyDistributionByCountryResponse(BlitzResponse):
|
|
|
142
142
|
class CompanyDistributionByDepartmentItem(BlitzModel):
|
|
143
143
|
"""Employee count for a single department (Blitz job function).
|
|
144
144
|
|
|
145
|
-
|
|
145
|
+
``count`` counts current jobs at the company, not people, once per current job: a person
|
|
146
|
+
with two current jobs there counts twice in ``total_employees`` (once in each job's
|
|
147
|
+
department). Jobs with no classified department are counted under ``"Other"``.
|
|
146
148
|
``percentage_ratio`` is the bucket's share of ``total_employees`` (0-100, to 2
|
|
147
149
|
decimals).
|
|
148
150
|
"""
|
|
@@ -157,6 +159,10 @@ class CompanyDistributionByDepartmentResponse(BlitzResponse):
|
|
|
157
159
|
|
|
158
160
|
Served by ``POST /v2/enrichment/company-distribution-by-department``.
|
|
159
161
|
|
|
162
|
+
``total_employees`` counts current jobs at the company, not people (a person with two
|
|
163
|
+
current jobs there counts twice), so it can exceed the one from
|
|
164
|
+
``enrichment.company_distribution_by_country``.
|
|
165
|
+
|
|
160
166
|
``found`` is ``False`` (and the call costs no records) when the company is unknown or
|
|
161
167
|
has no current employees.
|
|
162
168
|
"""
|
|
@@ -6,8 +6,9 @@ fields accept either an enum member (autocompleted, e.g. ``Industry.BANKING``) o
|
|
|
6
6
|
a raw string, so power users are never blocked.
|
|
7
7
|
|
|
8
8
|
All keys are optional unless noted; omit a filter to leave it unset. The search
|
|
9
|
-
endpoints cap every filter list at **50 entries**
|
|
10
|
-
``422``, so split a bigger
|
|
9
|
+
endpoints cap every filter list at **50 entries** (10 in a waterfall tier's ``location``,
|
|
10
|
+
see :class:`CascadeTier`) — a longer list is rejected with a ``422``, so split a bigger
|
|
11
|
+
inclusion/exclusion set across several requests.
|
|
11
12
|
"""
|
|
12
13
|
|
|
13
14
|
from __future__ import annotations
|
|
@@ -143,7 +144,7 @@ class CompanyFilter(TypedDict, total=False):
|
|
|
143
144
|
``company.tam_by_people``.
|
|
144
145
|
|
|
145
146
|
``linkedin_url`` is deliberately **not** here: only the people-side endpoints honour
|
|
146
|
-
it, and ``search.companies``
|
|
147
|
+
it, and ``search.companies`` rejects it with a ``422``. See :class:`PeopleCompanyFilter`.
|
|
147
148
|
"""
|
|
148
149
|
|
|
149
150
|
name: KeywordFilter
|
|
@@ -176,11 +177,9 @@ class PeopleCompanyFilter(CompanyFilter, total=False):
|
|
|
176
177
|
Extending, rather than leaving ``linkedin_url`` on the shared filter, keeps it off
|
|
177
178
|
``search.companies``: the live spec declares it on the ``company`` object of
|
|
178
179
|
``/v2/search/people`` and ``/v2/company/tam-by-people`` but **not**
|
|
179
|
-
``/v2/search/companies``,
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
removed from :class:`PeopleFilter`, and the same split as :class:`TamPeopleFilter` over
|
|
183
|
-
:class:`PeopleFilter`.
|
|
180
|
+
``/v2/search/companies``, which rejects the key with a ``422`` naming the field (since
|
|
181
|
+
2026-09-28; it used to be accepted and ignored). Same split as :class:`TamPeopleFilter`
|
|
182
|
+
over :class:`PeopleFilter`.
|
|
184
183
|
|
|
185
184
|
The assignability caveat on :class:`TamJobFilter` applies verbatim: this only rejects a
|
|
186
185
|
``search.companies`` call site that passes a *dict literal* carrying ``linkedin_url``.
|
|
@@ -202,9 +201,12 @@ class PeopleJobTitleFilter(TypedDict, total=False):
|
|
|
202
201
|
|
|
203
202
|
|
|
204
203
|
class PeopleLocationFilter(TypedDict, total=False):
|
|
205
|
-
"""Location filter for the people side of a people search
|
|
204
|
+
"""Location filter for the people side of a people search, and for each waterfall tier
|
|
205
|
+
(:class:`CascadeTier`). A person must match every field you set.
|
|
206
|
+
"""
|
|
206
207
|
|
|
207
208
|
city: KeywordFilter
|
|
209
|
+
# Codes such as ``"FR"`` or ``"GB"`` (2-3 letters, any case).
|
|
208
210
|
country_code: list[str]
|
|
209
211
|
continent: list[ContinentValue]
|
|
210
212
|
sales_region: list[SalesRegionValue]
|
|
@@ -227,9 +229,8 @@ class PeopleFilter(TypedDict, total=False):
|
|
|
227
229
|
"""People search criteria for ``search.people``.
|
|
228
230
|
|
|
229
231
|
``linkedin_url`` is deliberately absent: ``/v2/search/people`` stopped honouring it
|
|
230
|
-
on 2026-09-11
|
|
231
|
-
|
|
232
|
-
people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
|
|
232
|
+
on 2026-09-11, and since 2026-09-28 rejects it with a ``422`` naming the field. Match
|
|
233
|
+
specific people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
|
|
233
234
|
which still accepts it.
|
|
234
235
|
|
|
235
236
|
This is the persona criteria ``search.people`` and ``company.tam_by_people`` share;
|
|
@@ -246,6 +247,7 @@ class PeopleFilter(TypedDict, total=False):
|
|
|
246
247
|
job_title: PeopleJobTitleFilter
|
|
247
248
|
job_function: list[JobFunctionValue]
|
|
248
249
|
job_level: list[JobLevelValue]
|
|
250
|
+
# Smallest LinkedIn connection count (0-500, ``0`` = no lower bound); above 500 is a ``422``.
|
|
249
251
|
min_connections: int
|
|
250
252
|
location: PeopleLocationFilter
|
|
251
253
|
# ``| KeywordFilter`` is deliberate: this field was a ``KeywordFilter`` before it gained
|
|
@@ -286,9 +288,16 @@ class SearchPeopleFilter(PeopleFilter, total=False):
|
|
|
286
288
|
class CascadeTier(TypedDict):
|
|
287
289
|
"""One tier of a waterfall ICP cascade, tried in order until results are found.
|
|
288
290
|
|
|
289
|
-
Only ``include_title`` is required; the server defaults ``
|
|
290
|
-
|
|
291
|
-
|
|
291
|
+
Only ``include_title`` is required; the server defaults ``include_headline_search`` to
|
|
292
|
+
``False`` when omitted. The ``cascade`` list is capped at **10 tiers**, and each tier at
|
|
293
|
+
50 title phrases.
|
|
294
|
+
|
|
295
|
+
``location`` takes the same object as ``people.location`` on ``search.people``
|
|
296
|
+
(:class:`PeopleLocationFilter`): a person must match every field you set, and leaving it
|
|
297
|
+
out searches the whole world. Each list in it takes at most **10 values**; a longer list
|
|
298
|
+
is a ``422``. A plain list of country codes (``["US", "CA"]``) is the legacy form, still
|
|
299
|
+
accepted: it is read as ``country_code``, with the same 10-code cap, and a list holding
|
|
300
|
+
``"WORLD"`` turns the location filter off.
|
|
292
301
|
|
|
293
302
|
``is_recent_hire``, ``include_active_jobs`` and ``include_past_jobs`` are per-tier keys,
|
|
294
303
|
not arguments of ``search.waterfall_icp``: each tier can scope its own search, so a
|
|
@@ -296,7 +305,7 @@ class CascadeTier(TypedDict):
|
|
|
296
305
|
"""
|
|
297
306
|
|
|
298
307
|
include_title: list[str]
|
|
299
|
-
location: NotRequired[list[str]]
|
|
308
|
+
location: NotRequired[PeopleLocationFilter | list[str]]
|
|
300
309
|
include_headline_search: NotRequired[bool]
|
|
301
310
|
exclude_title: NotRequired[list[str]]
|
|
302
311
|
# Only people whose job at the company started in the last 90 days. It covers the jobs
|
|
@@ -95,8 +95,8 @@ class Person(BlitzModel):
|
|
|
95
95
|
full_name: str | None = None
|
|
96
96
|
nickname: str | None = None
|
|
97
97
|
civility_title: str | None = None
|
|
98
|
-
#: Built from the
|
|
99
|
-
#: the free-text headline
|
|
98
|
+
#: Built from the first entry of ``experiences`` (the matched position on the searches)
|
|
99
|
+
#: as ``"<job title> | @<employer>"``, not the free-text headline on the LinkedIn profile.
|
|
100
100
|
headline: str | None = None
|
|
101
101
|
about_me: str | None = None
|
|
102
102
|
location: Location | None = None
|
|
@@ -104,12 +104,11 @@ class Person(BlitzModel):
|
|
|
104
104
|
connections_count: int | None = None
|
|
105
105
|
#: Always ``None`` since 2026-09-15; the API keeps the key so clients don't break.
|
|
106
106
|
profile_picture_url: str | None = None
|
|
107
|
-
#: Positions from the person's profile
|
|
108
|
-
#:
|
|
109
|
-
#:
|
|
110
|
-
#:
|
|
111
|
-
#:
|
|
112
|
-
#: rather than assuming index 0 is the current role.
|
|
107
|
+
#: Positions from the person's profile. ``search.people``, ``search.employee_finder`` and
|
|
108
|
+
#: ``search.waterfall_icp`` return exactly one: the position that matched, which can be a
|
|
109
|
+
#: past one with ``include_past_jobs`` (read ``job_is_current``). ``enrichment.person``,
|
|
110
|
+
#: ``enrichment.email_to_person`` and ``enrichment.phone_to_person`` return the whole
|
|
111
|
+
#: career, in profile order.
|
|
113
112
|
experiences: BlitzList[Experience] = []
|
|
114
113
|
education: BlitzList[Education] = []
|
|
115
114
|
skills: BlitzList[str] = []
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
__version__ = "4.1.0" # x-release-please-version
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|