blitz-api-py 4.2.0__tar.gz → 4.4.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 (52) hide show
  1. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/CHANGELOG.md +19 -0
  2. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/PKG-INFO +65 -4
  3. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/README.md +64 -3
  4. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_exceptions.py +6 -4
  5. blitz_api_py-4.4.0/src/blitz_api/_version.py +1 -0
  6. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/search.py +22 -4
  7. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/search.py +22 -4
  8. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/__init__.py +6 -0
  9. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/_models.py +3 -2
  10. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/enums.py +1 -0
  11. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/filters.py +70 -12
  12. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/shared.py +8 -0
  13. blitz_api_py-4.2.0/src/blitz_api/_version.py +0 -1
  14. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/.gitignore +0 -0
  15. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/LICENSE +0 -0
  16. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/pyproject.toml +0 -0
  17. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/__init__.py +0 -0
  18. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_base_client.py +0 -0
  19. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_client.py +0 -0
  20. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_client_async.py +0 -0
  21. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_client_sync.py +0 -0
  22. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_compat.py +0 -0
  23. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_constants.py +0 -0
  24. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_pagination_async.py +0 -0
  25. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_pagination_base.py +0 -0
  26. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_pagination_sync.py +0 -0
  27. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_rate_limit.py +0 -0
  28. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_rate_limit_async.py +0 -0
  29. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  30. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/py.typed +0 -0
  31. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/__init__.py +0 -0
  32. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  33. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/account.py +0 -0
  34. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/changelog.py +0 -0
  35. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/company.py +0 -0
  36. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/enrichment.py +0 -0
  37. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  38. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_async/utils.py +0 -0
  39. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  40. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/account.py +0 -0
  41. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
  42. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/company.py +0 -0
  43. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/enrichment.py +0 -0
  44. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  45. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  46. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/account.py +0 -0
  47. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/changelog.py +0 -0
  48. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/company.py +0 -0
  49. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/enrichment.py +0 -0
  50. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/jobs.py +0 -0
  51. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/search.py +0 -0
  52. {blitz_api_py-4.2.0 → blitz_api_py-4.4.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.4.0](https://github.com/api-blitz/blitz-api-py/compare/v4.3.0...v4.4.0) (2026-11-18)
4
+
5
+
6
+ ### Features
7
+
8
+ * add geo exclude filters, people job_description, jobs company.mx and revenue_range ([#42](https://github.com/api-blitz/blitz-api-py/issues/42)) ([bf2814f](https://github.com/api-blitz/blitz-api-py/commit/bf2814f6ce77baa2b13f5aa3364a6912994139a3))
9
+
10
+ ## [4.3.0](https://github.com/api-blitz/blitz-api-py/compare/v4.2.0...v4.3.0) (2026-11-18)
11
+
12
+
13
+ ### Features
14
+
15
+ * add employee_finder job filters and job_duration_months ([#40](https://github.com/api-blitz/blitz-api-py/issues/40)) ([447565c](https://github.com/api-blitz/blitz-api-py/commit/447565cff93d394037814e7a0b223e257735d4f9))
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * add the Artificial Intelligence industry to the generated enums ([#39](https://github.com/api-blitz/blitz-api-py/issues/39)) ([4d41d29](https://github.com/api-blitz/blitz-api-py/commit/4d41d2923e3d219beca2c05cf9849d7c840da658))
21
+
3
22
  ## [4.2.0](https://github.com/api-blitz/blitz-api-py/compare/v4.1.0...v4.2.0) (2026-10-27)
4
23
 
5
24
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 4.2.0
3
+ Version: 4.4.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
@@ -169,7 +169,15 @@ Person(
169
169
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
170
170
  # Only the position that matched your filters — `job_is_current` says whether it
171
171
  # is current (past jobs are searched only with `include_past_jobs`).
172
- experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
172
+ # `job_duration_months` counts the months in the position.
173
+ experiences=[
174
+ Experience(
175
+ job_title="VP of Engineering",
176
+ company_name="Acme",
177
+ job_is_current=True,
178
+ job_duration_months=19,
179
+ )
180
+ ],
173
181
  # first_name, last_name, skills, education, certifications, … also present
174
182
  )
175
183
  ```
@@ -272,6 +280,58 @@ Where the flags go depends on the route, and the API rejects a flag in the wrong
272
280
  | `search.employee_finder` | top-level argument | — |
273
281
  | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
274
282
 
283
+ ### Countries, continents and sales regions
284
+
285
+ `country_code`, `continent` and `sales_region` take `include` and `exclude` lists in
286
+ `people["location"]`, in `company["hq"]` and in the `location` of a waterfall tier. `exclude`
287
+ never drops a record with no value on file, and a plain list is still accepted and read as
288
+ `include`. A country code has two letters, in any letter case, and `UK` is read as `GB`. A
289
+ value of any other length is a `422`, except `WORLD` in the codes to keep, which means every
290
+ country.
291
+
292
+ ```python
293
+ # People in Europe, outside France and Germany, whose job description mentions outbound.
294
+ page = client.search.people(
295
+ company={"hq": {"sales_region": {"exclude": ["APAC"]}}},
296
+ people={
297
+ "job_description": {"include": ["outbound prospecting"], "exclude": ["internship"]},
298
+ "location": {
299
+ "continent": {"include": ["Europe"]},
300
+ "country_code": {"exclude": ["FR", "DE"]},
301
+ },
302
+ },
303
+ )
304
+ ```
305
+
306
+ `people["job_description"]` on `search.people` and `company.tam_by_people` matches phrases
307
+ against the description of the job (`include` up to 50 phrases, `exclude` up to 20), and
308
+ `company["mx"]` also filters `jobs.search` and `company.tam_by_jobs`. Each company carries
309
+ `revenue_range`, the label of its yearly revenue band (`None` when the band is unknown).
310
+
311
+ `search.employee_finder` also takes `job_title` and `job_description`, each a dict with
312
+ `include` and `exclude` lists of phrases. They are matched against the person's current job
313
+ at the company, the same job as `job_level`, `job_function` and `is_recent_hire`. Wrap a
314
+ `job_title` phrase in `[brackets]` to match the whole title exactly; `job_description` has
315
+ no exact match. Each list takes up to 50 phrases (`job_description["exclude"]`: 20).
316
+
317
+ ```python
318
+ # Sales leaders at one company whose job description mentions Salesforce, interns left out.
319
+ employees = client.search.employee_finder(
320
+ company_linkedin_url="https://www.linkedin.com/company/openai",
321
+ job_title={"include": ["[Head of Sales]", "Account Executive"], "exclude": ["Intern"]},
322
+ job_description={"include": ["Salesforce"]},
323
+ )
324
+ for person in employees.auto_paging_iter(max_items=100):
325
+ job = person.experiences[0] if person.experiences else None
326
+ if job:
327
+ print(person.full_name, job.job_title, job.job_duration_months)
328
+ ```
329
+
330
+ Every `experiences[]` entry carries `job_duration_months`: the number of months in the
331
+ position, up to the current month for a current position and up to `job_end_date` for a past
332
+ one (the start and end months both count). It is `None` when `job_start_date` is missing, or
333
+ when a past position has no `job_end_date`.
334
+
275
335
  Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
276
336
  *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
277
337
  companies with none.
@@ -352,8 +412,9 @@ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pa
352
412
  print(page.fair_usage.records_used if page.fair_usage else None)
353
413
  ```
354
414
 
355
- `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
356
- resets without a second call:
415
+ Every `APIStatusError` carries the block of the error body in `err.fair_usage` (`None`
416
+ when the body has none). On an error only `request_id` and `records_used` are always set.
417
+ On an `InsufficientRecordsError` (`402`) it also says when the balance resets:
357
418
 
358
419
  ```python
359
420
  except InsufficientRecordsError as err:
@@ -138,7 +138,15 @@ Person(
138
138
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
139
139
  # Only the position that matched your filters — `job_is_current` says whether it
140
140
  # is current (past jobs are searched only with `include_past_jobs`).
141
- experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
141
+ # `job_duration_months` counts the months in the position.
142
+ experiences=[
143
+ Experience(
144
+ job_title="VP of Engineering",
145
+ company_name="Acme",
146
+ job_is_current=True,
147
+ job_duration_months=19,
148
+ )
149
+ ],
142
150
  # first_name, last_name, skills, education, certifications, … also present
143
151
  )
144
152
  ```
@@ -241,6 +249,58 @@ Where the flags go depends on the route, and the API rejects a flag in the wrong
241
249
  | `search.employee_finder` | top-level argument | — |
242
250
  | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
243
251
 
252
+ ### Countries, continents and sales regions
253
+
254
+ `country_code`, `continent` and `sales_region` take `include` and `exclude` lists in
255
+ `people["location"]`, in `company["hq"]` and in the `location` of a waterfall tier. `exclude`
256
+ never drops a record with no value on file, and a plain list is still accepted and read as
257
+ `include`. A country code has two letters, in any letter case, and `UK` is read as `GB`. A
258
+ value of any other length is a `422`, except `WORLD` in the codes to keep, which means every
259
+ country.
260
+
261
+ ```python
262
+ # People in Europe, outside France and Germany, whose job description mentions outbound.
263
+ page = client.search.people(
264
+ company={"hq": {"sales_region": {"exclude": ["APAC"]}}},
265
+ people={
266
+ "job_description": {"include": ["outbound prospecting"], "exclude": ["internship"]},
267
+ "location": {
268
+ "continent": {"include": ["Europe"]},
269
+ "country_code": {"exclude": ["FR", "DE"]},
270
+ },
271
+ },
272
+ )
273
+ ```
274
+
275
+ `people["job_description"]` on `search.people` and `company.tam_by_people` matches phrases
276
+ against the description of the job (`include` up to 50 phrases, `exclude` up to 20), and
277
+ `company["mx"]` also filters `jobs.search` and `company.tam_by_jobs`. Each company carries
278
+ `revenue_range`, the label of its yearly revenue band (`None` when the band is unknown).
279
+
280
+ `search.employee_finder` also takes `job_title` and `job_description`, each a dict with
281
+ `include` and `exclude` lists of phrases. They are matched against the person's current job
282
+ at the company, the same job as `job_level`, `job_function` and `is_recent_hire`. Wrap a
283
+ `job_title` phrase in `[brackets]` to match the whole title exactly; `job_description` has
284
+ no exact match. Each list takes up to 50 phrases (`job_description["exclude"]`: 20).
285
+
286
+ ```python
287
+ # Sales leaders at one company whose job description mentions Salesforce, interns left out.
288
+ employees = client.search.employee_finder(
289
+ company_linkedin_url="https://www.linkedin.com/company/openai",
290
+ job_title={"include": ["[Head of Sales]", "Account Executive"], "exclude": ["Intern"]},
291
+ job_description={"include": ["Salesforce"]},
292
+ )
293
+ for person in employees.auto_paging_iter(max_items=100):
294
+ job = person.experiences[0] if person.experiences else None
295
+ if job:
296
+ print(person.full_name, job.job_title, job.job_duration_months)
297
+ ```
298
+
299
+ Every `experiences[]` entry carries `job_duration_months`: the number of months in the
300
+ position, up to the current month for a current position and up to `job_end_date` for a past
301
+ one (the start and end months both count). It is `None` when `job_start_date` is missing, or
302
+ when a past position has no `job_end_date`.
303
+
244
304
  Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
245
305
  *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
246
306
  companies with none.
@@ -321,8 +381,9 @@ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pa
321
381
  print(page.fair_usage.records_used if page.fair_usage else None)
322
382
  ```
323
383
 
324
- `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
325
- resets without a second call:
384
+ Every `APIStatusError` carries the block of the error body in `err.fair_usage` (`None`
385
+ when the body has none). On an error only `request_id` and `records_used` are always set.
386
+ On an `InsufficientRecordsError` (`402`) it also says when the balance resets:
326
387
 
327
388
  ```python
328
389
  except InsufficientRecordsError as err:
@@ -31,9 +31,10 @@ if TYPE_CHECKING:
31
31
  def _parse_fair_usage(body: Any) -> FairUsage | None:
32
32
  """Pull the ``fair_usage`` block out of an error body, if the API sent one.
33
33
 
34
- The API attaches it to ``402`` responses, so a caller who runs out of records can
35
- read ``next_reset_at`` off the exception. Never raises: a malformed block just
36
- yields ``None`` rather than masking the original API error.
34
+ Since 2026-11-17 the API attaches it to every JSON error body (before, only to
35
+ ``402``), with ``records_used`` and ``request_id`` always set. A caller who runs out of
36
+ records can read ``next_reset_at`` off the exception. Never raises: a malformed block
37
+ just yields ``None`` rather than masking the original API error.
37
38
  """
38
39
  if not isinstance(body, dict):
39
40
  return None
@@ -98,7 +99,8 @@ class APIStatusError(BlitzError):
98
99
  message: A human-readable message extracted from the body when present.
99
100
  request_id: The value of the ``x-request-id`` response header, if any.
100
101
  fair_usage: The :class:`~blitz_api.types.FairUsage` block from the body, when
101
- the API sent one (it does on ``402``); ``None`` otherwise.
102
+ the API sent one (it does in every JSON error body); ``None`` otherwise. On an
103
+ error only ``records_used`` and ``request_id`` are always set.
102
104
  response: The underlying :class:`httpx.Response`.
103
105
  """
104
106
 
@@ -0,0 +1 @@
1
+ __version__ = "4.4.0" # x-release-please-version
@@ -12,6 +12,7 @@ from ...types.filters import (
12
12
  ContinentValue,
13
13
  JobFunctionValue,
14
14
  JobLevelValue,
15
+ KeywordFilter,
15
16
  PeopleCompanyFilter,
16
17
  PeopleFilter,
17
18
  SalesRegionValue,
@@ -84,6 +85,8 @@ class AsyncSearchResource:
84
85
  sales_region: list[SalesRegionValue] | None = None,
85
86
  job_level: list[JobLevelValue] | None = None,
86
87
  job_function: list[JobFunctionValue] | None = None,
88
+ job_title: KeywordFilter | None = None,
89
+ job_description: KeywordFilter | None = None,
87
90
  min_connections_count: int | None = None,
88
91
  is_recent_hire: bool | None = None,
89
92
  max_results: int | None = None,
@@ -92,11 +95,24 @@ class AsyncSearchResource:
92
95
  ) -> AsyncPageNumberPage[Person]:
93
96
  """Search employees at a single company, with page-based pagination.
94
97
 
95
- ``is_recent_hire=True`` keeps only people whose **current** job at the company
96
- started in the last 90 days (that job must also match ``job_level`` and
97
- ``job_function``; a job with no start date never matches).
98
+ ``job_level``, ``job_function``, ``job_title``, ``job_description`` and
99
+ ``is_recent_hire`` must all hold in the same job: the person's **current** job at
100
+ the company.
98
101
 
99
- Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
102
+ ``job_title`` and ``job_description`` each take ``include`` / ``exclude`` lists of
103
+ phrases. A title matches when it has every word of at least one ``include`` phrase;
104
+ wrap a phrase in brackets (``"[Head of Sales]"``) to match the whole title exactly,
105
+ ignoring case and accents. A description matches when every word of a phrase appears
106
+ in it, in any order (only its first 10,000 characters are searched); brackets give
107
+ no exact match there. ``exclude`` drops a job that matches any phrase, and
108
+ ``job_description["exclude"]`` never drops a job with no description.
109
+
110
+ ``is_recent_hire=True`` keeps only people whose job started in the last 90 days (a
111
+ job with no start date never matches).
112
+
113
+ Each list is capped at 50 entries, except ``job_description["exclude"]`` (20); a
114
+ longer one is a ``422``. ``country_code`` takes two-letter ISO 3166-1 codes in any
115
+ letter case (``UK`` is read as ``GB``; a value of any other length is a ``422``). It
100
116
  defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
101
117
  filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
102
118
 
@@ -110,6 +126,8 @@ class AsyncSearchResource:
110
126
  "sales_region": sales_region,
111
127
  "job_level": job_level,
112
128
  "job_function": job_function,
129
+ "job_title": job_title,
130
+ "job_description": job_description,
113
131
  "min_connections_count": min_connections_count,
114
132
  "is_recent_hire": is_recent_hire,
115
133
  "max_results": max_results,
@@ -14,6 +14,7 @@ from ...types.filters import (
14
14
  ContinentValue,
15
15
  JobFunctionValue,
16
16
  JobLevelValue,
17
+ KeywordFilter,
17
18
  PeopleCompanyFilter,
18
19
  PeopleFilter,
19
20
  SalesRegionValue,
@@ -86,6 +87,8 @@ class SearchResource:
86
87
  sales_region: list[SalesRegionValue] | None = None,
87
88
  job_level: list[JobLevelValue] | None = None,
88
89
  job_function: list[JobFunctionValue] | None = None,
90
+ job_title: KeywordFilter | None = None,
91
+ job_description: KeywordFilter | None = None,
89
92
  min_connections_count: int | None = None,
90
93
  is_recent_hire: bool | None = None,
91
94
  max_results: int | None = None,
@@ -94,11 +97,24 @@ class SearchResource:
94
97
  ) -> PageNumberPage[Person]:
95
98
  """Search employees at a single company, with page-based pagination.
96
99
 
97
- ``is_recent_hire=True`` keeps only people whose **current** job at the company
98
- started in the last 90 days (that job must also match ``job_level`` and
99
- ``job_function``; a job with no start date never matches).
100
+ ``job_level``, ``job_function``, ``job_title``, ``job_description`` and
101
+ ``is_recent_hire`` must all hold in the same job: the person's **current** job at
102
+ the company.
100
103
 
101
- Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
104
+ ``job_title`` and ``job_description`` each take ``include`` / ``exclude`` lists of
105
+ phrases. A title matches when it has every word of at least one ``include`` phrase;
106
+ wrap a phrase in brackets (``"[Head of Sales]"``) to match the whole title exactly,
107
+ ignoring case and accents. A description matches when every word of a phrase appears
108
+ in it, in any order (only its first 10,000 characters are searched); brackets give
109
+ no exact match there. ``exclude`` drops a job that matches any phrase, and
110
+ ``job_description["exclude"]`` never drops a job with no description.
111
+
112
+ ``is_recent_hire=True`` keeps only people whose job started in the last 90 days (a
113
+ job with no start date never matches).
114
+
115
+ Each list is capped at 50 entries, except ``job_description["exclude"]`` (20); a
116
+ longer one is a ``422``. ``country_code`` takes two-letter ISO 3166-1 codes in any
117
+ letter case (``UK`` is read as ``GB``; a value of any other length is a ``422``). It
102
118
  defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
103
119
  filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
104
120
 
@@ -112,6 +128,8 @@ class SearchResource:
112
128
  "sales_region": sales_region,
113
129
  "job_level": job_level,
114
130
  "job_function": job_function,
131
+ "job_title": job_title,
132
+ "job_description": job_description,
115
133
  "min_connections_count": min_connections_count,
116
134
  "is_recent_hire": is_recent_hire,
117
135
  "max_results": max_results,
@@ -47,6 +47,8 @@ from .filters import (
47
47
  CompanyHQFilter,
48
48
  CompanySizeFilter,
49
49
  CompanyTypeFilter,
50
+ ContinentFilter,
51
+ CountryCodeFilter,
50
52
  DatePostedFilter,
51
53
  EmploymentTypeFilter,
52
54
  IndustryFilter,
@@ -64,6 +66,7 @@ from .filters import (
64
66
  PeopleJobTitleFilter,
65
67
  PeopleLocationFilter,
66
68
  RangeFilter,
69
+ SalesRegionFilter,
67
70
  SearchPeopleFilter,
68
71
  SeniorityFilter,
69
72
  TamJobFilter,
@@ -120,6 +123,9 @@ __all__ = [
120
123
  "MxProviderFilter",
121
124
  "MxFilter",
122
125
  "RangeFilter",
126
+ "CountryCodeFilter",
127
+ "ContinentFilter",
128
+ "SalesRegionFilter",
123
129
  "CompanyHQFilter",
124
130
  "CompanyFilter",
125
131
  "PeopleJobTitleFilter",
@@ -46,8 +46,9 @@ class FairUsageRateLimit(BlitzModel):
46
46
  class FairUsage(BlitzModel):
47
47
  """Record usage, rate limit, and tracing data for a single request.
48
48
 
49
- Returned by every ``/v2`` endpoint on success, and on the ``402``
50
- insufficient-balance error (:attr:`~blitz_api.APIStatusError.fair_usage`).
49
+ Returned by every ``/v2`` endpoint on success, and since 2026-11-17 in every JSON error
50
+ body (:attr:`~blitz_api.APIStatusError.fair_usage`). On an error only ``records_used``
51
+ and ``request_id`` are always set; the other fields can be ``None``.
51
52
  """
52
53
 
53
54
  #: Records this request consumed, after reconciliation against the results
@@ -54,6 +54,7 @@ class Industry(str, Enum):
54
54
  ARCHITECTURAL_AND_STRUCTURAL_METAL_MANUFACTURING = 'Architectural and Structural Metal Manufacturing'
55
55
  ARCHITECTURE_AND_PLANNING = 'Architecture and Planning'
56
56
  ARMED_FORCES = 'Armed Forces'
57
+ ARTIFICIAL_INTELLIGENCE = 'Artificial Intelligence'
57
58
  ARTIFICIAL_RUBBER_AND_SYNTHETIC_FIBER_MANUFACTURING = 'Artificial Rubber and Synthetic Fiber Manufacturing'
58
59
  ARTISTS_AND_WRITERS = 'Artists and Writers'
59
60
  ARTS_AND_CRAFTS = 'Arts and Crafts'
@@ -129,14 +129,59 @@ class RangeFilter(TypedDict, total=False):
129
129
  max: float
130
130
 
131
131
 
132
+ class CountryCodeFilter(TypedDict, total=False):
133
+ """Include/exclude filter over country codes, in ``people.location``, ``company.hq`` and
134
+ the ``location`` of a waterfall tier.
135
+
136
+ A code is a two-letter ISO 3166-1 code such as ``"US"`` or ``"GB"``. Letter case does not
137
+ matter and ``"UK"`` is read as ``"GB"``. Since 2026-11-17 a value of any other length,
138
+ such as ``"USA"``, is rejected with a ``422`` (before, it was accepted and matched
139
+ nothing).
140
+
141
+ ``"WORLD"`` is the one exception: in ``include`` it means every country, so the country
142
+ filter is off, also when the list holds other codes. ``exclude`` does not accept it.
143
+
144
+ ``include`` never matches a record with no country on file, and ``exclude`` never drops
145
+ one.
146
+ """
147
+
148
+ include: list[str]
149
+ exclude: list[str]
150
+
151
+
152
+ class ContinentFilter(TypedDict, total=False):
153
+ """Include/exclude filter over continents. ``exclude`` never drops a record with no
154
+ continent on file.
155
+ """
156
+
157
+ include: list[ContinentValue]
158
+ exclude: list[ContinentValue]
159
+
160
+
161
+ class SalesRegionFilter(TypedDict, total=False):
162
+ """Include/exclude filter over sales regions. ``exclude`` never drops a record with no
163
+ sales region on file.
164
+ """
165
+
166
+ include: list[SalesRegionValue]
167
+ exclude: list[SalesRegionValue]
168
+
169
+
132
170
  class CompanyHQFilter(TypedDict, total=False):
133
- """Headquarters-location filter for company search."""
171
+ """Headquarters-location filter for company search. A company must match every field
172
+ you set.
173
+
174
+ ``country_code``, ``continent`` and ``sales_region`` take a dict with ``include`` and
175
+ ``exclude`` lists (since 2026-11-17). A plain list is the legacy form, still accepted: it
176
+ is read as ``include``. On ``search.people`` and ``company.tam_by_people`` the excludes
177
+ apply to the same job as your other company filters.
178
+ """
134
179
 
135
180
  city: KeywordFilter
136
181
  state: KeywordFilter
137
- country_code: list[str]
138
- continent: list[ContinentValue]
139
- sales_region: list[SalesRegionValue]
182
+ country_code: CountryCodeFilter | list[str]
183
+ continent: ContinentFilter | list[ContinentValue]
184
+ sales_region: SalesRegionFilter | list[SalesRegionValue]
140
185
 
141
186
 
142
187
  class CompanyFilter(TypedDict, total=False):
@@ -203,13 +248,17 @@ class PeopleJobTitleFilter(TypedDict, total=False):
203
248
  class PeopleLocationFilter(TypedDict, total=False):
204
249
  """Location filter for the people side of a people search, and for each waterfall tier
205
250
  (:class:`CascadeTier`). A person must match every field you set.
251
+
252
+ ``country_code``, ``continent`` and ``sales_region`` take a dict with ``include`` and
253
+ ``exclude`` lists (since 2026-11-17). A plain list is the legacy form, still accepted: it
254
+ is read as ``include``.
206
255
  """
207
256
 
208
257
  city: KeywordFilter
209
- # Codes such as ``"FR"`` or ``"GB"`` (2-3 letters, any case).
210
- country_code: list[str]
211
- continent: list[ContinentValue]
212
- sales_region: list[SalesRegionValue]
258
+ # Two-letter codes such as ``"FR"`` or ``"GB"``, any case. See :class:`CountryCodeFilter`.
259
+ country_code: CountryCodeFilter | list[str]
260
+ continent: ContinentFilter | list[ContinentValue]
261
+ sales_region: SalesRegionFilter | list[SalesRegionValue]
213
262
 
214
263
 
215
264
  class PeopleEducationFilter(KeywordFilter, total=False):
@@ -245,6 +294,13 @@ class PeopleFilter(TypedDict, total=False):
245
294
  """
246
295
 
247
296
  job_title: PeopleJobTitleFilter
297
+ # Phrases matched against the description of a job. Every word of a phrase must appear,
298
+ # in any order, and several phrases are OR-ed; only the first 10,000 characters of a
299
+ # description are searched. It applies to the same job as the job title and company
300
+ # filters. ``[brackets]`` give no exact match here. ``exclude`` drops a job whose
301
+ # description has every word of a phrase, and never drops a job with no description.
302
+ # ``include`` takes up to 50 phrases, ``exclude`` up to 20.
303
+ job_description: KeywordFilter
248
304
  job_function: list[JobFunctionValue]
249
305
  job_level: list[JobLevelValue]
250
306
  # Smallest LinkedIn connection count (0-500, ``0`` = no lower bound); above 500 is a ``422``.
@@ -351,7 +407,7 @@ class JobLocationFilter(TypedDict, total=False):
351
407
  """Location filter for a job posting (the job's location, not the company HQ)."""
352
408
 
353
409
  city: KeywordFilter
354
- country_code: KeywordFilter # ISO-3166 alpha-2 codes, matched exactly.
410
+ country_code: KeywordFilter # Two-letter ISO 3166-1 codes, any case; ``UK`` reads as ``GB``.
355
411
 
356
412
 
357
413
  class DatePostedFilter(TypedDict):
@@ -429,12 +485,12 @@ class JobCompanyHQFilter(TypedDict, total=False):
429
485
 
430
486
  city: KeywordFilter
431
487
  state: KeywordFilter
432
- country_code: KeywordFilter # ISO-3166 alpha-2 codes, matched exactly.
488
+ country_code: KeywordFilter # Two-letter ISO 3166-1 codes, any case; ``UK`` reads as ``GB``.
433
489
 
434
490
 
435
491
  class JobCompanyFilter(TypedDict, total=False):
436
- """Company-level firmographic criteria for ``jobs.search``, matched against the
437
- enriched company record behind each posting.
492
+ """Company-level firmographic criteria for ``jobs.search`` and ``company.tam_by_jobs``,
493
+ matched against the enriched company record behind each posting.
438
494
  """
439
495
 
440
496
  # ``True`` = only staffing/recruitment agencies, ``False`` = exclude confirmed
@@ -445,3 +501,5 @@ class JobCompanyFilter(TypedDict, total=False):
445
501
  size: CompanySizeFilter
446
502
  keywords: KeywordFilter
447
503
  hq: JobCompanyHQFilter
504
+ # Mail provider of the company, from the MX records of its domains.
505
+ mx: MxFilter
@@ -58,6 +58,11 @@ class Experience(BlitzModel):
58
58
  job_start_date: str | None = None
59
59
  job_end_date: str | None = None
60
60
  job_is_current: bool | None = None
61
+ #: Months the person has held the position: up to the current month for a current
62
+ #: position, up to ``job_end_date`` for a past one. The start and end months both count,
63
+ #: so a position that started this month gives ``1``. ``None`` when ``job_start_date``
64
+ #: is missing, or when a past position has no ``job_end_date``.
65
+ job_duration_months: int | None = None
61
66
  #: How the role is contracted, e.g. ``"Full-time"``, ``"Contract"``, ``"Internship"``.
62
67
  job_contract_type: str | None = None
63
68
  #: Where the work is performed, e.g. ``"Remote"``, ``"Hybrid"``, ``"On-site"``.
@@ -162,6 +167,9 @@ class Company(BlitzModel):
162
167
  industry: str | None = None
163
168
  type: str | None = None
164
169
  size: str | None = None
170
+ #: Label of the yearly revenue band, such as ``"$10M-$50M"``. ``None`` when the band is
171
+ #: unknown. The ``company.revenue`` filter of ``search.companies`` matches this band.
172
+ revenue_range: str | None = None
165
173
  employees_on_linkedin: int | None = None
166
174
  followers: int | None = None
167
175
  founded_year: int | None = None
@@ -1 +0,0 @@
1
- __version__ = "4.2.0" # x-release-please-version
File without changes
File without changes