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.
Files changed (56) hide show
  1. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/CHANGELOG.md +33 -0
  2. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/PKG-INFO +41 -13
  3. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/README.md +40 -12
  4. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/__init__.py +2 -3
  5. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_async.py +11 -2
  6. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_sync.py +11 -2
  7. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_constants.py +5 -2
  8. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_exceptions.py +0 -21
  9. blitz_api_py-4.0.0/src/blitz_api/_version.py +1 -0
  10. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/changelog.py +5 -8
  11. blitz_api_py-4.0.0/src/blitz_api/resources/_async/company.py +89 -0
  12. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/enrichment.py +19 -0
  13. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/jobs.py +8 -13
  14. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/search.py +23 -52
  15. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/changelog.py +5 -8
  16. blitz_api_py-4.0.0/src/blitz_api/resources/_sync/company.py +91 -0
  17. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/enrichment.py +19 -0
  18. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/jobs.py +8 -13
  19. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/search.py +23 -52
  20. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/__init__.py +8 -1
  21. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/_models.py +26 -2
  22. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/changelog.py +4 -13
  23. blitz_api_py-4.0.0/src/blitz_api/types/company.py +49 -0
  24. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enrichment.py +12 -0
  25. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enums.py +1 -0
  26. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/filters.py +93 -23
  27. blitz_api_py-4.0.0/src/blitz_api/types/shared.py +152 -0
  28. blitz_api_py-3.0.0/src/blitz_api/_version.py +0 -1
  29. blitz_api_py-3.0.0/src/blitz_api/resources/_async/company.py +0 -55
  30. blitz_api_py-3.0.0/src/blitz_api/resources/_sync/company.py +0 -57
  31. blitz_api_py-3.0.0/src/blitz_api/types/company.py +0 -31
  32. blitz_api_py-3.0.0/src/blitz_api/types/shared.py +0 -120
  33. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/.gitignore +0 -0
  34. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/LICENSE +0 -0
  35. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/pyproject.toml +0 -0
  36. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_base_client.py +0 -0
  37. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_client.py +0 -0
  38. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_compat.py +0 -0
  39. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_async.py +0 -0
  40. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_base.py +0 -0
  41. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_sync.py +0 -0
  42. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit.py +0 -0
  43. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
  44. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  45. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/py.typed +0 -0
  46. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/__init__.py +0 -0
  47. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  48. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/account.py +0 -0
  49. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
  50. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  51. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/account.py +0 -0
  52. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  53. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/account.py +0 -0
  54. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/jobs.py +0 -0
  55. {blitz_api_py-3.0.0 → blitz_api_py-4.0.0}/src/blitz_api/types/search.py +0 -0
  56. {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.0.0
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
- headline="VP of Engineering at Acme",
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 jobs methods return an **auto-paginating page**: iterate it and the SDK
216
- fetches each subsequent page for you. `search.people`/`search.companies` and
217
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
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 (5 req/s by default; check yours via
307
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
308
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
309
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
310
- path handles that.
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
- headline="VP of Engineering at Acme",
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 jobs methods return an **auto-paginating page**: iterate it and the SDK
185
- fetches each subsequent page for you. `search.people`/`search.companies` and
186
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
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 (5 req/s by default; check yours via
276
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
277
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
278
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
279
- path handles that.
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=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, url, headers=headers, json=json_body, params=params, timeout=timeout
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=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, url, headers=headers, json=json_body, params=params, timeout=timeout
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. The API allows 5 req/s on every plan; the
23
- #: per-key value is discoverable via ``client.account.key_info()``.
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, Any
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, and the trailing slash is load-bearing.
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 = _drop_none(days=days, limit=limit)
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, Any
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 = _drop_none(job=job, company=company, max_results=max_results, cursor=cursor)
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 = _drop_none(
63
- company_linkedin_url=company_linkedin_url,
64
- job=job,
65
- max_results=max_results,
66
- cursor=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
  )