blitz-api-py 2.0.0__tar.gz → 2.1.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 (46) hide show
  1. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/CHANGELOG.md +7 -0
  2. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/PKG-INFO +15 -6
  3. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/README.md +14 -5
  4. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_client_async.py +5 -0
  5. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_client_sync.py +5 -0
  6. blitz_api_py-2.1.0/src/blitz_api/_version.py +1 -0
  7. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/__init__.py +4 -0
  8. blitz_api_py-2.1.0/src/blitz_api/resources/_async/jobs.py +70 -0
  9. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_async/search.py +10 -2
  10. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_async/utils.py +8 -4
  11. blitz_api_py-2.1.0/src/blitz_api/resources/_sync/jobs.py +72 -0
  12. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_sync/search.py +10 -2
  13. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_sync/utils.py +8 -4
  14. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/__init__.py +29 -0
  15. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/account.py +5 -2
  16. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/enrichment.py +11 -0
  17. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/enums.py +28 -0
  18. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/filters.py +97 -4
  19. blitz_api_py-2.1.0/src/blitz_api/types/jobs.py +34 -0
  20. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/shared.py +2 -1
  21. blitz_api_py-2.0.0/src/blitz_api/_version.py +0 -1
  22. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/.gitignore +0 -0
  23. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/LICENSE +0 -0
  24. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/pyproject.toml +0 -0
  25. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/__init__.py +0 -0
  26. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_base_client.py +0 -0
  27. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_client.py +0 -0
  28. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_compat.py +0 -0
  29. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_constants.py +0 -0
  30. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_exceptions.py +0 -0
  31. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_pagination_async.py +0 -0
  32. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_pagination_base.py +0 -0
  33. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_pagination_sync.py +0 -0
  34. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_rate_limit.py +0 -0
  35. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_rate_limit_async.py +0 -0
  36. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  37. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/py.typed +0 -0
  38. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  39. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_async/account.py +0 -0
  40. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_async/enrichment.py +0 -0
  41. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  42. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_sync/account.py +0 -0
  43. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/resources/_sync/enrichment.py +0 -0
  44. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/_models.py +0 -0
  45. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/search.py +0 -0
  46. {blitz_api_py-2.0.0 → blitz_api_py-2.1.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.1.0](https://github.com/api-blitz/blitz-api-py/compare/v2.0.0...v2.1.0) (2026-07-23)
4
+
5
+
6
+ ### Features
7
+
8
+ * add jobs resource with search and company endpoints ([c96e67a](https://github.com/api-blitz/blitz-api-py/commit/c96e67ad9812f6f6c46b3aa095f7ba6792ec4a81))
9
+
3
10
  ## [2.0.0](https://github.com/api-blitz/blitz-api-py/compare/v1.0.0...v2.0.0) (2026-06-19)
4
11
 
5
12
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: blitz-api-py
3
- Version: 2.0.0
3
+ Version: 2.1.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
@@ -193,12 +193,13 @@ always call the API from your backend.
193
193
 
194
194
  ## Endpoints
195
195
 
196
- All methods are grouped into four namespaces:
196
+ All methods are grouped into five namespaces:
197
197
 
198
198
  | Namespace | Methods |
199
199
  | --- | --- |
200
200
  | `client.account` | `key_info()` |
201
201
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
202
+ | `client.jobs` | `search()`, `company()` |
202
203
  | `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()` |
203
204
  | `client.utils` | `current_date()` |
204
205
 
@@ -208,14 +209,15 @@ member or a raw string.
208
209
 
209
210
  ## Pagination
210
211
 
211
- The search methods return an **auto-paginating page**: iterate it and the SDK fetches
212
- each subsequent page for you. `search.people`/`search.companies` are cursor-based;
213
- `search.employee_finder` is page-based — both behave identically here.
212
+ The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
213
+ fetches each subsequent page for you. `search.people`/`search.companies` and
214
+ `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
215
+ all behave identically here.
214
216
 
215
217
  > **`max_results` is the page size, not a total.** It's results per page, and the API
216
218
  > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
217
219
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
218
- > employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
220
+ > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
219
221
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
220
222
  > `break` out of the loop, or drive pages manually.
221
223
 
@@ -236,6 +238,13 @@ for person in client.search.people(...).auto_paging_iter(max_items=200):
236
238
  for page in client.search.companies(company={...}).iter_pages(max_pages=5):
237
239
  print(page.total_results, len(page.results), page.cursor)
238
240
 
241
+ # Jobs are cursor-paginated too — surface hiring signals matching your ICP.
242
+ for job in client.jobs.search(
243
+ job={"title": {"include": ["Head of Sales"]}, "date_posted": {"last_days": 30}},
244
+ company={"industry": {"include": ["Software Development"]}, "size": {"include": ["51-200"]}},
245
+ ).auto_paging_iter(max_items=200):
246
+ print(job.company_name, job.title, job.location.city if job.location else None)
247
+
239
248
  # Or page manually.
240
249
  page = client.search.people(people={...}, max_results=50)
241
250
  print(page.results, page.cursor)
@@ -162,12 +162,13 @@ always call the API from your backend.
162
162
 
163
163
  ## Endpoints
164
164
 
165
- All methods are grouped into four namespaces:
165
+ All methods are grouped into five namespaces:
166
166
 
167
167
  | Namespace | Methods |
168
168
  | --- | --- |
169
169
  | `client.account` | `key_info()` |
170
170
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
171
+ | `client.jobs` | `search()`, `company()` |
171
172
  | `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()` |
172
173
  | `client.utils` | `current_date()` |
173
174
 
@@ -177,14 +178,15 @@ member or a raw string.
177
178
 
178
179
  ## Pagination
179
180
 
180
- The search methods return an **auto-paginating page**: iterate it and the SDK fetches
181
- each subsequent page for you. `search.people`/`search.companies` are cursor-based;
182
- `search.employee_finder` is page-based — both behave identically here.
181
+ The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
182
+ fetches each subsequent page for you. `search.people`/`search.companies` and
183
+ `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
184
+ all behave identically here.
183
185
 
184
186
  > **`max_results` is the page size, not a total.** It's results per page, and the API
185
187
  > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
186
188
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
187
- > employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
189
+ > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
188
190
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
189
191
  > `break` out of the loop, or drive pages manually.
190
192
 
@@ -205,6 +207,13 @@ for person in client.search.people(...).auto_paging_iter(max_items=200):
205
207
  for page in client.search.companies(company={...}).iter_pages(max_pages=5):
206
208
  print(page.total_results, len(page.results), page.cursor)
207
209
 
210
+ # Jobs are cursor-paginated too — surface hiring signals matching your ICP.
211
+ for job in client.jobs.search(
212
+ job={"title": {"include": ["Head of Sales"]}, "date_posted": {"last_days": 30}},
213
+ company={"industry": {"include": ["Software Development"]}, "size": {"include": ["51-200"]}},
214
+ ).auto_paging_iter(max_items=200):
215
+ print(job.company_name, job.title, job.location.city if job.location else None)
216
+
208
217
  # Or page manually.
209
218
  page = client.search.people(people={...}, max_results=50)
210
219
  print(page.results, page.cursor)
@@ -17,6 +17,7 @@ from ._rate_limit import AsyncRateLimiter
17
17
  from .resources import (
18
18
  AsyncAccountResource,
19
19
  AsyncEnrichmentResource,
20
+ AsyncJobsResource,
20
21
  AsyncSearchResource,
21
22
  AsyncUtilsResource,
22
23
  )
@@ -155,6 +156,10 @@ class AsyncBlitzAPI(BaseClient):
155
156
  def search(self) -> AsyncSearchResource:
156
157
  return AsyncSearchResource(self)
157
158
 
159
+ @cached_property
160
+ def jobs(self) -> AsyncJobsResource:
161
+ return AsyncJobsResource(self)
162
+
158
163
  @cached_property
159
164
  def enrichment(self) -> AsyncEnrichmentResource:
160
165
  return AsyncEnrichmentResource(self)
@@ -19,6 +19,7 @@ from ._rate_limit import RateLimiter
19
19
  from .resources import (
20
20
  AccountResource,
21
21
  EnrichmentResource,
22
+ JobsResource,
22
23
  SearchResource,
23
24
  UtilsResource,
24
25
  )
@@ -157,6 +158,10 @@ class BlitzAPI(BaseClient):
157
158
  def search(self) -> SearchResource:
158
159
  return SearchResource(self)
159
160
 
161
+ @cached_property
162
+ def jobs(self) -> JobsResource:
163
+ return JobsResource(self)
164
+
160
165
  @cached_property
161
166
  def enrichment(self) -> EnrichmentResource:
162
167
  return EnrichmentResource(self)
@@ -0,0 +1 @@
1
+ __version__ = "2.1.0" # x-release-please-version
@@ -8,10 +8,12 @@ from __future__ import annotations
8
8
 
9
9
  from ._async.account import AsyncAccountResource
10
10
  from ._async.enrichment import AsyncEnrichmentResource
11
+ from ._async.jobs import AsyncJobsResource
11
12
  from ._async.search import AsyncSearchResource
12
13
  from ._async.utils import AsyncUtilsResource
13
14
  from ._sync.account import AccountResource
14
15
  from ._sync.enrichment import EnrichmentResource
16
+ from ._sync.jobs import JobsResource
15
17
  from ._sync.search import SearchResource
16
18
  from ._sync.utils import UtilsResource
17
19
 
@@ -20,6 +22,8 @@ __all__ = [
20
22
  "AsyncAccountResource",
21
23
  "SearchResource",
22
24
  "AsyncSearchResource",
25
+ "JobsResource",
26
+ "AsyncJobsResource",
23
27
  "EnrichmentResource",
24
28
  "AsyncEnrichmentResource",
25
29
  "UtilsResource",
@@ -0,0 +1,70 @@
1
+ """The Jobs resource: ``client.jobs``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING, Any
6
+
7
+ from ..._compat import TimeoutParam
8
+ from ..._pagination_async import AsyncCursorPage
9
+ from ...types.filters import JobCompanyFilter, JobFilter
10
+ from ...types.jobs import Job
11
+
12
+ if TYPE_CHECKING:
13
+ from ..._client import AsyncBlitzAPI
14
+
15
+ _SEARCH = "/v2/jobs/search"
16
+ _COMPANY = "/v2/jobs/company"
17
+
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
+ class AsyncJobsResource:
25
+ def __init__(self, client: AsyncBlitzAPI) -> None:
26
+ self._client = client
27
+
28
+ async def search(
29
+ self,
30
+ *,
31
+ job: JobFilter | None = None,
32
+ company: JobCompanyFilter | None = None,
33
+ max_results: int | None = None,
34
+ cursor: str | None = None,
35
+ timeout: TimeoutParam = None,
36
+ ) -> AsyncCursorPage[Job]:
37
+ """Search live job postings across companies, combining job-level filters
38
+ with company firmographics.
39
+
40
+ Auto-paginates over every matching job when the result is iterated; use
41
+ ``.iter_pages()`` or the ``cursor=`` arg for manual control.
42
+ """
43
+ body = _drop_none(job=job, company=company, max_results=max_results, cursor=cursor)
44
+ return await self._client._request(
45
+ "POST", _SEARCH, body=body, cast_to=AsyncCursorPage[Job], timeout=timeout
46
+ )
47
+
48
+ async def company(
49
+ self,
50
+ *,
51
+ company_linkedin_url: str,
52
+ job: JobFilter | None = None,
53
+ max_results: int | None = None,
54
+ cursor: str | None = None,
55
+ timeout: TimeoutParam = None,
56
+ ) -> AsyncCursorPage[Job]:
57
+ """List job postings at a single company, scoped by its LinkedIn company URL.
58
+
59
+ Auto-paginates over every matching job; use ``.iter_pages()`` or ``cursor=``
60
+ for manual control.
61
+ """
62
+ body = _drop_none(
63
+ company_linkedin_url=company_linkedin_url,
64
+ job=job,
65
+ max_results=max_results,
66
+ cursor=cursor,
67
+ )
68
+ return await self._client._request(
69
+ "POST", _COMPANY, body=body, cast_to=AsyncCursorPage[Job], timeout=timeout
70
+ )
@@ -141,12 +141,20 @@ class AsyncSearchResource:
141
141
  *,
142
142
  company_linkedin_url: str,
143
143
  cascade: list[CascadeTier],
144
+ profile_min_connections: int | None = None,
144
145
  max_results: int | None = None,
145
146
  timeout: TimeoutParam = None,
146
147
  ) -> WaterfallIcpResponse:
147
- """Find the best decision-maker at a company via a prioritized cascade."""
148
+ """Find the best decision-maker at a company via a prioritized cascade.
149
+
150
+ ``profile_min_connections`` sets the minimum LinkedIn connections for a match
151
+ (server defaults to 200 when omitted).
152
+ """
148
153
  body = _drop_none(
149
- company_linkedin_url=company_linkedin_url, cascade=cascade, max_results=max_results
154
+ company_linkedin_url=company_linkedin_url,
155
+ cascade=cascade,
156
+ profile_min_connections=profile_min_connections,
157
+ max_results=max_results,
150
158
  )
151
159
  return await self._client._request(
152
160
  "POST", _WATERFALL, body=body, cast_to=WaterfallIcpResponse, timeout=timeout
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from typing import TYPE_CHECKING
5
+ from typing import TYPE_CHECKING, Any
6
6
 
7
7
  from ..._compat import TimeoutParam
8
8
  from ...types.utils import CurrentDateResponse
@@ -18,13 +18,17 @@ class AsyncUtilsResource:
18
18
  self._client = client
19
19
 
20
20
  async def current_date(
21
- self, *, region: str, timeout: TimeoutParam = None
21
+ self, *, region: str | None = None, timeout: TimeoutParam = None
22
22
  ) -> CurrentDateResponse:
23
- """Get the current server date/time for an IANA timezone (e.g. ``America/New_York``)."""
23
+ """Get the current server date/time for an IANA timezone (e.g. ``America/New_York``).
24
+
25
+ ``region`` is optional; the server defaults to ``America/New_York`` when omitted.
26
+ """
27
+ body: dict[str, Any] = {} if region is None else {"region": region}
24
28
  return await self._client._request(
25
29
  "POST",
26
30
  _CURRENT_DATE,
27
- body={"region": region},
31
+ body=body,
28
32
  cast_to=CurrentDateResponse,
29
33
  timeout=timeout,
30
34
  )
@@ -0,0 +1,72 @@
1
+ # This file is @generated by scripts/gen_sync.py from src/blitz_api/resources/_async/jobs.py.
2
+ # Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
3
+ """The Jobs resource: ``client.jobs``."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import TYPE_CHECKING, Any
8
+
9
+ from ..._compat import TimeoutParam
10
+ from ..._pagination_sync import CursorPage
11
+ from ...types.filters import JobCompanyFilter, JobFilter
12
+ from ...types.jobs import Job
13
+
14
+ if TYPE_CHECKING:
15
+ from ..._client import BlitzAPI
16
+
17
+ _SEARCH = "/v2/jobs/search"
18
+ _COMPANY = "/v2/jobs/company"
19
+
20
+
21
+ def _drop_none(**kwargs: Any) -> dict[str, Any]:
22
+ """Build a request body keeping only the arguments the caller provided."""
23
+ return {key: value for key, value in kwargs.items() if value is not None}
24
+
25
+
26
+ class JobsResource:
27
+ def __init__(self, client: BlitzAPI) -> None:
28
+ self._client = client
29
+
30
+ def search(
31
+ self,
32
+ *,
33
+ job: JobFilter | None = None,
34
+ company: JobCompanyFilter | None = None,
35
+ max_results: int | None = None,
36
+ cursor: str | None = None,
37
+ timeout: TimeoutParam = None,
38
+ ) -> CursorPage[Job]:
39
+ """Search live job postings across companies, combining job-level filters
40
+ with company firmographics.
41
+
42
+ Auto-paginates over every matching job when the result is iterated; use
43
+ ``.iter_pages()`` or the ``cursor=`` arg for manual control.
44
+ """
45
+ body = _drop_none(job=job, company=company, max_results=max_results, cursor=cursor)
46
+ return self._client._request(
47
+ "POST", _SEARCH, body=body, cast_to=CursorPage[Job], timeout=timeout
48
+ )
49
+
50
+ def company(
51
+ self,
52
+ *,
53
+ company_linkedin_url: str,
54
+ job: JobFilter | None = None,
55
+ max_results: int | None = None,
56
+ cursor: str | None = None,
57
+ timeout: TimeoutParam = None,
58
+ ) -> CursorPage[Job]:
59
+ """List job postings at a single company, scoped by its LinkedIn company URL.
60
+
61
+ Auto-paginates over every matching job; use ``.iter_pages()`` or ``cursor=``
62
+ for manual control.
63
+ """
64
+ body = _drop_none(
65
+ company_linkedin_url=company_linkedin_url,
66
+ job=job,
67
+ max_results=max_results,
68
+ cursor=cursor,
69
+ )
70
+ return self._client._request(
71
+ "POST", _COMPANY, body=body, cast_to=CursorPage[Job], timeout=timeout
72
+ )
@@ -143,12 +143,20 @@ class SearchResource:
143
143
  *,
144
144
  company_linkedin_url: str,
145
145
  cascade: list[CascadeTier],
146
+ profile_min_connections: int | None = None,
146
147
  max_results: int | None = None,
147
148
  timeout: TimeoutParam = None,
148
149
  ) -> WaterfallIcpResponse:
149
- """Find the best decision-maker at a company via a prioritized cascade."""
150
+ """Find the best decision-maker at a company via a prioritized cascade.
151
+
152
+ ``profile_min_connections`` sets the minimum LinkedIn connections for a match
153
+ (server defaults to 200 when omitted).
154
+ """
150
155
  body = _drop_none(
151
- company_linkedin_url=company_linkedin_url, cascade=cascade, max_results=max_results
156
+ company_linkedin_url=company_linkedin_url,
157
+ cascade=cascade,
158
+ profile_min_connections=profile_min_connections,
159
+ max_results=max_results,
152
160
  )
153
161
  return self._client._request(
154
162
  "POST", _WATERFALL, body=body, cast_to=WaterfallIcpResponse, timeout=timeout
@@ -4,7 +4,7 @@
4
4
 
5
5
  from __future__ import annotations
6
6
 
7
- from typing import TYPE_CHECKING
7
+ from typing import TYPE_CHECKING, Any
8
8
 
9
9
  from ..._compat import TimeoutParam
10
10
  from ...types.utils import CurrentDateResponse
@@ -20,13 +20,17 @@ class UtilsResource:
20
20
  self._client = client
21
21
 
22
22
  def current_date(
23
- self, *, region: str, timeout: TimeoutParam = None
23
+ self, *, region: str | None = None, timeout: TimeoutParam = None
24
24
  ) -> CurrentDateResponse:
25
- """Get the current server date/time for an IANA timezone (e.g. ``America/New_York``)."""
25
+ """Get the current server date/time for an IANA timezone (e.g. ``America/New_York``).
26
+
27
+ ``region`` is optional; the server defaults to ``America/New_York`` when omitted.
28
+ """
29
+ body: dict[str, Any] = {} if region is None else {"region": region}
26
30
  return self._client._request(
27
31
  "POST",
28
32
  _CURRENT_DATE,
29
- body={"region": region},
33
+ body=body,
30
34
  cast_to=CurrentDateResponse,
31
35
  timeout=timeout,
32
36
  )
@@ -14,6 +14,7 @@ from .enrichment import (
14
14
  CompanyDistributionByDepartmentItem,
15
15
  CompanyDistributionByDepartmentResponse,
16
16
  CompanyEnrichmentResponse,
17
+ DomainToLinkedinMatch,
17
18
  DomainToLinkedinResponse,
18
19
  EmailEnrichmentResponse,
19
20
  EmailMatch,
@@ -26,25 +27,38 @@ from .enums import (
26
27
  CompanyType,
27
28
  Continent,
28
29
  EmployeeRange,
30
+ EmploymentType,
29
31
  Industry,
30
32
  JobFunction,
31
33
  JobLevel,
32
34
  LastFundingType,
33
35
  SalesRegion,
36
+ Seniority,
37
+ WorkArrangement,
34
38
  )
35
39
  from .filters import (
36
40
  CascadeTier,
37
41
  CompanyFilter,
38
42
  CompanyHQFilter,
43
+ CompanySizeFilter,
39
44
  CompanyTypeFilter,
45
+ DatePostedFilter,
46
+ EmploymentTypeFilter,
40
47
  IndustryFilter,
48
+ JobCompanyFilter,
49
+ JobCompanyHQFilter,
50
+ JobFilter,
51
+ JobLocationFilter,
41
52
  KeywordFilter,
42
53
  LastFundingTypeFilter,
43
54
  PeopleFilter,
44
55
  PeopleJobTitleFilter,
45
56
  PeopleLocationFilter,
46
57
  RangeFilter,
58
+ SeniorityFilter,
59
+ WorkArrangementFilter,
47
60
  )
61
+ from .jobs import Job
48
62
  from .search import (
49
63
  WaterfallIcpMatch,
50
64
  WaterfallIcpResponse,
@@ -80,6 +94,9 @@ __all__ = [
80
94
  "SalesRegion",
81
95
  "JobFunction",
82
96
  "JobLevel",
97
+ "Seniority",
98
+ "EmploymentType",
99
+ "WorkArrangement",
83
100
  # filters
84
101
  "KeywordFilter",
85
102
  "IndustryFilter",
@@ -92,12 +109,23 @@ __all__ = [
92
109
  "PeopleLocationFilter",
93
110
  "PeopleFilter",
94
111
  "CascadeTier",
112
+ "SeniorityFilter",
113
+ "EmploymentTypeFilter",
114
+ "WorkArrangementFilter",
115
+ "JobLocationFilter",
116
+ "DatePostedFilter",
117
+ "JobFilter",
118
+ "CompanySizeFilter",
119
+ "JobCompanyHQFilter",
120
+ "JobCompanyFilter",
95
121
  # account
96
122
  "KeyInfo",
97
123
  "ActivePlan",
98
124
  # search (paginated results return the page classes exported from `blitz_api`)
99
125
  "WaterfallIcpMatch",
100
126
  "WaterfallIcpResponse",
127
+ # jobs (paginated results return the page classes exported from `blitz_api`)
128
+ "Job",
101
129
  # enrichment
102
130
  "EmailMatch",
103
131
  "EmailEnrichmentResponse",
@@ -105,6 +133,7 @@ __all__ = [
105
133
  "EmailToPersonResponse",
106
134
  "PhoneToPersonResponse",
107
135
  "CompanyEnrichmentResponse",
136
+ "DomainToLinkedinMatch",
108
137
  "DomainToLinkedinResponse",
109
138
  "LinkedinToDomainResponse",
110
139
  "CompanyDistributionByCountryItem",
@@ -2,6 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from typing import Literal
6
+
5
7
  from ._models import BlitzModel
6
8
 
7
9
  __all__ = ["ActivePlan", "KeyInfo"]
@@ -20,8 +22,9 @@ class KeyInfo(BlitzModel):
20
22
 
21
23
  valid: bool | None = None
22
24
  id: str | None = None
23
- remaining_credits: float | None = None
25
+ # A number on metered plans; the literal "unlimited" on unlimited plans.
26
+ remaining_credits: float | Literal["unlimited"] | None = None
24
27
  next_reset_at: str | None = None
25
- max_requests_per_seconds: int | None = None
28
+ max_requests_per_seconds: float | Literal["unlimited"] | None = None
26
29
  allowed_apis: list[str] = []
27
30
  active_plans: list[ActivePlan] = []
@@ -12,6 +12,7 @@ __all__ = [
12
12
  "EmailToPersonResponse",
13
13
  "PhoneToPersonResponse",
14
14
  "CompanyEnrichmentResponse",
15
+ "DomainToLinkedinMatch",
15
16
  "DomainToLinkedinResponse",
16
17
  "LinkedinToDomainResponse",
17
18
  "CompanyDistributionByCountryItem",
@@ -66,11 +67,21 @@ class CompanyEnrichmentResponse(BlitzModel):
66
67
  company: Company | None = None
67
68
 
68
69
 
70
+ class DomainToLinkedinMatch(BlitzModel):
71
+ """An additional company LinkedIn match for a domain, beyond the primary one."""
72
+
73
+ company_linkedin_url: str | None = None
74
+ company_name: str | None = None
75
+
76
+
69
77
  class DomainToLinkedinResponse(BlitzModel):
70
78
  """Result of ``enrichment.domain_to_linkedin`` (domain -> company LinkedIn URL)."""
71
79
 
72
80
  found: bool | None = None
73
81
  company_linkedin_url: str | None = None
82
+ company_name: str | None = None
83
+ # Runner-up matches when a domain resolves to more than one company.
84
+ other: list[DomainToLinkedinMatch] = []
74
85
 
75
86
 
76
87
  class LinkedinToDomainResponse(BlitzModel):
@@ -19,6 +19,9 @@ __all__ = [
19
19
  "JobFunction",
20
20
  "JobLevel",
21
21
  "LastFundingType",
22
+ "Seniority",
23
+ "EmploymentType",
24
+ "WorkArrangement",
22
25
  ]
23
26
 
24
27
 
@@ -658,3 +661,28 @@ class LastFundingType(str, Enum):
658
661
  SECONDARY_MARKET = 'Secondary market'
659
662
  INITIAL_COIN_OFFERING = 'Initial coin offering'
660
663
  POST_IPO_SECONDARY = 'Post IPO secondary'
664
+
665
+
666
+ class Seniority(str, Enum):
667
+ _0_2 = '0-2'
668
+ _2_5 = '2-5'
669
+ _5_10 = '5-10'
670
+ _10 = '10+'
671
+
672
+
673
+ class EmploymentType(str, Enum):
674
+ FULL_TIME = 'FULL_TIME'
675
+ PART_TIME = 'PART_TIME'
676
+ CONTRACTOR = 'CONTRACTOR'
677
+ TEMPORARY = 'TEMPORARY'
678
+ INTERN = 'INTERN'
679
+ VOLUNTEER = 'VOLUNTEER'
680
+ PER_DIEM = 'PER_DIEM'
681
+ OTHER = 'OTHER'
682
+
683
+
684
+ class WorkArrangement(str, Enum):
685
+ ON_SITE = 'On-site'
686
+ HYBRID = 'Hybrid'
687
+ REMOTE_OK = 'Remote OK'
688
+ REMOTE_SOLELY = 'Remote Solely'
@@ -16,11 +16,14 @@ from .enums import (
16
16
  CompanyType,
17
17
  Continent,
18
18
  EmployeeRange,
19
+ EmploymentType,
19
20
  Industry,
20
21
  JobFunction,
21
22
  JobLevel,
22
23
  LastFundingType,
23
24
  SalesRegion,
25
+ Seniority,
26
+ WorkArrangement,
24
27
  )
25
28
 
26
29
  # Each accepts an enum member (autocompleted) or a raw string, so callers are
@@ -36,6 +39,9 @@ ContinentValue = Continent | str
36
39
  SalesRegionValue = SalesRegion | str
37
40
  JobFunctionValue = JobFunction | str
38
41
  JobLevelValue = JobLevel | str
42
+ SeniorityValue = Seniority | str
43
+ EmploymentTypeValue = EmploymentType | str
44
+ WorkArrangementValue = WorkArrangement | str
39
45
 
40
46
 
41
47
  class KeywordFilter(TypedDict, total=False):
@@ -86,6 +92,7 @@ class CompanyHQFilter(TypedDict, total=False):
86
92
  class CompanyFilter(TypedDict, total=False):
87
93
  """Company search criteria, shared by ``search.companies`` and ``search.people``."""
88
94
 
95
+ # Applied on ``search.people`` only; ``search.companies`` ignores it.
89
96
  linkedin_url: list[str]
90
97
  name: KeywordFilter
91
98
  industry: IndustryFilter
@@ -119,7 +126,7 @@ class PeopleJobTitleFilter(TypedDict, total=False):
119
126
  class PeopleLocationFilter(TypedDict, total=False):
120
127
  """Location filter for the people side of a people search."""
121
128
 
122
- city: list[str]
129
+ city: KeywordFilter
123
130
  country_code: list[str]
124
131
  continent: list[ContinentValue]
125
132
  sales_region: list[SalesRegionValue]
@@ -128,6 +135,7 @@ class PeopleLocationFilter(TypedDict, total=False):
128
135
  class PeopleFilter(TypedDict, total=False):
129
136
  """People search criteria for ``search.people``."""
130
137
 
138
+ linkedin_url: list[str] # Match specific people by LinkedIn URL (server caps at 50).
131
139
  job_title: PeopleJobTitleFilter
132
140
  job_function: list[JobFunctionValue]
133
141
  job_level: list[JobLevelValue]
@@ -137,9 +145,94 @@ class PeopleFilter(TypedDict, total=False):
137
145
 
138
146
 
139
147
  class CascadeTier(TypedDict):
140
- """One tier of a waterfall ICP cascade, tried in order until results are found."""
148
+ """One tier of a waterfall ICP cascade, tried in order until results are found.
149
+
150
+ Only ``include_title`` is required; the server defaults ``location`` to worldwide
151
+ and ``include_headline_search`` to ``False`` when omitted.
152
+ """
141
153
 
142
154
  include_title: list[str]
143
- location: list[str]
144
- include_headline_search: bool
155
+ location: NotRequired[list[str]]
156
+ include_headline_search: NotRequired[bool]
145
157
  exclude_title: NotRequired[list[str]]
158
+
159
+
160
+ class SeniorityFilter(TypedDict, total=False):
161
+ """Include/exclude filter over a job's seniority band.
162
+
163
+ These are **years-of-experience** bands on the posting (``0-2``, ``2-5``,
164
+ ``5-10``, ``10+``) — unrelated to the people-side ``JobLevel`` (``C-Team``, ``VP``, ...).
165
+ """
166
+
167
+ include: list[SeniorityValue]
168
+ exclude: list[SeniorityValue]
169
+
170
+
171
+ class EmploymentTypeFilter(TypedDict, total=False):
172
+ """Include/exclude filter over the employment type a job offers."""
173
+
174
+ include: list[EmploymentTypeValue]
175
+ exclude: list[EmploymentTypeValue]
176
+
177
+
178
+ class WorkArrangementFilter(TypedDict, total=False):
179
+ """Include/exclude filter over where the work is performed."""
180
+
181
+ include: list[WorkArrangementValue]
182
+ exclude: list[WorkArrangementValue]
183
+
184
+
185
+ class JobLocationFilter(TypedDict, total=False):
186
+ """Location filter for a job posting (the job's location, not the company HQ)."""
187
+
188
+ city: KeywordFilter
189
+ country_code: KeywordFilter # ISO-3166 alpha-2 codes, matched exactly.
190
+
191
+
192
+ class DatePostedFilter(TypedDict):
193
+ """Recency filter restricting results to jobs posted within the last N days."""
194
+
195
+ last_days: int # 1-3650.
196
+
197
+
198
+ class JobFilter(TypedDict, total=False):
199
+ """Job-level search criteria, shared by ``jobs.search`` and ``jobs.company``."""
200
+
201
+ title: KeywordFilter
202
+ description: KeywordFilter
203
+ ai_keywords: KeywordFilter # Broad theme search across title, description, taxonomies.
204
+ field: KeywordFilter # Professional field or discipline. Free-form — any label.
205
+ seniority: SeniorityFilter
206
+ employment_type: EmploymentTypeFilter
207
+ work_arrangement: WorkArrangementFilter
208
+ location: JobLocationFilter
209
+ date_posted: DatePostedFilter
210
+
211
+
212
+ class CompanySizeFilter(TypedDict, total=False):
213
+ """Include-only filter over the LinkedIn size buckets. The API exposes no ``exclude``."""
214
+
215
+ include: list[EmployeeRangeValue]
216
+
217
+
218
+ class JobCompanyHQFilter(TypedDict, total=False):
219
+ """Headquarters-location filter for the company side of a job search."""
220
+
221
+ city: KeywordFilter
222
+ state: KeywordFilter
223
+ country_code: KeywordFilter # ISO-3166 alpha-2 codes, matched exactly.
224
+
225
+
226
+ class JobCompanyFilter(TypedDict, total=False):
227
+ """Company-level firmographic criteria for ``jobs.search``, matched against the
228
+ enriched company record behind each posting.
229
+ """
230
+
231
+ # ``True`` = only staffing/recruitment agencies, ``False`` = exclude confirmed
232
+ # agencies. Omit to include both.
233
+ is_agency: bool
234
+ industry: IndustryFilter
235
+ employee_count: RangeFilter
236
+ size: CompanySizeFilter
237
+ keywords: KeywordFilter
238
+ hq: JobCompanyHQFilter
@@ -0,0 +1,34 @@
1
+ """Response models for the Jobs resource.
2
+
3
+ ``jobs.search``/``jobs.company`` return ``CursorPage[Job]`` (the auto-paging cursor
4
+ page defined in :mod:`blitz_api._pagination_async` / ``_pagination_sync``), so there
5
+ is no per-endpoint response wrapper here — only the ``Job`` item model.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from ._models import BlitzModel
11
+ from .shared import Location
12
+
13
+ __all__ = [
14
+ "Job",
15
+ ]
16
+
17
+
18
+ class Job(BlitzModel):
19
+ """A single job posting returned by ``jobs.search`` and ``jobs.company``.
20
+
21
+ ``date_posted`` is the raw timestamp string the API emits (e.g.
22
+ ``"2026-07-08 23:00:07+02"`` — a space separator and a UTC offset, not ISO-8601),
23
+ so it is kept as a string rather than parsed to a ``datetime``. ``location`` reuses
24
+ the shared :class:`~blitz_api.types.shared.Location` model, of which the jobs payload
25
+ populates ``city`` and ``country_code``.
26
+ """
27
+
28
+ date_posted: str | None = None
29
+ title: str | None = None
30
+ url: str | None = None
31
+ company_name: str | None = None
32
+ company_linkedin_url: str | None = None
33
+ ai_summary: str | None = None
34
+ location: Location | None = None
@@ -49,8 +49,9 @@ class Experience(BlitzModel):
49
49
  class Education(BlitzModel):
50
50
  """A single education entry from a person's profile."""
51
51
 
52
- school: str | None = None
52
+ school_name: str | None = None
53
53
  degree: str | None = None
54
+ field_of_study: str | None = None
54
55
  start_date: str | None = None
55
56
  end_date: str | None = None
56
57
 
@@ -1 +0,0 @@
1
- __version__ = "2.0.0" # x-release-please-version
File without changes
File without changes